- Interact with Azure Cosmos DB with PowerShell - Tue, Sep 14 2021
- Azure health services: Track Microsoft cloud outages and maintenance - Wed, Sep 8 2021
- Powerline: Customize your PowerShell console - Tue, Aug 31 2021
The Stsadm.exe command-line utility has been deprecated since SharePoint 2010, so if you haven't yet begun your migration to Windows PowerShell, then I suggest you conquer your learning curve sooner rather than later. Recall that Microsoft added PowerShell support to their Windows Server Common Engineering Criteria (CEC) in 2010, which means that all Windows Server products require a PowerShell interface in addition (or instead of) a GUI front-end.
In this blog post I would like to outline some common points of confusion that SharePoint administrators encounter with using Windows PowerShell to manage SharePoint 2013.
SharePoint 2013 uses snap-ins, not modules ^
Windows PowerShell has two methods for packaging and deploying cmdlets and associated PowerShell functionality: snap-ins and modules. Snapins are are "old school" compiled dynamic link libraries (DLLs) that need to be installed and registered on target systems before you can add the snap-in to your system.
Modules were introduced in PowerShell v2 and are the preferred way to deploy PowerShell code. Modules can be dynamically loaded by Windows Server 2012, and are generally much more flexible to use in practice than snap-ins.
To load a module into your PowerShell session, use the Import-Module cmdlet like so:
What we SharePoint administrators need to know is that, for whatever reason, the Microsoft SharePoint product team cleaves to the Powershell v1 snap-in motif to deploy the over 800 cmdlets included in SharePoint 2013.
Thus, we instead must issue the Add-PsSnapin cmdlet to load the Microsoft.SharePoint.PowerShell DLL:
Note that we must identify the full SharePoint Object Model namespace to the target DLL instead of using a single, friendly name such as ServerManager or ActiveDirectory. Oh, well.
Nothing "special" about the SharePoint Management Shell ^
In my experience, some SharePoint administrators habitually use the SharePoint Management Shell that is installed with the SharePoint product. Why? Perhaps these admins feel that there is something "special" that the Management Shell gives you that you don't get by using a standard PowerShell session.
Take a look at the screenshot below; I'm about to show you something interesting and cool. On the left side of the figure I show you the Properties sheet of the SharePoint 2013 Management Shell. In the Target field, we can see that the shortcut actually calls the PowerShell runtime environment and opens a script file named sharepoint.ps1. That .ps1 file is located deep within the SharePoint 15 hive.
The "smoke and mirrors" of the SharePoint Management Shell
As you can see in the lower-right of the screenshot, all the sharepoint.ps1 file does is to load the SharePoint snap-in! Sure, there is a little bit more code. For instance, the Set-Location statement puts your current working directory to your home folder path. The first two lines of the script file evaluate your PowerShell version, and if you are running a version greater than 1 (a no-brainer, really), the PowerShell session is configured to reuse execution threads; this prevents multiple PowerShell sessions from wasting system memory.
Thus, we see that you gain no real practical advantage by invoking the SharePoint Management Shell, Instead, simply customize your PowerShell profile to set up the environment and load the SharePoint snap-in, and you're good to go.
The SharePoint PowerShell "Online Help" is lacking ^
A new feature introduced in Windows PowerShell 3.0 is updatable help. This is, at least on paper (so to speak), a great idea because in my experience the Microsoft SharePoint product team tend to be a bit sloppy and inconsistent in their SharePoint PowerShell documentation.
As a matter of fact, the SharePoint PowerShell help is not even available locally by default. You'll need to run the following cmdlet on your SharePoint server in order to download the help files from the Internet:
Once you've updated your local PowerShell help and loaded the SharePoint snap-in, you can invoke the Get-Help (aliased to help) cmdlet in the usual manner:
Get-Help New-SPWebApplication -Full
Another new feature is the Online parameter of Get-Help, which bypasses your local PowerShell help files and retrieves the presumably latest and greatest content directly from Microsoft's content servers:
Get-Help Get-SPSite -Online
I show you the Online parameter in the screenshot below.
You can retrieve the "latest and greatest" PowerShell help by using Get-Help -online.
Please forgive my negative attitude toward the woefully incomplete and error-laden SharePoint 2013 PowerShell online help. I will try to give Microsoft the benefit of the doubt that they will correct the errors and expand the help system as the SharePoint 2013 product matures.
No Built-in cmdlets exist to create lists and libraries ^
The SharePoint object model's naming convention is, for the most part, logically implemented. To wit:
- SPFarm: SharePoint farm
- SPWebApplication: SharePoint Web application
- SPSite: SharePoint site collection
- SPWeb: SharePoint site or subsite
- SPList: SharePoint list
- SPDocumentLibrary: SharePoint document library
So far, so good, as you would expect, we use New-SPWebApplication, New-SPSite, and New-SPWeb to create new SharePoint Web applications, site collections, and sites, respectively.
Sadly, this consistency model breaks down at the list and document library level. That is to say, SharePoint 2013 RTM includes no built-in PowerShell cmdlets to facilitate the easy creation of document libraries or lists. Bummer!
Instead, we must turn to third-party developers who possess knowledge of the SharePoint application programming interface (API). For instance, Himanshu Kumar wrote a handy PowerShell script to create a document library; try it out and let me know how it works for you in the comments portion of this blog post.
Don't forget about the Whatif parameter ^
Some PowerShell statements can be incredibly destructive to your SharePoint farm if they are run against your production servers without full testing. I'm very grateful that Microsoft provides us with the Whatif parameter to run a "pre-flight check" on our code before executing it for real. Consider:
Get-SPWeb -Site "http://oursite" | Remove-SPWeb -WhatIf
Basically, the WhatIf parameter allows the PowerShell runtime environment to parse your code, but prohibits the statement(s) from actually activating in your farm.
If your code contains any syntax problems, then WhatIf will catch 'em. If you made an addressing mistake, WhatIf will catch that as well. However, if your code works, then you'll simply receive your PowerShell prompt back with no errors.
The first PowerShell statement hit a live SharePoint Web; The WhatIf parameter caught the mistake (non-existent Web) in the second statement.
By the way, the WhatIf parameter is a built-in component of PowerShell versions 2, 3, and 4, and is therefore available to any PowerShell module or snap-in, at least in theory. This parameter is not in any way exclusive to SharePoint 2013.
If case you wondered, I used the PowerShell Integrated Scripting Environment (ISE) to generate the screen capture. This tool is built into Windows Server 2012, although it needs to be installed:
I love the ISE because the tool includes debugging, syntax highlighting, syntax help, code completion--in other words, all the features you expect in a development tool.