In the previous recipe, we looked at some of the functionalities available to you in the PowerShell library, designed to help you access basic features in SharePoint. By using those features, you can access SharePoint objects and manipulate their properties. But what if you need to access the object model beyond what's available to you from the PowerShell snap-in for SharePoint? In this recipe, we'll take a look at how you can access more advanced features in SharePoint by referencing SharePoint assemblies and associated methods in those libraries.
In this example, we'll be using PowerGUI to execute our script. So log in to your environment with administrative privileges and launch PowerGUI.
The following steps will demonstrate how you can use some of the advanced SharePoint functions by referencing external assemblies in your PowerShell script:
1. Navigate to the test site URL: http://intranet.contoso.com and click on the Shared Documents library to access the library.
2. In the ribbon click Library | Library Settings.
3. Under Permissions and Management click Information management policy settings as seen in the following screenshot:.
4. Select Document from the list of available content types.
5. Take note that none of the policies have been defined for this document library.
6. Switch to your PowerGUI scripting editor and enter the following script:
$siteUrl = "http://intranet.contoso.com" $snapin = Get-PSSnapin | Where-Object {$_.Name -eq 'Microsoft.SharePoint.Powershell'} $snapin = Get-PSSnapin | Where-Object {$_.Name -eq 'Microsoft.SharePoint.Powershell'} if ($snapin -eq $null) { Write-Host "Loading SharePoint Powershell Snapin" Add-PSSnapin "Microsoft.SharePoint.Powershell" } $site = Get-SPSite | Where-Object {$_.Url -eq $siteUrl} $web = $site.OpenWeb(); $list = $web.Lists["Shared Documents"]; $policy = [Microsoft.Office.RecordsManagement.InformationPolicy.ListPolicySettings]($list); if ($policy.ListHasPolicy -eq 0) { $policy.UseListPolicy = "true"; $policy.Update(); } $contentType = $list.ContentTypes["Document"]; [Microsoft.Office.RecordsManagement.InformationPolicy.Policy]::CreatePolicy($contentType, $null); $newPolicy = [Microsoft.Office.RecordsManagement.InformationPolicy.Policy]::GetPolicy($contentType); $newPolicy.Items.Add( "Microsoft.Office.RecordsManagement.PolicyFeatures.Expiration", "<Schedules nextStageId='3'>" + "<Schedule type='Default'>" + "<stages>" + "<data stageId='1' stageDeleted='true'></data>" + "<data stageId='2'>" + "<formula id='Microsoft.Office.RecordsManagement.PolicyFeatures.Expiration.Formula.BuiltIn'>" + "<number>1</number>" + "<property>Created</property>" + "<period>years</period>" + "</formula>" + "<action type='action' id='Microsoft.Office.RecordsManagement.PolicyFeatures.Expiration.Action.MoveToRecycleBin' />" + "</data>" + "</stages>" + "</Schedule>" + "</Schedules>"); $newPolicy.Update();7. Press F5 to execute the script, and then wait until the script executes.
8. Switch back to the policy setting page we accessed in step 5. Take note of the new policy added to the Retention policy where expiration has been enabled on the document library items, as seen in the following screenshot:
 |
The preceding code demonstrates how to take advantage of SharePoint class libraries to access functionality and methods available in those class libraries, and not directly available as PowerShell SharePoint script extensions. Although methods used here are discussed in detail in Chapter 8, Managing Documents and Records in SharePoint with PowerShell, this recipe demonstrates basics behind accessing SharePoint object model using PowerShell. In this example, we created a new expiration policy on the document library of the team site on the development environment downloaded from Microsoft's download site http://intranet.contoso.com.
We started by accessing the site which we are interested in by using the PowerShell Get-SPSite method. We then accessed the current site at which the SharePoint Documents document library is hosted.
Next, we got hold of the current policy on the library in order to add a new instance of a policy.
We used the CreatePolicy method available in the [Microsoft.Office.RecordsManagement.InformationPolicy.Policy] namespace to create a policy for the library. This part demonstrates how the function is not available in the PowerShell syntax, but is available in the SharePoint library, and can be called in order to access some of the advanced functions in SharePoint.
The rest of the preceding code adds the definition of the policy we're trying to create on the library and adds the new policy object to the list of available policies.
When you execute this script, the newly defined policy will be added to the library on the site.
Let's take a look at how you can access external SharePoint libraries to execute more advanced PowerShell commands.
In this example, we looked at how you can create an expiration formula on the library, but there is plenty more you can do. To access functions in SharePoint libraries, you need to identify the object class and namespace those functions belong to so you can reference them in PowerShell.
If you search for the policy function class on TechNet you will find: Microsoft.Office.RecordsManagement.InformationPolicy.Policy. From there you can also determine various functions available to be called.
To call any of the functions, you would use the method we used in the preceding source code and reference the namespace first, followed by the class and function names.
Let's look at another example where we use PowerShell to connect to the current site and then change the status of features on the site.
1. Open PowerGUI, click File | New to create a new script.
2. Add the following code to the script window:
$siteUrl = "http://intranet.contoso.com" $snapin = Get-PSSnapin | Where-Object {$_.Name -eq 'Microsoft.SharePoint.Powershell'} if ($snapin -eq $null) { Write-Host "Loading SharePoint Powershell Snapin" Add-PSSnapin "Microsoft.SharePoint.Powershell" } $site = Get-SPSite | Where-Object {$_.Url -eq $siteUrl} $features = $site.FeatureDefinitions; $features.get_Item("CustomFeature").Status = "Offline"3. Run the script from within PowerGUI by pressing F5.
4. Verify the status of our
CustomFeaturewhich should beOffline.
Note that we did not have direct access to the features object but rather to its parent. Yet, by using PowerShell, we were able to call function on a child object allowing us to change the status of the feature on the site.
In this case, we set the feature to be Offline. Among other available options related to a feature status, we could choose the following: Online, Disabled, Offline, Unprovisioning, Provisioning, Upgrading.
As you can see, this method is handy when you need to disable defective features across many sites in your environment.
This example demonstrates how you can access other available libraries in SharePoint and even your own custom libraries to call functions from within them.