Merge branch 'release-1.7' of https://github.com/PowerShell/SharePoin…

…tDsc into release-1.7

Modules/SharePointDsc/SharePointDsc.psd1

@@ -113,7 +113,7 @@ PrivateData = @{
     PSData = @{
 
         # Tags applied to this module. These help with module discovery in online galleries.
-        Tags = @('DesiredStateConfiguration', 'DSC', 'DSCResourceKit', 'DSCResource', 'preview')
+        Tags = @('DesiredStateConfiguration', 'DSC', 'DSCResourceKit', 'DSCResource')
 
         # A URL to the license for this module.
         LicenseUri = 'https://github.com/PowerShell/SharePointDsc/blob/master/LICENSE'

Modules/SharePointDsc/en-US/about_SPFarm.help.txt

@@ -0,0 +1,210 @@
+.NAME
+    SPFarm
+
+# Description
+
+    This resource is used to create a new SharePoint farm and allow servers to
+    join that farm. It will detect the presence of the configuration database
+    on the SQL server as a first step, and if it does not exist then the farm
+    will be created. If the database does exist, the server will join that
+    configuration database. Once the config DB has been created, the
+    resource will install local help collections, secure resources and activate
+    features.
+
+    If the central admin site is to be running on the local server, the
+    RunCentralAdmin property should be set to true. In the event that the central
+    admin site has not been provisioned, this resource will first create it,
+    otherwise it will simply start the central admin service instance on the
+    local server.
+
+    The passphrase is passed as a Credential object.The username of this
+    credential is ignored, only the value of the password is used as the farm
+    passphrase.
+
+    The port of the Central Admin website can be set by using the
+    CentralAdministrationPort property, if this is not defined the site will be
+    provisioned on port 9999. However this setting will not impact existing
+    deployments that already have Central Admin provisioned on another port. Also
+    when a farm is created, the current behavior is to not enroll the server as a
+    cache server (which is the default behavior of SharePoint). This means you
+    need to use SPDistributedCacheService on at least one server in the farm to
+    designate it as a cache server.
+
+    CentralAdministrationAuth can be specified as "NTLM" or "KERBEROS". If not
+    specified, it defaults to NTLM. If using Kerberos, make sure to have
+    appropriate SPNs setup for Farm account and Central Administration URI.
+
+.PARAMETER Ensure
+    Key - string
+    Allowed values: Present, Absent
+    Present to create/join the farm. Absent is currently not supported
+
+.PARAMETER FarmConfigDatabaseName
+    Required - String
+    Name of the configuration database
+
+.PARAMETER DatabaseServer
+    Required - String
+    Server that will host the configuration and admin content databases
+
+.PARAMETER FarmAccount
+    Required - String
+    The account to use as the main farm account
+
+.PARAMETER Passphrase
+    Required - String
+    The passphrase to use to allow servers to join this farm
+
+.PARAMETER AdminContentDatabaseName
+    Required - String
+    The name of the admin content database
+
+.PARAMETER RunCentralAdmin
+    Required - Boolean
+    Should the central admin site run on this specific server?
+
+.PARAMETER CentralAdministrationPort
+    Write - uint32
+    What port will Central Admin be provisioned to - default is 9999
+
+.PARAMETER CentralAdministrationAuth
+    Write - String
+    Allowed values: NTLM, Kerberos
+    The authentication provider of the CentralAdministration web application
+
+.PARAMETER ServerRole
+    Write - string
+    Allowed values: Application, ApplicationWithSearch, Custom, DistributedCache, Search, SingleServer, SingleServerFarm, WebFrontEnd, WebFrontEndWithDistributedCache
+    SharePoint 2016 only - the MinRole role to enroll this server as
+
+.PARAMETER InstallAccount
+    Write - String
+    POWERSHELL 4 ONLY: The account to run this resource as, use PsDscRunAsCredential if using PowerShell 5
+
+
+.EXAMPLE
+    This example shows how a basic SharePoint farm can be created. The database server and names
+    are specified, and the accounts to run the setup as, the farm account and the passphrase are
+    all passed in to the configuration to be applied. By default the central admin site in this
+    example is provisioned to port 9999 using NTLM authentication.
+
+
+    Configuration Example 
+    {
+        param(
+            [Parameter(Mandatory = $true)]
+            [PSCredential]
+            $FarmAccount,
+
+            [Parameter(Mandatory = $true)]
+            [PSCredential]
+            $SetupAccount,
+
+            [Parameter(Mandatory = $true)]
+            [PSCredential]
+            $Passphrase
+        )
+        Import-DscResource -ModuleName SharePointDsc
+
+        node localhost {
+            SPFarm SharePointFarm
+            {
+                Ensure                    = "Present"
+                DatabaseServer            = "SQL.contoso.local\SQLINSTANCE"
+                FarmConfigDatabaseName    = "SP_Config"
+                AdminContentDatabaseName  = "SP_AdminContent"
+                Passphrase                = $Passphrase
+                FarmAccount               = $FarmAccount
+                RunCentralAdmin           = $true
+                PsDscRunAsCredential      = $SetupAccount
+            }
+        }
+    }
+
+
+.EXAMPLE
+    This example shows how a basic SharePoint farm can be created. The database server and names
+    are specified, and the accounts to run the setup as, the farm account and the passphrase are
+    all passed in to the configuration to be applied. Here the port for the central admin site to
+    run on, as well as the authentication mode for the site are also specified.
+
+
+    Configuration Example 
+    {
+        param(
+            [Parameter(Mandatory = $true)]
+            [PSCredential]
+            $FarmAccount,
+
+            [Parameter(Mandatory = $true)]
+            [PSCredential]
+            $SetupAccount,
+
+            [Parameter(Mandatory = $true)]
+            [PSCredential]
+            $Passphrase
+        )
+        Import-DscResource -ModuleName SharePointDsc
+
+        node localhost {
+            SPFarm SharePointFarm
+            {
+                Ensure                    = "Present"
+                DatabaseServer            = "SQL.contoso.local\SQLINSTANCE"
+                FarmConfigDatabaseName    = "SP_Config"
+                AdminContentDatabaseName  = "SP_AdminContent"
+                CentralAdministrationPort = 5000
+                CentralAdministrationAuth = "Kerberos"
+                Passphrase                = $Passphrase
+                FarmAccount               = $FarmAccount
+                RunCentralAdmin           = $true
+                PsDscRunAsCredential      = $SetupAccount
+            }
+        }
+    }
+
+
+.EXAMPLE 
+    This example shows how a basic SharePoint farm can be created. The database server and names
+    are specified, and the accounts to run the setup as, the farm account and the passphrase are
+    all passed in to the configuration to be applied. By default the central admin site in this
+    example is provisioned to port 9999 using NTLM authentication. In this example we also see
+    the server role defined as "Application" which tells SharePoint 2016 the role to apply to
+    this server as soon as the farm is created. This property is not supported for SharePoint 2013
+    and so this specific example would fail if used against that verison.
+
+
+    Configuration Example 
+    {
+        param(
+            [Parameter(Mandatory = $true)]
+            [PSCredential]
+            $FarmAccount,
+
+            [Parameter(Mandatory = $true)]
+            [PSCredential]
+            $SetupAccount,
+
+            [Parameter(Mandatory = $true)]
+            [PSCredential]
+            $Passphrase
+        )
+        Import-DscResource -ModuleName SharePointDsc
+
+        node localhost {
+            SPFarm SharePointFarm
+            {
+                Ensure                    = "Present"
+                DatabaseServer            = "SQL.contoso.local\SQLINSTANCE"
+                FarmConfigDatabaseName    = "SP_Config"
+                AdminContentDatabaseName  = "SP_AdminContent"
+                ServerRole                = "Application"
+                Passphrase                = $Passphrase
+                FarmAccount               = $FarmAccount
+                RunCentralAdmin           = $true
+                PsDscRunAsCredential      = $SetupAccount
+            }
+        }
+    }
+
+

Modules/SharePointDsc/en-US/about_SPFarmPropertyBag.help.txt

@@ -0,0 +1,84 @@
+.NAME
+    SPFarmPropertyBag
+
+# Description
+
+    This resource is used to work with SharePoint Property Bags at the farm level.
+    The account that runs this resource must be a farm administrator.
+
+    The default value for the Ensure parameter is Present. When not specifying this
+    parameter, the property bag is configured.
+
+.PARAMETER Key
+    Key - string
+    The key of the SPFarm property bag
+
+.PARAMETER Value
+    Write - String
+    Value of the SPfarm property bag
+
+.PARAMETER Ensure
+    Write - string
+    Allowed values: Present, Absent
+    Set to present to ensure the SPfarm property exists, or absent to ensure it is removed
+
+.PARAMETER InstallAccount
+    Write - String
+    POWERSHELL 4 ONLY: The account to run this resource as, use PsDscRunAsCredential if using PowerShell 5
+
+
+.EXAMPLE
+    This example shows how add property bag in the current farm.
+
+
+Configuration Example 
+{
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [PSCredential]
+        $SetupAccount
+    )
+
+    Import-DscResource -ModuleName SharePointDsc
+
+    node localhost 
+    {
+        SPFarmPropertyBag APPLICATION_APPCodeProperty
+        {
+            PsDscRunAsCredential = $SetupAccount
+            Key = "FARM_TYPE"
+            Value = "SearchFarm"
+            Ensure = "Present"
+        }
+    }
+}
+
+
+.EXAMPLE
+    This example shows how remove property bag in the current farm.
+
+
+Configuration Example 
+{
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [PSCredential]
+        $SetupAccount
+    )
+
+    Import-DscResource -ModuleName SharePointDsc
+
+    node localhost 
+    {
+        SPFarmPropertyBag APPLICATION_APPCodeProperty
+        {
+            PsDscRunAsCredential = $SetupAccount
+            Key = "KeyToRemove"
+            Ensure = "Absent"
+        }
+    }
+}
+
+

