Introduction to Cmdlets for the SharePoint Management Shell
Last modified: January 14, 2010
Applies to: SharePoint Foundation 2010
Windows PowerShell™ is a new command-line tool and a supporting scripting language from Microsoft that complements Cmd.exe in the Windows administration context and that supersedes the Stsadm.exe administration tool. Although both Cmd.exe and Stsadm.exe will be maintained for backward compatibility, all current and future development of scripts and administrative files in SharePoint Foundation should use this new scripting technology.
Unlike most command-line tools, which accept and return text, Windows PowerShell is built on the Microsoft .NET Framework and accepts and returns .NET Framework objects. This fundamental change in the environment brings entirely new tools and methods that greatly improve control, efficiency, and productivity for developers and administrators.
Windows PowerShell is a simple command-line tool that introduces the concept of a cmdlet. A cmdlet is a verb-noun combination comprising a command and an object on which the command acts. Windows PowerShell cmdlet names are comprised of verbs and nouns, separated by a dash (-), which together denote their functional properties. For example, the cmdlet name Get-SPSite combines the verb (command) "Get" with the noun (object) "SPSite" to name the cmdlet that retrieves a specified SPSite object. You can use cmdlets individually, or you can string cmdlets together in linked sequences to perform complex tasks.
Cmdlet nouns take parameters as name-value pairs that give specificity to the cmdlet noun. When cmdlets are invoked, they return output objects. The objects that are returned also have properties that display as name-value pairs. Because cmdlets return objects, these objects can be passed (or "piped") to another cmdlet, in sequence. In this way, cmdlets can be chained together, providing enormous flexibility.
In fact, this is just the beginning of the significant differences between a Windows PowerShell cmdlet and commands in stsadm.exe. For example, it is important to note that a cmdlet is not an executable; rather, it is an instance of a .NET Framework class. So, with a few exceptions, cmdlets return objects rather than text streams, and they process their input objects from an object pipeline.
As you can see, Windows PowerShell is not just a new command-line tool. It is also, and perhaps more importantly, a new scripting language. Windows PowerShell installs natively with over 100 core Windows cmdlets. The library of SharePoint Foundation cmdlets, which presently number over 500, install on top of these core Windows cmdlets. These SharePoint-specific cmdlets are exposed in a special, proprietary shell called the SharePoint Management Shell.
Windows PowerShell provides both general and SharePoint-specific implementations. Under the hood, this difference is reflected in the fact that, while Windows PowerShell cmdlets derive from the base class PSCmdlet, cmdlets for SharePoint Foundation derive instead from a specialized SharePoint base class called SPCmdlet.
The distinction between Windows PowerShell cmdlets, which derive from the PSCmdlet class, and the SharePoint cmdlets, which derive from the SPCmdlet class, is very important. All of the SharePoint cmdlets that ship with SharePoint Foundation and that are exposed in the SharePoint Management Shell, are derived from the SPCmdlet class. Furthermore, all custom cmdlets that you write to support your SharePoint deployments must also be SharePoint cmdlets.
Following is the signature for the SPCmdlet base class. Note that SPCmdlet derives from the PSCmdlet class.
public abstract class SPCmdlet : PSCmdlet
Note that when you use the variable operator cmdlets, which include Get, Set, New, and Remove, you must use the specific SPCmdlet class implementations, not those derived from the PSCmdlet class. This is consistent with the scripting model for using Windows PowerShell cmdlets in SharePoint Foundation.
For cmdlets that handle persistent objects:
Get cmdlets: SPGetCmdletBase<TCmdletObject>
Set cmdlets: SPSetCmdletBase<TCmdletObject>
New cmdlets: SPNewCmdletBase<TCmdletObject>
Remove cmdlets: SPRemoveCmdletBase<TCmdletObject>
For cmdlets that handle nonpersistent objects:
For action cmdlets: