Loading the SharePoint Cmdlets

Microsoft has provided a number of SharePoint-specific Cmdlets, so you can easily manipulate SharePoint objects (applications, site collections, sites, lists, etc.) via PowerShell. These Cmdlets are available to you via a DLL plug-in, which you must enable in a regular Windows PowerShell window. If you launch the SharePoint Management Shell, the shell preloads the SharePoint Cmdlets for you. Type the following commands into your PowerShell window to see if you have the SharePoint Cmdlets loaded:

Get-PSSnapin -Registered | Where-Object { $_.Name -eq "Microsoft.SharePoint.PowerShell" }

The preceding command executes a PowerShell Cmdlet to get all registered snap-in objects, which you then pipe to another built-in Cmdlet, called Where-Object, to filter the list to a specific snap-in for SharePoint. If the SharePoint snap-in is loaded, you should see details about the registered snap-in object. If the preceding command produces no output, you can register the snap-in with the following:

Add-PSSnapin "Microsoft.SharePoint.PowerShell"

After adding the snap-in, re-run the script to check for the registered snap-in, and you should see details of the snap-in.

PowerShell Syntax

Once you start using PowerShell frequently, you will understand the terminology and syntax for PowerShell Cmdlets and script notation. PowerShell Cmdlets assume the syntax verb-prefix noun. The verb always indicates the action on the Cmdlet, and PowerShell supports the verb standards, listed in Table 3-1.

The prefix in a Cmdlet is usually a two-letter qualifier that identifies the technology; for example, PS identifies PowerShell, AD identifies Active Directory, and SP identifies SharePoint. Finally, the noun is the affected object or resource; for example, Get-SPSite calls the SharePoint Cmdlet to “get” a new SharePoint “site” object.

Exploring SharePoint Cmdlets

As I mentioned in the earlier sections, SharePoint provides a number of Cmdlets, enabling you to interface with SharePoint and configure your farm. What do you do if you want to see a list of these Cmdlets? In using STSADM, you could provide the –o parameter to see a list of operations. Fortunately, PowerShell has a nice built-in Cmdlet called Get-Command.

Executing the Get-Command Cmdlet with no parameters will list every single available Cmdlet in PowerShell—yes, all of them! Passing the –Noun parameter to the Get-Command Cmdlet allows you to filter the list by a given noun name. If you cast your memory back to the previous section, you may remember that I mentioned standard syntax includes a noun prefix to identify the technology. SharePoint prefixes all nouns with “SP,” so you can easily get a list of all SharePoint Cmdlets as follows:

Get-Command –Noun SP*

The previous command uses a wildcard character, which tells the Get-Command Cmdlet to return any Cmdlets that start with “SP” and end with any other string of characters. There is still a large number of Cmdlets listed just for SharePoint operations; the following command tells us exactly how many (my install lists over 770):

(Get-Command –Noun SP*).Count

I think you need to narrow down the list; the Get-Command Cmdlet allows you to search for specific words in the noun. For example, if you wanted to list all the Cmdlets that deal with subsites (SPWeb) objects, you would use the following syntax:

Get-Command –Noun SPWeb

Figure 3-2 shows a much smaller (and manageable) list of Cmdlets. You can use the same trick to find all Cmdlets for site collection control—using the SPSite noun, rather than SPWeb.

Getting Help

Getting a list of PowerShell Cmdlets is good, but knowing more about a specific Cmdlet is better. PowerShell includes another built-in Cmdlet to get help for a specific Cmdlet: Get-Help. The Get-Help Cmdlet provides details about Cmdlets, providers, aliases, functions, and scripts. The following line demonstrates how to execute the Get-Help Cmdlet to get help about the Get-SPWeb Cmdlet:

Get-Help Get-SPWeb

Figure 3-3 shows a screenshot of the Get-Help Cmdlet used with the Get-SPWeb Cmdlet as a parameter. As you can see, the Get-Help Cmdlet displays the name, a synopsis, syntax, and description of the Cmdlet passed as argument. The syntax information is probably most important because it details the various arguments for the Cmdlet.

