Today’s post is one of my favorite new capabilities… custom parameters!  With SharePoint’s previous admin console (STSADM) you could create your own custom commands (Which you can still do with PowerShell in 2010—see Gary’s post on Custom Cmdlets for a good starting point); but these required you to create your own command entirely in code from scratch, even if existing commands got you 90% of the way.  But in 2010, you can add only the parameters you need to existing commands by wrapping the existing cmdlet inside a function.  If you use this to make your own commands, please let me know!  I’m always interested to see what other parameters people are creating for themselves.  And with that, let’s begin!

Now those of you who read my blog know that my other main area of focus is Master Page design.  I’m a big fan of scripting all my repetitive steps—so when testing a new master page I want to deploy all possible templates that exist with my master page; but when you get ahold of your SharePoint 2010 beta you’ll not find a “MasterPage” setting on the SPWeb cmdlets…  Not to worry, we can add our own!

Here’s the initial syntax of Set-SPWeb (as of the 2010 Beta):

First we need to take a copy of the New-ScriptCmdlet.ps1 file from the script library.  This is essentially a copy of James Brundage’s script from his Fun with Script Cmdlets blog post.  Essentially this script will “auto generate” a wrapper function based on the cmdlet passed into it.   For this situation I saved the New-ScrpitCmdlet.ps1 file to my C: drive and dot source the “New-ScriptCmdlet” function into my session so that I can call this command to generate the Set-SPWeb wrapper function:

PS> Get-Command Set-SPWeb | New-ScriptCmdlet Set-SPWeb | Set-Content Set-SPWeb.ps1

Now that we generated the Set-SPWeb.ps1 function that we can add our logic to!  Open up this file and you’ll see a function that has the same syntax as the cmdlet…

What we’re going to do today is add a “MasterPageRelativeUrl” to the cmdlet which takes a string to represent the relative path to the master page to apply.  First, we add the parameter to the “Param” list (I’ll highlight any “new” scripting I introduce):

param(

    [Parameter(Mandatory=$true, Position=0, ValueFromPipeline=$true)][Microsoft.SharePoint.PowerShell.SPWebPipeBind] ${Identity},

    [System.String]${RelativeUrl},

    [System.String]${Description},

    [Microsoft.SharePoint.PowerShell.SPWebTemplatePipeBind]${Template},

    [System.String]${Theme},

    [Parameter(ValueFromPipeline=$true)][Microsoft.SharePoint.PowerShell.SPAssignmentCollection]${AssignmentCollection},

    [System.String] $MasterPageRelativeURL

)

Then we need to handle this parameter being passed into the script.  Add the highlighted code to the Try block of the BEGIN section to collect the value and remove this from the parameters passed to the actual cmdlet.  Also, we need the Identity stored locally to use later so we’ll store that too:

begin

{

    try {

        $outBuffer = $null

  $m_Identity = $null; $m_MasterPage = $null;

        if ($PSBoundParameters.TryGetValue('OutBuffer', [ref]$outBuffer))

        {

            $PSBoundParameters['OutBuffer'] = 1

        }

        if ($PSBoundParameters.TryGetValue('masterpagerelativeurl', [ref]$m_MasterPage))

        {

            [void]$PSBoundParameters.Remove('masterpagerelativeurl')

            [void]$PSBoundParameters.TryGetValue('identity', [ref]$m_Identity)

        }

        $wrappedCmd = $ExecutionContext.InvokeCommand.GetCommand('Set-SPWeb', [System.Management.Automation.CommandTypes]::Cmdlet)

        $scriptCmd = {& $wrappedCmd @PSBoundParameters }

        $steppablePipeline = $scriptCmd.GetSteppablePipeline($myInvocation.CommandOrigin)

        $steppablePipeline.Begin($PSCmdlet)

    } catch {

        throw

    }

}

And the last step—we use one line of OM to set the master page on a given SPWeb object.  However, I’m going to wrap the command in a ShouldProcess and some other logic to handle poorly formed Master Page URLs. Just realize that only the line starting in Get-SPWeb is actually required.

The Process section should now look like this:

process

{

    try {

        $steppablePipeline.Process($_)

        if($pscmdlet.ShouldProcess($m_Identity.webUrl, "MasterURL=$m_MasterPage")){

        if(!($masterpage.StartsWith("/_catalogs/masterpage/"))){ Write-Warning "Master Page paths generally start with the page /_catalogs/masterpage/"; }

           Get-SPWeb $m_Identity.webURL |%{ $_.MasterUrl = $m_MasterPage; $_.Update() }

        }

    } catch {

        throw

    }

}

So now if we dot-source this new Set-SPWeb script we’ll see that the MasterPageRelativeURL is now shown!

So now I can run Set-SPWeb to change the Master Page! If I use WhatIf I’ll see two entries, once for the cmdlet and once for my custom script:

Command to change a master page:

PS C:\> Set-SPWeb http://mybrandingsite -MasterPageRelativeUrl "/_catalogs/masterpage/zcustom.master"

I've posted the final Set-SPWeb.ps1 file in the Script Library as well.

NOTE: you can still force PowerShell to use the CMDLET directly by calling “Microsoft.sharepoint.powershell\Set-SPWeb” or the Function directly using “\Set-SPWeb”.