Administering SharePoint 2013 with Windows PowerShell 3.0

SharePoint 2013 administrators need to be familiar with Windows PowerShell in order to manage their farms efficiently. As it happens, there are a few "need to know" tips that SharePoint admins must have in their toolbox; this blog post provides them to you.
Latest posts by Timothy Warner (see all)

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.

SharePoint Management Shell

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:

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:

I show you the Online parameter in the screenshot below.

PowerShell help

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:

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.

Whatif parameter

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.

Join the 4sysops PowerShell group!

Your question was not answered? Ask in the forum!

0
Share
0 Comments

Leave a reply

Your email address will not be published. Required fields are marked *

*

© 4sysops 2006 - 2020

CONTACT US

Please ask IT administration questions in the forums. Any other messages are welcome.

Sending

Log in with your credentials

or    

Forgot your details?

Create Account