xSharePointProvisioning Module – PowerShell Desired State Configuration (DSC)

The xSharePointProvisioning module contains DSC resources to provision SharePoint artifacts using the Client Side Object Model (CSOM). There are two versions: one for O365 and ne for SharePoint on premise. Currently the following resources are in the package:

xList Ensure a list with a specific title and description at a given URL. If the list does not exist it will be created with the specified template.
xField Ensure that a list at a specific url has or has not a specified field.
XListItem Ensure that a list at a specific url has or has not a list item with the specified properties.

For the near future are planned to add xWeb, xFile, xCustomUserAction – depending on my time I can share for this.

Security

To use CSOM with SharePoint or O365 you have to authenticate by providing a set of valid credentials. The winmgmt service that executes the DSC configurations normally runs under the local system account – so you cannot use this account to authenticate. The only way is to pass the credentials directly to the resources. This has some security impacts. It is possible to encrypt the password in the mof files (see http://blogs.msdn.com/). But you have to export and import the public key file on all target nodes.  For quick tests it’s more convenient to save the password in plain text.

To temporarily save the password in plain text you have to set PSDscAllowPlainTextPassword to true in the configuration data.

$ConfigurationData = @{
    AllNodes = @(
        @{
            NodeName="*"
            PSDscAllowPlainTextPassword=$true
         }
        @{
            NodeName="localhost"
         }
    )
}

When I use TFS Release Management to execute my DSC configuration it does not bother me too much. The release management server copies all the files to the target machine and deletes the mof files after he is done. For O365 I go one step further. I configure a deployment machine in azure and provision the machine only for deployment. After the deployment is complete the release management server takes care of shutting down the machine.

For all other scenarios I strongly encourage you to encrypt the passwords.

Installation

To install xSharePointProvisioning module:
Unzip the content under $env:ProgramFiles\WindowsPowerShell\Modules folder

To confirm installation:
Run Get-DSCResource to see that xList, xField & xListItem are among the DSC Resources listed

Requirements

This module requires the latest version of PowerShell (v4.0, which ships in Windows 8.1 or Windows Server 2012R2). To easily use PowerShell 4.0 on older operating systems, install WMF 4.0 .  Please read the installation instructions that are present on both the download page and the release notes for WMF 4.0.

The module uses the assemblies Microsoft.SharePoint.Client and Microsoft.SharePoint.Client.Runtime. They are both loaded by their name from GAC. If you want to add the assemblies to the module you have to check for the following lines and change them to load the assemblies by a relative path (i.e. with the add-type cmdlet).

[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint.Client")
[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint.Client.Runtime") 

If you want to create the module from the source on GitHub you will also need the latest Version of xDSCResourceDesigner.

Adding or extending resources

The idea of xSharePointAdministration and xSharePointProvisioning is to create a community around them and that everyone can easily extend the module. You find a complete guide here.

If you’re missing a resource and you cannot add it yourself, then you can create an issue on GitHub.

Examples

For every resource in the module there is a test script in the git repository. The script uses global variables for the URL to the test site and for the credentials. This is the test script for the xField resource.

if (-not $Url)
{
    $Url = Read-Host "Enter the url to the test site:"
}

if (-not $Credentials)
{
    $Credentials = Get-Credential
}

$ConfigurationData = @{
    AllNodes = @(
        @{
            NodeName="*"
            PSDscAllowPlainTextPassword=$true
         }
        @{
            NodeName="localhost"
         }
    )
}


Configuration TestFieldResource
{
    param
    (
        [Parameter(Mandatory=$false)]
        [PSCredential]$Credential,

        [Parameter(Mandatory=$false)]
        [string]$Url
    )

    Import-DscResource -ModuleName xSharePointProvisioning   -Name ALIS_xField
    
    Node $AllNodes.NodeName 
    {
        xField TextField
        {
            FieldXml = "<Field Type='Text' DisplayName='My Text Field' Name='MyTextField' />"
            Url = "$Url/Lists/MyCustomList"
            Ensure = "Present"
            Credentials = $Credential
        }

        xField NoteField
        {
            FieldXml = "<Field Type='Note' DisplayName='My Note Field' Name='MyNoteField' />"
            Url = "$Url/Lists/MyCustomList"
            Ensure = "Present"
            Credentials = $Credential
        }

        xField NumberField
        {
            FieldXml = "<Field Type='Number' DisplayName='My Number Field' Name='MyNumberField' />"
            Url = "$Url/Lists/MyCustomList"
            Ensure = "Present"
            Credentials = $Credential
        }
    }
}

TestFieldResource -ConfigurationData $ConfigurationData -Url $Url -Credential $Credentials -verbose

Restart-Service Winmgmt -force

Start-DscConfiguration -Path .\TestFieldResource -Wait -Force -Verbose

Get-DscConfiguration

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s