PowerShell Primer for SharePoint Developers: Part 2

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.

This entry was posted in PowerShell, SharePoint, SharePoint 2010, SharePoint 2013. Bookmark the permalink.