Invoke-SPDscCommand documentation improvement

Just ran into previously described issue (because I was loading the SP PSSnapin in an external script) and found this great wiki entry: https://github.com/PowerShell/SharePointDsc/wiki/Using-the-Script-resource-in-configurations-that-use-SharePointDsc

It should be improved though as Arguments & Credential are not documented and I had to dig through source code to figure out how they work. I propose the following changes:

Script example:

Script SPDscExample
{
  GetScript = {
    Invoke-SPDscCommand -ScriptBlock {
      # your code goes here
      $params = $args[0]
      Write-Verbose $params.Foo
    } -Arguments @{ Foo = "Bar" } -Credentials (Get-Credentials)
  }
  ...
}

Additionally it should be noted that you can’t use DSC specific variables within the SPDscCommand, that means e.g. using $using:DscWorkingFolder in the script block will not work. You need to pass all external variables into SPDscCommand via its arguments.

Maybe we can even get a real wiki entry for Invoke-SPDscCommand like we have for all the resources?

[ykuijs]

I did some testing and it looks like this has something to do with the Script resource and the fact that snap-ins are loaded in a module scope. In this case inside of the module of the Script resource.

I tried to skip the Invoke-Command (when using PsDscRunAsCredential, this is not required since the resource already runs in a user context) cmdlet, but that also doesn’t work:

        Script TestAddSnapin
        {
          GetScript = {
            $SPSnapin = Get-PSSnapin Microsoft.SharePoint.PowerShell -ErrorAction SilentlyContinue
            if ($null -eq $SPSnapin) {
		        Add-PsSnapin Microsoft.SharePoint.PowerShell
            }

            Write-Verbose "Returning Farm Build Version"
            $farm = Get-SPFarm
            Write-Verbose "Version: $($farm.BuildVersion)"
            return $farm.BuildVersion
          }
          TestScript = {
            $SPSnapin = Get-PSSnapin Microsoft.SharePoint.PowerShell -ErrorAction SilentlyContinue
            if ($null -eq $SPSnapin) {
		        Add-PsSnapin Microsoft.SharePoint.PowerShell
            }

            Write-Verbose "Getting Farm"
            $farm = Get-SPFarm
            Write-Verbose "Version: $($farm.BuildVersion)"

            return $false
          }
          SetScript = {
            $SPSnapin = Get-PSSnapin Microsoft.SharePoint.PowerShell -ErrorAction SilentlyContinue
            Write-Verbose "--$SPSnapin--"
            if ($null -eq $SPSnapin) {
		        Add-PsSnapin Microsoft.SharePoint.PowerShell
            }

            Write-Verbose "Getting Farm"
            $farm = Get-SPFarm
            Write-Verbose "Version: $($farm.BuildVersion)"
          }
          PsDscRunAsCredential = $SPSetupAccount
        }

When doing a Test-DscConfiguration, this works just fine. However when doing a Start-DscConfiguration, the Test part works but the Set part fails with the “An item with the same key has already been added” error.

When using Invoke-SPDscCommand this works fine, since that method exists in a separate module (SharePointDsc) and therefore has its own scope. Loading the snap-in from that module and testing if it is already loaded works as expected.

So you can keep using Invoke-SPDscCommand or create your own module, which you call from the Script resource and does the magic for you.

[ykuijs]

Thanks for pointing this out! I have updated the example in the article.

The reason that we don’t have a real wiki article is that this function is a helper function for SharePointDsc and wasn’t created to be published (and used) outside of the module. However, due to the way modules work, we currently have no way of limiting the use of this function.

On the other hand: This is convenient because it enables the possibilities described in the wiki article you are referring to 😉