Modules/SharePointDsc/en-us/about_SPAccessServiceApp.help.txt

@@ -0,0 +1,89 @@
+.NAME
+    SPAccessServiceApp
+
+# Description
+
+    This resource is responsible for creating Access Services Application instances
+    within the local SharePoint farm. The resource will provision and configure the
+    Access Services Service Application.
+
+    The default value for the Ensure parameter is Present. When not specifying this
+    parameter, the service application is provisioned.
+
+.PARAMETER Name
+    Key - string
+    The name of the service application
+
+.PARAMETER ApplicationPool
+    Required - string
+    The name of the application pool to run the service app in
+
+.PARAMETER DatabaseServer
+    Required - string
+    The name of the database server to host Access Services databases
+
+.PARAMETER Ensure
+    Write - string
+    Allowed values: Present, Absent
+    Present ensures service app exists, absent ensures it is removed
+
+.PARAMETER InstallAccount
+    Write - String
+    POWERSHELL 4 ONLY: The account to run this resource as, use PsDscRunAsCredential if using PowerShell 5
+
+
+.EXAMPLE
+    This example shows how to deploy Access Services 2013 to the local SharePoint farm.
+
+
+    Configuration Example 
+    {
+        param(
+            [Parameter(Mandatory = $true)]
+            [PSCredential]
+            $SetupAccount
+        )
+        Import-DscResource -ModuleName SharePointDsc
+
+        node localhost {
+            SPAccessServiceApp AccessServices
+            {
+                Name                 = "Access Services Service Application"
+                ApplicationPool      = "SharePoint Service Applications" 
+                DatabaseServer       = "SQL.contoso.local\SQLINSTANCE"
+                PsDscRunAsCredential = $SetupAccount
+            }
+        }
+    }
+
+
+.EXAMPLE
+
+    This example shows how to remove a specific Access Services 2013 from the local 
+    SharePoint farm. Because Application pool and database server are both required
+    parameters, but are not acutally needed to remove the app, any text value can 
+    be supplied for these as they will be ignored. 
+
+
+    Configuration Example 
+    {
+        param(
+            [Parameter(Mandatory = $true)]
+            [PSCredential]
+            $SetupAccount
+        )
+        Import-DscResource -ModuleName SharePointDsc
+
+        node localhost {
+            SPAccessServiceApp AccessServices
+            {
+                Name                 = "Access Services Service Application"
+                ApplicationPool      = "n/a" 
+                DatabaseServer       = "n/a"
+                Ensure               = "Absent"
+                PsDscRunAsCredential = $SetupAccount
+            }
+        }
+    }
+
+