Using Windows PowerShell to Manage SharePoint 2010

Your account must be assigned the SharePoint_Shell_Access role on any SQL Server databases against which PowerShell will be used, both configuration and content databases. Note that this role is nested into the db_owner role, which means you have full access to the database (and all site collections held within) to do whatever you like—intentionally or not!

Your account, or a group that you are a member of, must be a member of the WSS_ADMIN_WPG local group on all servers in the farm.

You must be a site collection administrator on any site collection that you will manage via PowerShell.

Using the Invoke-Command cmdlet: This lets you execute one-off commands by specifying the computer on which to run the command as a parameter.

Creating a session on a remote computer using New-PSSession, then passing that session to the Invoke-Command cmdlet: This lets you load the SharePoint snap-in and maintain session state.You can then pass SharePoint cmdlets directly through the Invoke-Command cmdlet.

As 2 above, but rather than executing commands via Invoke-Command, you import the remote session to your local session, which lets you enter native SharePoint cmdlets into your local session that execute against the remote session.

Learn the parameters. With almost all cmdlets, you need to define which object is the target by using one or more parameters. The target object could be many things, such as a web application, a content database, or a site collection. Consult the Help for a cmdlet to discover the different ways in which it can be called.
For example the syntax for Get-SPSite indicates four different ways in which it can be called. One way is to specify a content database as the target object for this cmdlet, in which case all site collections within the specified content database will be listed. You use the Get-Help cmdlet to access the Help for a cmdlet, and the -examples parameter is especially useful for finding out the different ways the cmdlet can be used.

Understand the PipeBind object. The PipeBind object type is expected for some parameters (e.g., the -Identity parameter on the Get-SPSite cmdlet). The PipeBind object type accepts multiple formats due to the fact that you can uniquely reference a SharePoint object in multiple ways. For example, you can use the URL for a site collection or its GUID (globally unique identifier). The PipeBind object type ensures that you have the flexibility to use whatever unique identifier is appropriate for the operation at hand.

Beware performance hungry operations. Many innocuous cmdlets can operate against a very large number of items. For example, the Get-SPSite cmdlet with no parameters enumerates all the site collections in the farm. Most cmdlets, therefore, have a built-in limit on the number of objects they return. You can explicitly override the limit by using the -Limit parameter, which takes a non-negative number or the word “ALL” as its value. As an example, the Get-SPSite inbuilt limit is 200.

Unsure? Use –whatif. As you execute cmdlets (especially those that do Write operations), you might want to be sure beforehand what the outcome of the operation will be. PowerShell supports a parameter called -whatif that lets you see what the operation would do if it were actually executed. This parameter is very useful for those operations where you are unsure of the target objects that will ultimately be operated on. Consider the following:

Get-SPSite –Limit 20 | Remove-SPSite –whatif

You can't know for sure what the twenty returned sites would be, so to pipe them without caution into a destructive cmdlet such as Remove-SPSite could be disastrous. The parameter -whatif is your get-out-of-jail-free card.

Know your scope and control the objects that you work with. Some cmdlets are global in execution and therefore can be run on any server in the farm (e.g., New-SPSite), whereas others are local and affect only the server upon which they’re run (e.g., Start-SPServiceInstance).

There are various ways to work with the subset of the objects that a particular cmdlet returns. First, some cmdlets let you specify parameters that limit the scope of execution to a known entity such as the farm, web application, or content database. Second, you can use client-side filtering using the where-object cmdlet in the pipeline. This lets you look at every object that's returned and process only those that match the specified criteria. All objects are returned initially, and the filtering is done on the client, which could be wasteful as far as server processing is concerned.

Finally, server-side filtering is supported by some cmdlets—usually through, but not limited to, the -Filter parameter. The -Filter parameter performs object filtering during execution of the cmdlet on the server, before the result set is sent to the client. This is much more performant than client-side filtering and is supported by the Get-SPSite cmdlet as well as others such as Get-SPWeb. The Get-SPSite, Get-SPWeb, and Get-SPSiteAdministration cmdlets also support wildcards and regular expressions via the -RegEx parameter. Both of these options result in server-side filtering, and their use is encouraged. As an example, the following commands use server-side filtering to return all the webs that have been provisioned with the Blog template and all the webs that are owned by people in the EMEA domain:

get-spsite | get-spweb –Filter \{$_.Template–eq “BLOG#0”\}get-spsite –Filter \{$_.Owner–like "EMEA*"\} | get-spweb

Use calculated properties to extract what you need. Some cmdlets return a collection of values, and you need to use these as input to a calculated property to extract the actual data you're interested in. Calculated properties are defined using a hash table that contains the Name (key) you want to give to the calculated property and the Expression (value) you want to apply to generate the calculated property. For example, the Usage attribute of the Get-SPSite cmdlet returns details about quota and actual usage. To list just the storage that's currently being used by a site collection, you would type the following:

Get-SPSite | select URL, @\{Name=”Size”;Expression=\{$_.Usage.Storage\}\}

Don’t get exhausted. From a development perspective, it's always a best practice to dispose of objects (such as site, web, and site administration objects) to avoid server memory exhaustion. The same holds true from within PowerShell if you are assigning such objects to variables for subsequent use. (Note that this particular issue doesn't occur when you use these objects interactively in the shell in a single-line command, because they will be automatically disposed of properly after that single command is complete.) As an example, the following two commands run the risk of the structures associated with the $sites variable not being disposed of correctly.
This won’t be a big issue if you're executing just a small number of commands that affect only a small number of objects, but it's an important consideration if you write scripts that run frequently and touch many objects. To properly dispose of such objects, SharePoint provides two cmdlets, Start-SPAssigment and Stop-SPAssigment. The former creates structures called assignment collectors, and the latter disposes of these structures. Your task is to let the system know when you want to create and dispose of these structures by calling the appropriate cmdlets.

The cmdlets support two modes of execution. The first uses -Global as the single parameter on both these cmdlets to indicate that you want to use the global assignment collector. This is the simplest option, and when the Start-SPAssigment cmdlet is encountered, this indicates to SharePoint to start tracking any subsequent assignments until it encounters the Stop-SPAssignment cmdlet. At this point, it disposes of all the objects that were assigned in the meantime, and any variables that contained objects will no longer be valid.

The disadvantage of doing this globally is that every object will be kept, whether assigned to a variable or not. So operations that generate a large number of objects (such as Get-SPsite -Limit ALL) will cause problems, and your shell will eventually run out of memory. SharePoint does warn you of this possibility if you attempt to execute an operation that will return a large number of objects when a global assignment collector is currently active.

The second mode of execution is to create individual assignment collectors and explicitly use these collectors when generating objects that you want to store for later manipulation. In the following example, I create an assignment collector variable called $ac that’s subsequently used to create variable $s, because I know that it will contain a large number of objects that I want to refer to later in the script. Note that the objects returned here will be disposed of automatically, so no need to worry about any assignment collectors.