PowerShell has a rich set of advanced features that provide an Administrator with a multitude of options depending on what they would like to do. This nugget will take a more focused look into the many ways objects can be used. Remember, an object in this case is a variable. From Part 1 of this nugget, you know that variables are objects that hold something. This nugget will conclude with some PowerShell scripting basics. Thanks goes to Sheyi for providing a technical review.
PipeBind
PipeBind is a concept where a parameter accepts an object “variable” of a specific type. If you look at the syntax of get-help new-spsite –full, you will discover some parameters accept pipe bind:
New-SPSite -Url <String> -OwnerAlias <String> [-AssignmentCollection <SPAssignmentCollection>] [-Confirm <SwitchParameter>]] [-ContentDatabase <SPContentDatabasePipeBind>] [-Description <String>] [-HostHeaderWebApplication <SPWebApplicationPipeBind>] [-Language <UInt32>] [-Name <String>] [-OwnerEmail <String>] [-QuotaTemplate <SPQuotaTemplatePipeBind>] [-SecondaryEmail <String>] [-SecondaryOwnerAlias <String>] [-SiteSubscription <SPSiteSubscriptionPipeBind>] [-Template <SPWebTemplatePipeBind>] [-WhatIf [<SwitchParameter>]] [<CommonParameters>]
In this example, there are several parameters that accept pipe binds. Here is an example of passing a variable to the template parameter which accepts a pipe bind.
$tem = get-spwebtemplate –identity STS#0
New-spsite –url http://contosoweb –owneralias contoso\administrator –name contososite –template $tem
Properties and Methods
Variables have properties and method’s available based on the type of the variable. For example, declaring a variable and assigning it a web application will contain all properties and functions for type SPWebApplication. To view all of the available properties and methods, you can pipeline the get-member cmdlet.
For Example:
$web = get-spwebapplication
$web | get-member
Note: This is not a complete list of all method’s and properties available for this type.
It’s possible to add conditions to get more desirable results. For Example, you can use the where alias if you just want to see a specific member type. To view only members of type Method punch in the following:
$web | get-member | where {$_.MemberType –eq “Method”}
Note: It is possible to do more than one pipeline J
Viewing Properties
Before updating and viewing specific properties of an object, it’s important to know how to first view all properties and there corresponding values. By default, only a few properties are exposed by simply printing a variable.
Use get-object cmdlet to view all properties of a given object. An alias for the get-object cmdlet is available called select which is what I prefer to use.
Note: Another option to view all properties of a given object is available.
For Example: $web | fl
If you happen to know which property to specify, simply append the property name with the variable.
In this example, two content databases are outputted because the Web Application has two content databases attached. What if you only need to make changes to one of them? Where-object command-let is available which assists in filtering down results. An alias exists for the where-object command-let called where which is what I prefer to use.
$web.contentdatabases | where {$_.name –eq “WSS_Content”}
The example above demonstrates how to view and filter properties against a single object\variable. What if you know which property to use and simply want to filter directly from the command-let. Some command-lets offer parameters which allow filtering on the fly.
For Example, the –filter parameter is available running Get-SpSite command-let.
Get-spsite –filter {$_.owner –eq “contosoweb\administrator”}
This example outputs every site collection where the owner is set as contosoweb\administrator. This is a much faster query when dealing with a large # of sites.
Note: You can also use the –like wild card instead of –eq.
For Example: Get-spsite –filter {$_.owner –like “contoso\ad*”}
Setting Properties
Besides viewing properties, it’s possible to update properties as well.
For Example, setting a property called name and updating it using update method:
$web.name
Output: SharePoint – 80
$web.name = “My Renamed Site!”
$web.update()
Output: My Renamed Site!
Running Methods
Besides using the update method above to set a property, you have a variety of methods available for a specific object type. For Example:
Scripting with PowerShell
PowerShell scripts provide an automated approach to group one or more command-lets in order to accomplish one or more tasks. For Example, PowerShell scripts can provision new Web Applications\Site Collections, service applications, or backup\restore farm. Again, the possibilities are endless depending on what an Administrator wants to do. A powershell script is as easy as dropping your command-lets in notepad and saving the file with a .ps1 extension. Variables are often used in PowerShell scripts because they save time in writing scripts as well as provide a cleaner look to the script. The following example is a simple script to provision a new site collection:
$russmax = get-spuser –identity contoso\administrator -web http://contosoweb
$DB = get-contentdatabase
new-spsite -url http://contosoweb/sites/dancan -template $tem -Name DanCanSite -Description DQ -owneralias $russmax -contentdatabase $db
After saving this script as newsite.ps1, launch powershell and run the following from the directory where the script resides:
.\newsite.ps1
Also, custom command-lets and functions can be created and used within PowerShell scripts to achieve a more desirable result. Advanced PowerShell scripts for SharePoint 2010 will be available on codeplex soon.
http://www.codeplex.com/SharePointPSScripts/
PowerShell has been nicely integrated into SharePoint 2010 and is the eventual replacement of stsadm. Stsadm still exists with SharePoint 2010 for backward compatibility reasons but PowerShell is here to stay and will be the most widely adopted and used out of the two. PowerShell is included as a prerequisite which is automatically downloaded and installed during the prerequisite install of SharePoint 2010. Part 1 of this nugget will focus on basics of PowerShell including features and where to start. Part 2 will contain some more advance topics such as scripting and manipulating objects by setting properties or running methods against them.
Basics
Windows PowerShell™ is a task-based command-line shell and scripting language designed especially for system administration. Built on the .NET Framework, Windows PowerShell™ helps IT professionals and power users control and automate the administration of the Windows operating system and applications that run on Windows.
Built-in Windows PowerShell commands, called cmdlets, let you manage the computers in your enterprise from the command line. Windows PowerShell™ providers let you access data stores, such as the registry and certificate store, as easily as you access the file system. In addition, Windows PowerShell™ has a rich expression parser and a fully developed scripting language.
Windows PowerShell™ includes the following features:
Note: The basics section was taken directly from technet because I couldn’t have written this any better. See the resources section at the bottom of this blog for direct access to the site.
PowerShell Features
TAB – Expansion
It’s possible if you do not know an entire cmdlet to tab through what you have typed in order to find a match. Cmdlets always start with a verb-cmdlet name combination. Tab expansion is great for quickly tabbing through all matching cmdlets. For Example, the entire first part of the name (the verb) and the hyphen that follows it must be inputted. For example, if you type get-co and then press the Tab key, Windows PowerShell will automatically expand this to the Get-Command cmdlet. If you press Tab key again, Windows PowerShell replaces this with the only other matching cmdlet name, Get-Content.
Pipelining
Pipelining is the process where the output of one command is piped to a second command using the Pipline operator |.
get-spwebapplication –identity http://contosoweb/ | new-spcontentdatabase –name contosodb
In this example, the output of get-webapplication is piped over to new-spcontentdatabase cmdlet. The new-spcontentdatabase cmdlet has –webapplication parameter and it’s required. You don’t need to specify this parameter because it’s piped over.
Format List
Format-List cmdlet formats the output of a command as a list of properties in which each property is displayed on a separate line. Typically, the alias of FL is used instead via piping.
For example: get-spwebapplication –identity http://contosoweb | FL
Aliases
An alias is another name you assign to a cmdlet, function, script, etc…. There are some built-in aliases within PowerShell. You can look at those by running the get-alias cmdlet. It’s possible to create aliases by using the Set-Alias cmdlet.
For Example, create an alias named DanCan which runs get-spwebapplication:
Set-Alias DanCan get-spwebapplication
Now running DanCan will produce the same result as get-spwebapplication.
Variables
PowerShell contains basic programming principles such as using Variables. Variables are simply an object that holds something. For Example, you can create variables to hold a specific content database. What you do with that variable is endless in terms of options available which will be discussed in the next nugget. For now, it’s important to understand how to declare variables.
To declare a variable named Var to hold content database named contosoDB type the following:
$var = get-spcontentdatabase –identity contosoDB
Type $var and it will output what’s stored in the variable.
Getting Help with get-help
PowerShell is accessible via the start menu:
Note: PowerShell is referred to as SharePoint 2010 Management Shell in SharePoint 2010
Scenario:
Great, it’s opened now what do I do! In this scenario, an administrator, Dan, must use PowerShell to create a new site collection using team site template and is unsure of which cmdlet or syntax to run.
The Get-Help cmdlet will output every alias, cmdlet, and function using a prefix of *. It’s great for finding out which cmdlet to run and get help on how exactly to run the cmdlet.
For Example: get-help *
Try it out and you’ll see it dump out lots of stuff like aliases and cmdlets. If you want to dump out just cmdlets you could type the following:
Get-help * | where {$_.category –eq “cmdlet”}
All SharePoint cmdlets start with SP so to output only SharePoint cmdlets you type the following:
Get-help *-SP* | where {$_.category –eq “cmdlet”}
This is great but I’d rather pipe it out to txt file. To pipe any output to a text file append > c:\filepath\filename.txt
Get-help *-SP* | where {$_.category –eq “cmdlet”} > c:\odst\output.txt
Note: Don’t worry about understanding the entire syntax, it will be more familiar after reviewing both PowerShell nuggets.
Verbs are appended to cmdlets which describe the action taken. For Example: creating, removing, or setting a new/modified value on an object. Since I’m looking to create I could be even more granular by typing the following:
Get-help new-SP* | where {$_.category –eq “cmdlet”}
After some mining, the administrator Dan needs to use the New-SPSite cmdlet. In order to properly run this command Dan needs to know the required parameters and the correct syntax. By default, running the following provides a brief summary and outputs syntax:
Get-help new-spsite
What it doesn’t tell you is which parameters are required and a brief description of each parameter. The following gives you that information:
Get-help new-spsite -full
A partial of the output:
SYNOPSIS Creates a new site collection at the specified URL.
SYNTAX New-SPSite -Url <String> -OwnerAlias <String> [-AssignmentCollection <SPAssignmentCollection>] [-Confirm <SwitchParameter>]] [-ContentDatabase <SPCon tentDatabasePipeBind>] [-Description <String>] [-HostHeaderWebApplication <SPWebApplicationPipeBind>] [-Language <UInt32>] [-Name <String>] [-OwnerEmail <String>] [-QuotaTemplate <SPQuotaTemplatePipeBind>] [-SecondaryEmail <String>] [-SecondaryOwnerAlias <String>] [-SiteSubscription <SPSiteSubscriptionPipeBind>] [-Template <SPWebTemplatePipeBind>] [-WhatIf [<SwitchParameter>]] [<CommonParameters>] DETAILED DESCRIPTION
The New-SPSite cmdlet creates a new site collection with the URL and owner specified by the Url and OwnerAlias parameters.
PARAMETERS -Url <String> Specifies the URL that the new site collection uses. If this is not a host header site, the URL must start with the containing the Web application URL Required? true Position? 1 Default value Accept pipeline input? True Accept wildcard characters? false
The required parameters are URL and Owner. Dan also wants to specify a team site template so it will look like the following:
New-spsite –url http://contosoweb/sites/snackattack -OwnerAlias contoso\farmadmin -template STS#0
Note – To get a full list of installed templates run the following: get-spwebtemplate
TIP: Get-Command cmdlet –syntax can also if an Administrator just needs to review the syntax.
Resources:
http://technet.microsoft.com/en-us/library/bb978526.aspx
http://technet.microsoft.com/en-us/library/dd347700.aspx
http://technet.microsoft.com/en-us/library/dd347728.aspx
http://technet.microsoft.com/en-us/library/dd347730.aspx