Five Simple But Powerful PowerShell Functions/Filters for SharePoint

To start out, a function in PowerShell is similar to a function in any other development language. (See my last post “Commands in PowerShell” for a little PowerShell basics on command and functions.) It takes zero or more inputs, runs zero or more statements and possibly returns one or more values. Functions in PowerShell are a way to gather up multiple statements into a functional, reusable piece of code. Below is a shell of a basic function in PowerShell.

Function DoThis($var)
{
<Statements>
}

What exactly is a PowerShell filter? A filter is very similar to a function with the exception of the filter keyword.

Filter DoThat($var)
{
<Statements>
}

Both functions and filters can participate in the PowerShell pipeline but they do so in slightly different ways. (To read about the pipeline.. ) The PowerShell pipeline provides the ability to stream the output of one command as input to the next command via the pipe character |. Functions (simple functions) can access the current object in the pipeline using the $Input value and run till completion. Filters access the current object in the pipeline using the $_ variable and run once per object placed in the pipeline. There is a slight but real difference between how a function and filter work but suffice it to say that in simplistic terms Filters work nicer with the pipeline . ( Ok, that is not completely true. There is a way to create a function that will work like a filter but that is not the focus of this post and using filters saves me a few lines of code.)

 

So here are my simple functions and filters that I end up using all the time.

function Get-LocalFarm
{
return [Microsoft.SharePoint.Administration.SPFarm]::Local
}

filter Get-WebService
{
$webServices = new-object Microsoft.SharePoint.Administration.SPWebServiceCollection($_)
$webServices
}

filter Get-WebApplication
{
$_.WebApplications
}

filter Get-SiteCollection
{
$_.Sites
}

filter Get-Web
{
$_.AllWebs
}

Did I not say they were simple? So what is the big deal about these function and filters? Figure 1 below displays a simple view of a SharePoint Farm object hierarchy. The above five functions and filters allow us to access all of the objects show in Figure 1.

Figure 1: Basic SharePoint Object Model Hierarchy

If you compare the function/filters from above to the hierarchy in Figure 1 you will notice that there is a corresponding filter or function for each object level.

It is very simple – Get-LocalFarm will return the SPFarm object. If you pipe the SPFarm object to Get-SPWebService you will have access to all the SPWebServices associated with the local farm. Chain all five function/filters together and the end result is ALL SPWeb objects on the farm. Since these are small reusable pieces of code you can stop the chain where it makes sense.

Before I demonstrate how you can use these filters and functions let me explain how to set these up in PowerShell.

First you must be on a WSS 3.0 or MOSS 2007 server. Since the SharePoint object model does not remote you must run these from a PowerShell instance on the server.

Next before you add the filters and functions to the PowerShell environment you must add the Microsoft.Sharepoint assembly to the PowerShell environment. To add the Microsoft.SharePoint assembly to the PowerShell environment simply run the following command in PowerShell :

[Reflection.Assembly]::Load(“Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c”)

Next copy the function and filters listed above and paste into the PowerShell command window. Since I used these all the time I have these listed in my profile.ps1 file so they load up automatically when I start PowerShell. Now you can use one or more of the function/filters to access any of the object model items shown in Figure 1.

Here are a few examples to play with:

get-localfarm
get-localfarm |get-webservice
get-localfarm |get-webservice | get-webapplication
get-localfarm |get-webservice | get-webapplication | get-sitecollection
get-localfarm |get-webservice | get-webapplication | get-sitecollection | get-web

The first example will output a text representation of the SPFarm object for the local farm.
The second example will output zero or more text representations of SPWebService objects associated with the farm. You should be able to guess the objects passed out the pipeline based on the name of the filter.

If you actually executed the last statement in the list of statements above you should have ended up with output similar to Figure 2.

Screen shot of PowerShell output displaying a SPWeb object

Figure 2 : Screen shot of get-localfarm |get-webservice | get-webapplication | get-sitecollection | get-web

In Figure 2 we see that the SPWeb objects hit the end of the pipeline and was formatted for the host providing us a view into the SPWeb object. A view such as this is not real easy to review particularly when the out scrolls off the screen. So let’s format the output so we can get a better view of the results. For an SPWeb object I like to view the URL. We can pipe the SPWeb objects to the format-table cmdlet. The new command looks like:

Get-localfarm |get-webservice | get-webapplication | get-sitecollection | get-web |format-table -property url

and the new output looks like:

Screen shot of PowerShell ouput of SPWeb objects using format table

Figure 3: SPWeb objects piped to Format-Table cmdlet

Figure 3 displays the output of the last set of commands. It shows all web objects on the farm. Although we now only see the url of each SPWeb object sent to the format-table cmdlet we have access to properties and methods of the SPWeb object. So now we have access to each SPWeb object in the farm as it passes though the pipeline. Since we have access to the actual SPWeb object we have access to all the properties and methods of that object and can script against it. That’s pretty powerful.

Right now I am sure it appears that there is a lot of noise in the output but the next post we will continue to use these filters and functions along with other PowerShell cmdlets to be more selective in the output.

One last example for you to try
(get-localfarm).solutions | format-table -property name

Yes this will output the name of all solutions installed on the farm