The Get-Help Cmdlet includes parameters to get information that is more detailed on a Cmdlet. Passing the –Examples parameter will return various examples to demonstrate the use of the Cmdlet. Passing the –Detailed parameter will give more detail beyond the basic information, and passing the –Full parameter will provide the complete help file for a Cmdlet. Try out the Get-Help Cmdlet on a number of well-known Cmdlets as well as some you have not encountered to get a good understanding of available help information.

The –Parameter argument is helpful in conjunction with the Get-Help Cmdlet because it provides details about a given parameter. Typically, when introduced to a new Cmdlet, you would use the Get-Help Cmdlet to get the syntax of available parameters and then provide the –Parameter argument to get details on a specific parameter for a Cmdlet. You can pass a * as the name to the –Parameter argument to get detailed information on all parameters supported by a Cmdlet.

Aliases

An alias is a shortcut for lengthy Cmdlets. For example, typing the lengthy Cmdlet named Get-SPBrowserCustomerExperienceImprovementProgram might get annoying quickly. By creating an alias for the Cmdlet, you can then use the alias in place of the full-length Cmdlet. Of course, I deliberately chose a Cmdlet name that stood out as long, but the likelihood of needing to get the browser customer experience program too often is small. However, this example does demonstrate that some PowerShell Cmdlets can get quite long.

The following example demonstrates how to create an alias, called web, for the Get-SPWeb Cmdlet:

Set-Alias –Name web –Value Get-SPWeb

You can then get the alias value with the following line:

Get-Alias web

To use the alias, simply replace the full name of the Cmdlet with the alias, complete with required parameters, as follows:

web http://sp2013

Pipelines

Pipelines, in my opinion, really set PowerShell apart from standard command-line operations in Windows. Pipelines allow passing of output information from one PowerShell script or Cmdlet to another. Earlier in the chapter, I mentioned that PowerShell deals with objects rather than strings, and this becomes apparent when using pipelines.

The following Cmdlet lists all SPList objects within the root web of a site collection:

