In my last post in this series I covered the basics of PowerShell, explaining what it is and how it works and introducing ways to find your way around the various facilities that are available. In this post I want to move on a bit and look at how we can perform some common SharePoint activities.
PowerShell for SharePoint
There are over 530 cmdlets in the Microsoft.SharePoint.Powershell snap-in so we won’t cover all of them but hopefully we now have the tools to be able to find the correct command for a particular task.
First things first, where can we find PowerShell? There are two possibilities when running on a SharePoint server, either select the SharePoint 2010 Management Shell from the start menu or open up a command prompt and enter:
PowerShell
When using the SharePoint management shell the SharePoint snap-in will already be installed. When using a standard PowerShell console we can install the snap-in by entering the following command:
Add-PSSnapIn Microsoft.SharePoint.PowerShell
We can check the list of installed snap-ins by using the command:
Get-PSSnapIn
Connecting to SharePoint remotely
One of the real benefits of PowerShell is the ability to use it to connect to remote machines. We can open a PowerShell session on a client machine and then use remoting to connect to a SharePoint server. To enable remoting on the server enter the following command:
Enable-PSRemoting
This command will enable the WinRM service and setup the firewall to allow incoming sessions.
Once the server has been configured, we can connect from any client machine by entering the following command:
Enter-PSSession “Server Name” -Credential (Get-Credential)
Note: If the client machine is running on a domain and your SharePoint server is running as a standalone server there are a few other steps that are necessary to enable remote connectivity such as configuring SSL connectivity on the server. Further information can be found at http://msdn.microsoft.com/en-us/library/aa384372(VS.85).aspx
Once a remote connection has been established, the SharePoint snap-in can be added with the command:
Add-PSSnapin Microsoft.SharePoint.Powershell
PowerShell Permissions
In order to use SharePoint cmdlets, users must be members of the SharePoint_Shell_Access role for the farm configuration database as well as a member of the WSS_ADMIN_WPG group on the SharePoint front-end server. To grant users the appropriate permissions use the following command:
Add-SPShellAdmin -Username domain\username
-database (Get-SPContentDatabase -webapplication http://Web app name)
Users must be explicitly granted permissions to every database that they need access to. By default only the account used to setup SharePoint will have permission to execute this command.
Working with Site Collections and Sites
Most of the cmdlets commonly used in the management of site collections or sites end in SPSite or SPWeb. To pick up a reference to a site collection we can use:
$site=Get-SPSite -Identity http://siteurl
Or we can return a list of all site collections by using:
Get-SPSite
When it comes to managing site objects (SPWeb), we can pick up a specific web using:
$web=Get-SPWeb -Identity http://weburl/
However to return a list of sites we need to either use the Site parameter or an SPSite object:
Get-SPWeb -Site http://SiteUrl
or
Get-SPWeb -Site $site
Creating Site Collections and Sites
We can create a new site collection using the New-SPSite cmdlet:
New-SPSite -Url http://localhost/Sites/NewSiteCollection - OwnerAlias username
We can also add new sites using the New-SPWeb cmdlet:
New-SPWeb -Url http://localhost/Sites/NewSiteCollection/NewWeb -Name MyNewWeb
Deleting Site Collections and Sites
We can delete site collections and sites by using the Remove-SPSite or the Remove-SPWeb cmdlets.
Remove-SPWeb -Identity http://localhost/Sites/NewSiteCollection/NewWeb
or
Remove-SPSite -Identity http://localhost/Sites/NewSiteCollection
Setting properties on SharePoint objects
When setting properties on the objects returned by SharePoint management cmdlets we need to call the Update method in the same manner as when updating properties using the Server Object Model. For example:
$web=SP-GetSPWeb -Identity http://myweburl
$web.Title=”My New Title”
$web.Update()
Working with Lists and Libraries
In the same was as in the server object model, lists and libraries are accessed via SPWeb objects. For example, we can enumerate the lists on a site using:
Get-SPWeb -Identity http://myweburl | Select -Expand lists| Select Title
We can add new lists using the Add method of the Lists property:
Get-SPWeb -Identity http://myweburl | ForEach {$_.Lists.Add("My Task List", "",
$_.ListTemplates["Tasks"])}
Working with Content
We can retrieve a list of all items in a site using:
Get-SPWeb -Identity http://myweburl | Select -Expand Lists | Select -Expand Items | select Name, Url
Or we can apply a filter to show only documents:
Get-SPWeb -Identity http://myweburl | Select -Expand Lists | Where {$_.BaseType -eq "DocumentLibrary"} | Select -Expand Items | select Name, Url
We can also make use of filters to search for a specific item:
Get-SPWeb -Identity http://myweburl | Select -Expand Lists | Select -Expand Items | Where {$_.Name -like "foo*"} | select Name, Url
Creating new documents
To create a new document in a document library:
function New-SPFile($WebUrl, $ListName, $DocumentName,$Content)
{
$stream = new-object System.IO.MemoryStream
$writer = new-object System.IO.StreamWriter($stream)
$writer.Write($content)
$writer.Flush()
$list=(Get-SPWeb $WebUrl).Lists.TryGetList($ListName)
$file=$list.RootFolder.Files.Add($DocumentName, $stream,$true)
$file.Update()
}
New-SPFile -WebUrl "http://myweburl" -ListName "Shared Documents"
-DocumentName "PowerShellDocument.txt"
-Content "Document Content"
Summary
In this post we’ve covered common activities and introduced cmdlets that are used to pick up references to entry point to the SharePoint server object model that will be familiar to most developers such as SPWeb, SPSite and SPList. Since PowerShell exposes objects in a similar manner to C#, developers can build on this knowledge to script many tasks that would otherwise require managed code.
