We all have a pair of jeans that fits just right. We’ve had them for years and they hug us in all the right spots. They might not be the best looking, and they might have a few holes in them, but they're comfortable and we like them. For SharePoint 2007 admins, STSADM was like that pair of jeans.
Comfortable with STSADM?
Sure, it was a bit persnickety and somewhat limited in its usage. But we liked it and it was all ours. After using STSADM with SharePoint 2007, and maybe even SharePoint 2003, we were comfortable with STSADM and finally able to work around its idiosyncrasies to get things done.
Then SharePoint 2010 came along and everything changed. SharePoint 2010 gives up our beloved STSADM for PowerShell. That pair of jeans we’ve spent years and years getting just the way we want isn't any good any more.
PowerShell Can Do It Better
But don’t fret fellow SharePoint admins. PowerShell does more than STSADM and, in general, does everything faster. We can eat all we want and our new jeans will still fit. Not only will these jeans fit, but they have more pockets and they make us look even better than our old jeans did.
In this article, I'll show you how to start using PowerShell to administer SharePoint 2010. You'll learn how to get around in PowerShell and what to do when you’re completely lost.
And I'll show you how to get PowerShell to do your SharePoint bidding for you. You won’t have a Ph.D. in PowerShell by the end of this article, but you’ll have a solid GED you can be proud of.
Where to Start
Let’s put this out in the open right up front; PowerShell is scary. STSADM might not have had the most friendly interface, but if you screwed up, it spewed its usage out to the screen in an almost condescending manner, as if to say “Bzzzt! Try again!”
While this could be frustrating at times, it was helpful. When STSADM did its dump to the screen, it was all SharePoint-related junk. You had a good chance of being able to muddle through and figure something out.
PowerShell is not nearly so forgiving. And how do you even know where to start? To make sure you get PowerShell with all the SharePoint goodness baked in, start it with the SharePoint Management Shell shortcut in the Start menu.
The SharePoint Management Shell
If you try to manage SharePoint in any other PowerShell console, you’re going to find it even less welcoming than usual.
When you fire up the SharePoint Management Shell it doesn’t offer any advice; it just blindly stares back at you, blinking, expecting you to do something. If you’re not familiar with PowerShell, this can be quite daunting. Where do you start?
Start with Help
The good news is that you don’t need anything fancy to get started. Help is as easy to find as just typing "help." When you type help in any PowerShell prompt, you’ll get a screen full of really useful help. If you remember nothing from this article, remember to type help when you need help in PowerShell. In return, you’ll get a screen like Figure 1 shows.
The help screen offers a lot to digest, and it probably won’t all make sense right away. The two key things to take away from this help screen are using Get-Help followed by a cmdlet name to see how to use the cmdlet, and using Get-Command to help you find commands.
Both of these help commands will serve you well as you make your way through the PowerShell jungle. You might have noticed a pattern in the PowerShell cmdlets Get-Help and Get-Command: they’re both in the form of verb dash noun.
In the preceding cases, Get is the verb and Help and Command are the nouns. Note also that the nouns are singular. This makes discovering cmdlets easy, once you know that all the nouns in the SharePoint PowerShell cmdlets start with SP.
A command like Get-Command –Noun SP* will return all the cmdlets in PowerShell that deal with SharePoint. This gives you a great jumping off point.
As you scroll through the 500+ results, you see not only each SharePoint-related PowerShell cmdlet, you also start to see the patterns associated with them. You'll see nouns like SPWebApplication, SPWeb, SPSite, and SPUser. It might be handy to make a searchable list of these cmdlets.
The following command will take the output of the Get-Command statement and save it to a text file called sharepoint-cmdlets.txt. Then you can use something as simple as Notepad to open the file and search for SPSite, SPWeb, or whatever term you're interested in.
Get-Command -Noun SP* | Select Name | Out-File sharepoint-cmdlets.txt
I'll cover how that command works later in this article.
As mentioned, you can use the Get-Help cmdlet to obtain information about any cmdlet, including examples of its usage. For example, if the cmdlet Get-SPSite sparks your interest, you can use the command Get-Help Get-SPSite to get the syntax of the command and a description.
Under the Remarks section, you're reminded that with Get-Help you can get examples of how to use the cmdlet. This is a great way to quickly explore how cmdlets are used when you’re trying to figure out how to accomplish a task.
As you become more familiar with the SharePoint cmdlets you can refine your Get-Command searches. For instance, after you're accustomed to thinking of site collections as SPSites, you can use Get-Command –Noun SPSite to see all the cmdlets that deal with site collections (Figure 2).
Using techniques like this you can find the cmdlet you’re looking for, as well as cmdlets you didn’t know existed. For instance, Figure 2 lists a cmdlet called Move-SPSite. You might want to investigate that later.
You can see how your PowerShell knowledge will continue to expand. After using Get-Command a few times you’ll start to get used to the SharePoint objects that PowerShell uses.
Then, as you’re poking around you’ll see that same object in other cmdlets and the pieces will start to fall together. You’ll start seeing that, with PowerShell, you can accomplish tasks you weren't even thinking about.
The Next Step
Now that you're no longer completely helpless in PowerShell, let’s get our hands dirty and start using PowerShell to make your SharePoint farm a better place.
The best way to learn how to use PowerShell is to use PowerShell when there’s a task that needs to be done in SharePoint. Instead of leaning on STSADM, or Central Admin, when something needs to be done in SharePoint 2010, figure it out in PowerShell.
Let’s start with a couple of simple tasks: getting a list of the site collections and webs in a farm.
Figure 2 shows all the cmdlets that deal with SPSites, which are the Object Model objects that represent site collections. One of them, Get-SPSite, will return a list of site collections that match the criteria you pass it.
If you don’t pass it any parameters, it will list all the site collections in your farm. Figure 3 shows Get-SPSite in action.
In Figure 3, you can see that Get-SPSite started to list all the site collections, then stopped because there were too many. SharePoint 2010 has a number of stoppers in place to keep performance from suffering because of lists with a large number of items.
These lists can cause problems in a few ways. They can bog down the SQL Server as the query runs, they can use excessive bandwidth as the results are sent across the wire, and they can overwhelm the client showing the results—in this case, PowerShell.
To prevent all these bad things from happening to you, PowerShell limits the results of many cmdlets to 20, unless you specify otherwise.
Fortunately, in the truncated output, Get-SPSite gives you the key to getting all the results: adding -Limit All to the command.
Most Get- cmdlets have a complimentary Set- cmdlet, and Get-SPSite is no exception.
You can use Set-SPSite to set various properties of a site collection. Using Get-Help Set-SPSite, you can discover all the properties that it can set.
One of the properties is the secondary site collection administrator. Having two owners for every site collection is a great idea. If the primary owner leaves the company, the secondary owner will still be able to get into the site collection and administer it.
Often, this practice is not followed when SharePoint is installed, and it’s tough to retrofit. These kinds of exercises are where PowerShell really shines. It makes short work of looping through collections of objects and filtering them, if need be.
Walking Through a PowerShell Command
The following PowerShell command lists all the site collections in a farm that are in the customers managed path—and who their primary and secondary owners are. Figure 4 shows the results.
Get-SPSite -Limit all http://sharepoint1/customers/*| Select Url, Owner, Secondarycontact | Format-Table –AutoSize
Let’s walk through this PowerShell snippet and see what it does.
The first part, Get-SPSite -Limit all http://sharepoint1/customers/*, uses the Get-SPSite cmdlet to retrieve all the site collections in the farm that are in the customers managed path.
The next character, |, is called a pipe. This tells PowerShell to pass the results of the command before the pipe to the command after the pipe.
In this example, the results to the left of the pipe are a collection of the SPSite objects that match our criteria.
This collection of objects is passed to Select Url, Owner, Secondarycontact. Remember that objects have properties.
This line tells PowerShell to display the Url, Owner and Secondarycontact properties of the SPSite objects passed to it.
How do you know what the property names were? The property names were determined by piping the output of Get-SPSite through Get-Member earlier. The Get-Member cmdlet returns all the methods and properties of any object passed to it.
This is another terrific way to explore the object model and think of fun things to do with PowerShell.
Take it a Step Further
You could stop there, but you can take it a step further and make the display cleaner by using the Format-Table cmdlet. You pass the objects from Select to Format-Table and use the –AutoSize parameter to properly format the output on the screen.
You can see from the output that none of the Customers site collections have secondary owners. Fortunately, you can leverage that same PowerShell line to walk through your site collections and, instead of showing the current settings of site collections, you can assign new settings.
With just a little tweaking the following command will assign a secondary owner to all the site collections in the Customers managed path:
Get-SPSite -Limit all http://sharepoint1/customers/* | Set-SPSite -SecondaryOwnerAlias contoso\shane
This command takes the output from Get-SPSite and uses it for Set-SPSite and sets all the secondary owners to contoso\shane in one fell swoop. Figure 5 shows the result.
This particular example might seem a bit contrived, but it’s a great example of the kind of tasks you can accomplish with PowerShell in SharePoint 2010.
Something like this would never have been possible with STSADM in SharePoint 2007 without a manually edited text file, a fancy FOR loop, and a great deal of cussing.
Another Fun Task
Another common request in the SharePoint 2007 timeframe was to determine which template was used when a web was created.
Before the introduction of the enumallwebs STSADM operation in Service Pack 2, you had no way out of the box to determine this.
Even with enumallwebs it's tough to get this information because you have to run it against each content database individually.
As you can imagine, this task is trivial, and almost fun in SharePoint 2010 with PowerShell. The following PowerShell command walks through each SPSite, enumerates each of its webs, then displays that web’s URL and the template it was created with:
Get-SPSite -limit all | Get-SPWeb -limit all | Select URL, webtemplate | Out-GridView
This example adds a little something extra. Instead of printing the results to the screen, PowerShell opens up a gridview window to display the results.
Once you open the gridview, you can add filter criteria, sort by columns, and so on. Figure 6 shows the gridview output with the criteria fields added for the two columns.
How did I discover Out-GridView? After seeing an example of Out-File and wondering what other commands used the verb “out” I ran Get-Command –verb out and saw Out-Gridview in the list.
For extra credit see which cmdlets start with “export.” You'll find some interesting options, especially Export-CSV and Export-CLIXML.
PowerShell's Advantages Over STSADM
You should now have a good foundation to start working with PowerShell. You'll find that PowerShell offers the following advantages over STSADM:
- Looping – The ability to work through a collection of objects (web applications, site collections, web, users, and so on) and perform an action on each one.
- Filtering – Being able to loop through a specific set of objects, like webs that are based on the blog template, or users whose names start with “T.”
- Piping – The ability to pass objects from one command to another, allowing some very complicated tasks to be completed in a single command line.
-
Access to the object model – PowerShell gives you direct access to the method and properties of SharePoint’s objects
Useful PowerShell Snippets
Here are a few other PowerShell snippets to get your creative juices flowing:
This command lists all the databases in your farm in order of largest to smallest and shows their size.
Get-SPDatabase | sort-object disksizerequired -desc | format-table Name, @\\{Label ="Size in MB"; Expression = \\{$_.disksizerequired/1024/1024\\}\\}
This command backs up each of your site collections to c:\backups and automatically names them.
Get-SPWebApplication | Get-SPSite | ForEach-Object \\{$FilePath = “c:\backups\” + $_.Url.Replace("http://",””).Replace(“/”,”-“ + “.bak”; Backup-SpSite –Identity $_ -path $Filepath\\}
This command enables a Feature on every site collection in a given web application.
Get-SPSite –Limit ALL –WebApplication $WebAppNameorUrl |%\\{ Enable-SPFeature $FeatureIdOrName –url $_.Url \\}
The Pain Soon Goes Away
I hope this article has made you more comfortable with using PowerShell in your SharePoint 2010 farm. The best way to get familiar with PowerShell is not by reading articles like this one (although it’s a great start); the best way is to start using PowerShell.
The next time you need to accomplish a task in SharePoint 2010, make a conscious effort to learn how to do it in PowerShell. The first few times will be painful, but very soon you’ll get used to how PowerShell works and it will become second nature to you.