(Get-SPSite http://sp2013).RootWeb.Lists

Looking at the preceding command, you see that I use parentheses around the Get-SPSite Cmdlet and then access the RootWeb property and Lists collection. This further illustrates the fact that PowerShell uses objects—the Get-SPSite Cmdlet returns a SPSite object, which has a property called RootWeb. Now, back to our discussion about pipelines.

If you execute the preceding command, you will get back pages of unhelpful information as PowerShell displays every SPList object returned from the Lists collection. By default, PowerShell displays all information about an object if you do not specify the property or method associated with the object.

The following modified example shows the same command piping the output to the ForEach Cmdlet. The ForEach Cmdlet iterates a collection and allows you to control fine-grained operation on each object in the collection.

(Get-SPSite http://sp2013).RootWeb.Lists | ForEach-Object { $_.Title }

The preceding command pipes the results to the ForEach Cmdlet, which iterates the collection and executes the commands in the curly braces. When working with Cmdlets that iterate over collections or filter collections, the special syntax $_ denotes the current object in the iteration. The preceding command outputs the title of each list in the collection.

Administration Permissions

If you have used STSADM in any capacity, you might understand the frustration that comes from failure to execute operations because the current user does not have enough permissions in SharePoint content and configuration databases. The typical response from IT is to provide you the credentials of the SharePoint farm account and have you run the SharePoint Management Shell as the farm user—not ideal.

SharePoint requires the current user (running the PowerShell session) to be a member of the SharePoint Shell Access role, and be a member of the local Windows security group WSS_ADMIN_WPG. Assuming you have administrator rights on the SQL Server hosting SharePoint, and the local SharePoint server, you could assign users to the SQL role for a SharePoint database and assign the same users to the local security group via server management. However, this is a chapter on PowerShell, so you should learn how to accomplish the same result using the SharePoint Management Shell.

To grant administration rights for a user, you first have to possess administration rights—a chicken and egg situation. In all likelihood, because you are reading this book, you have already established farm administration rights and have SQL administration rights on the SQL Server. All the same, it is good to try out the following commands and assign an otherwise-non-admin user permissions to execute shell commands against SharePoint.

In this example, I am going to grant my user permissions on my default WSS content database, by providing the database parameter. If you do not include the database parameter in the following command, then SharePoint will assign the permission in the main SharePoint configuration database—this is fine if you plan to perform PowerShell commands that configure the farm. If you plan to use PowerShell to administer site collections, subsites, lists, etc. belonging to a specific content database, then I recommend using the database parameter with a specific content database.

$db = Get-SPContentDatabase -Identity WSS_Content
Add-SPShellAdmin -database $db -UserName ROBDEVsp_admin

Follow up the preceding command with the following one to get a list of shell administrators for the default content database:

$db = Get-SPContentDatabase -Identity WSS_Content
Get-SPShellAdmin –database $db

It probably goes without saying (but I will say it regardless) that you can revoke shell administration rights with the following commands:

$db = Get-SPContentDatabase -Identity WSS_Content
Remove-SPShellAdmin -database $db -UserName ROBDEVsp_admin

Content Databases

In the previous section, ”Administration Permissions,” I included the Cmdlet Get-SPContentDatabase. This Cmdlet is one of a small list that deals with content databases. A content database, as you may already know, stores all content for one or many site collections. The following command lists the content database Cmdlets, explained in Table 3-2. Of course, you can leverage the Get-Help Cmdlet to get more information on any of the listed Cmdlets.

Get-Command *SPContentDatabase*

Of the Cmdlets listed in Table 3-2, the Cmdlet Mount-SPContentDatabase plays an important part in database-attach upgrades from SharePoint 2010 to SharePoint 2013. We use the Get-SPContentDatabase Cmdlet most often because it returns an object instance representing the content database, which we may then pass to other Cmdlets. This Cmdlet returns a SPContentDatabase object, which has many properties. To see a list of them, execute the following command:

Get-SPContentDatabase | Format-List *

The Format-List Cmdlet displays the properties of a piped object in list format (Figure 3-4).

The Get-SPContentDatabase Cmdlet lists all content database–associated web applications; using the –WebApplication parameter, provide the name of the web application.

Get-SPContentDatabase –WebApplication "SharePoint -80"

Every site collection resides in at least and no more than one content database, which you can establish using the –Site parameter, as follows:

Get-SPContentDatabase –Site " http://hostname/sitecollection "

Web Applications

PowerShell includes a selection of Cmdlets to manipulate web applications. A web application is the hosting application that resides in Internet Information Server and hosts one or many site collections. Execute the following PowerShell command to obtain a list of web application Cmdlets:

Get-Command –Noun SPWebApplication

Table 3-3 provides a description of each of the web application–related Cmdlets.

Now that I have covered web applications in PowerShell, I shall examine site collections next, followed by sites and subsites.

Site Collections (SPSite)

A site collection represents the taxonomy of a web site, and hosts a hierarchy of sites. In Central Administration, you create, edit, and delete site collections under the Application Management section. Table 3-4 lists the available Cmdlets; you can see a list of these Cmdlets by executing the following command:

Get-Command –Noun SPSite

The more common of the SPSite Cmdlets are the Backup and Restore Cmdlets. As administrators, we are familiar with the STSADM backup and restore commands, which provide granular backup of complete site collections (often used when deploying a version of a web solution from development to staging and production). The new PowerShell Backup and Restore Cmdlets support the use of SQL snapshots, which ensures integrity of the backup, while allowing users to continue reading and writing to the active site collection. STSADM backup places a read-only lock on the site collection, prohibiting backup of a busy SharePoint site collection during business hours.

Sites (SPWeb)

Consider a modern intranet or public web site, which consists of multiple levels, accessible via navigation elements. A site represents a single level in a site hierarchy. In SharePoint, a single site contains document libraries, lists, and subsites. It does not matter if the site is a publishing site, team site, meeting site, etc. The site represents one node in the overall site taxonomy.

The SharePoint object model, and hence PowerShell, represents a site as a SPWeb object. Similar to other objects in PowerShell, you can get an idea of the number of properties associated with the SPWeb object by using the following command:

Get-SPWeb http://web-url | Format-List *

Table 3-5 lists the available Cmdlets, using the following command:

Get-Command –Noun SPWeb

Typically, the most common of the preceding SPWeb Cmdlets is the Get-SPWeb Cmdlet, with which you might perform multiple operations via different SP Cmdlets. The SPSite site collection maintains a list of all SPWeb objects available in the site collection, which you can iterate as follows:

(Get-SPSite http://sp2013).AllWebs | Foreach-Object { $_.Title }

The preceding command gets SPWeb objects via the AllWebs collection on the SPSite object returned by the Get-SPSite Cmdlet. In my example, I am simply displaying the title of each site in the site collection, but I could just as easily pass the SPWeb object to a Cmdlet that performs an operation on the SPWeb object.

Memory and Disposal

Developers of SharePoint applications understand the need for memory disposal practice. SharePoint objects, such as SPSite, SPWeb, etc., consume resources, and it is the developer’s responsibility to release these resources by calling the Dispose method on these types of objects when done using them. Do you have to concern yourself with memory disposal when using these objects in PowerShell? Fortunately, PowerShell, in conjunction with the SharePoint object model, assists in the disposal of expensive SharePoint objects.

Earlier in this chapter, I mentioned using the SharePoint Management Shell, rather than the standard Windows PowerShell, because each command or single-line pipeline runs in a single thread. This is important when using objects like SPSite and SPWeb, because we often like to pipe these objects and Cmdlets that return these objects together, which would ordinarily leak memory in a multi-threaded Windows PowerShell window.

So, how does PowerShell manage memory disposal? I shall provide an example.

Get-SPWebApplication | Get-SPSite –limit all | Foreach-Object { $._Url }

The preceding command iterates over every site collection for every web application in the farm. For each site collection, the command displays the URL. The issue with this command is that the call to Get-SPSite for each web application uses space in memory for the new SPSite object. In a standard Windows PowerShell, not disposing of the SPSite object after each iteration would cause a memory leak. The SharePoint Management Shell caters to these scenarios and ensures disposal of all objects allocated in the preceding pipeline sequence.

Now, consider the following scenario, where SPSite and SPWeb objects are used over several lines of a PowerShell script:

$site = Get-SPSite " http://sp2013 "
Foreach ($web in $site.AllWebs) {
      Write-Host $web.Title
}

The preceding script gets a new instance of a SPSite object for a site collection URL, then iterates every site in the site collection (represented by SPWeb objects) displaying the title. In this example, PowerShell cannot help you because it has no way of knowing whether to dispose of the SPSite object nor each SPWeb object in the iteration, since the operations span several lines in the script. In this case, disposal is the responsibility of the script developer.

As a rule, I like to dispose of all SharePoint objects that implement the IDisposable interface. The following modified script ensures disposal:

$site = Get-SPSite " http://sp2013 "
try {
  Foreach ($web in $site.AllWebs) {
    try {
      Write-Host $web.Title
    } finally {
      $web.Dispose();
    }
  }
} finally {
  $site.Dispose();
}

Although the second version of the script ensures disposal of memory, the script is messy. Developers writing code in C# have a shortcut to clean up disposable objects with the using keyword. In PowerShell, we also have a shortcut, shown as follows:

Start-SPAssignment –Global
$site = Get-SPSite " http://sp2013 "
Foreach ($web in $site.AllWebs) {
      Write-Host $web.Title
}
Stop-SPAssignment –Global

Wrapping our script between the Start-SPAssignment –Global and Stop-SPAssignment –Global statements ensures that PowerShell disposes of any object allocated and assigned to the global space. Objects in the global space are those that the script has not scoped to a particular named space. The following example shows the script using two scoped name spaces:

$siteScope = Start-SPAssignment
$site = Get-SPSite " http://sp2013 "
for ($i=0;$i -lt $site.AllWebs.Count; $i++) {
  $webScope = Start-SPAssignment
  Write-Host $site.AllWebs[$i].Title
  Stop-SPAssignment $webScope
}
Stop-SPAssignment $siteScope

As you have discovered, memory management of SharePoint objects in PowerShell is important. If you are writing small scripts that have a short execution time—as in they complete within a few seconds—then memory-management is probably not one of your major concerns. However, if you have a script that iterates a large site collection and performs significant processing, then you can easily find yourself eating memory until your PowerShell instance crashes.

Before I conclude this section on memory and disposal, there is one more important point to be aware of—PowerShell does not clean up leaked objects at the end of scripts. In other words, if you have a leaky script, which you execute several times (perhaps because you are debugging), PowerShell is unable to claim the leaked memory until you terminate the PowerShell process. Again, this is not a big consideration if you are executing your scripts in a short window of time, but if you have a PowerShell script running for a lengthy duration, pay close attention to the amount of memory the PowerShell process consumes.