Power shell for sp admins

Editor's Notes

• #13: Difference between –detailed and –examples and –full: -full = examples + detailed + (required?) info
• #14: Exercise 1: Explore the SharePoint 2010 Management getShellIf you are familiar with previous versions of SharePoint Products and Technologies, you have probably used the stsadm command-line tool to perform various administrative tasks. You may have used batch files to automate sequences of stsadm commands. You may even have developed your own utility applications by programming against the SharePoint object model. Windows PowerShell offers a new approach to administration in SharePoint Server 2010 through the SharePoint 2010 Management Shell. Windows PowerShell combines the immediacy of the command-line with the power and flexibility of managed code. In this exercise, you will explore the SharePoint 2010 Management Shell and learn how to use Windows PowerShell to accomplish some simple administrative tasks. Note: A text file called “PowerShell Lab Commands.txt” with all the PowerShell commands and scripts used in this lab can be found in the D:\\PowerShell\\ folder. Getting Started with the Management Shell In this task, you will familiarize yourself with the SharePoint 2010 Management Shell, learn how to find help and information, and start using PowerShell commands (known as „cmdlets‟). 1. Ensure you are logged on to the virtual machine as contoso\\Administrator with a password of pass@word1 2. Launch the SharePoint 2010 Management Shell. To do this, on the Start menu, point to All Programs, click Microsoft SharePoint 2010 Products, and then click SharePoint 2010 Management Shell. (Note: You can safely ignore the error message that displays when you open the Management Shell) 3. At the PS > prompt, type the following command, and then press Enter: Get-Command –pssnapin "Microsoft.SharePoint.PowerShell" |more This command displays all the available cmdlets in the Microsoft.SharePoint.PowerShell namespace. Press Space to page down the list. Notice that there are hundreds of cmdlets relating to a broad range of administrative tasks. You can press Enter to move down the list one item at a time. Note: You could also type gcmas shorthand for Get-Command. To get help and information on a particular cmdlet, you can use the Get-Help <cmdlet-name> command. 4. Type the following command, and then press Enter: Get-Help Get-SPSiteThe console window displays information on how to use the Get-SPSitecmdlet. As you might have guessed, cmdlets that include the Get prefix return information. You can use these cmdlets to write information to the console, or to provide information to other cmdlets. You can also use the theGet-Help <cmdlet-name> -detailed or Get-Help <cmdlet-name> -full command options to retrieve more detailed technical information on a specific cmdlet. As some of these help files can be very long, remember that you can append |more to any command if you want to page the command output. 5. Type the following command, and then press Enter: Get-SPSite –WebApplication http://warriorThis command returns all the site collections that exist in the http://warrior Web application. (Note: Your results on your HOL VM may vary from the screen shot below.) You can use the same approach to retrieve information at each level of the SharePoint architecture. For example, you can retrieve all the Web applications in your server farm, all the site collections within a specific Web application, or all the individual sites within a site collection. Retrieving Information from the Server Farm Windows PowerShell provides a highly sophisticated and very powerful interactive scripting language. This can be somewhat daunting to new users. Fortunately, the SharePoint snap-in for Windows PowerShell includes many straightforward cmdlets that can retrieve information from the SharePoint Server farm without requiring the ability to write sophisticated scripts. In addition to being an invaluable tool in day-to-day administrative tasks, these cmdlets also provide a great starting point to learn more about Windows PowerShell. In this task, you will explore cmdlets that retrieve information from a SharePoint server farm. When you are not sure which cmdlet you need to perform a particular task, you can use the Get-Command cmdlet to find out what is available. For example, suppose you want to review which cmdlets can retrieve information from SharePoint Server 2010. 1. Type the following command, and then press Enter: Get-Command Get-SP* |more The console window displays the names of all the cmdlets that start with Get-SP. The verb Get is common to all cmdlets that return information, and the noun prefix SP is common to all SharePoint cmdlets. The asterisk is a wildcard character. Note: You can use the same approach to find cmdlets relating to specific areas of functionality. For example, Get-Command *Service* will return all service-related cmdlets. We will now explore some of the more commonly used Get cmdlets. 2. Type the following command, and then press Enter: Get-SPServiceApplication | Select ID, Name The console window displays the ID and Name properties of each service application that is running in the server farm. We‟ll study the pipe character and the Select syntax later in the lab. Lets consider a more realistic example. Suppose the event logs identify a problem with a service application and provide a GUID. You need to find out which service application is causing the problem. 3. Note the ID for the Access Service in the list, you will need to enter it in the next command. A quick way to copy text from within the Management Shell window is to select text using the mouse cursor and press Enter. This copies the text to the clipboard. 4. Type the following command, and then press Enter: Get-SPServiceApplication –Identity <Identity from previous step> To paste text within the Management Shell, simply right-click in the window. The copied text will paste where the blinking cursor is sitting. The console window provides details of the service application and identifies the corresponding IIS application pool. Now let‟s take a look at Feature management. In the course of many routine deployment and troubleshooting tasks, you will need to find the GUID that corresponds to a particular SharePoint feature. This was a somewhat laborious task in previous versions of SharePoint Products and Technologies, and administrators would often resort to full-text searches of the Features folder on the file system. SharePoint Server 2010 provides a far more straightforward approach to this problem through Windows PowerShell. 5. Type the following command, and then press Enter: Get-SPFeatureThe console window provides a list of all the installed features in the server farm, together with an ID and scope for each feature. In addition to retrieving a list all the installed features in a server farm, you may also want to retrieve a list of all the features that are activated to a particular scope. To do this, you can add a switch parameters to the Get-SPFeaturecmdlet (Site, Web, WebApplication, or Farm). 6. Type the following command, and then press Enter: Get-SPFeature –Site http://portal.contoso.com The console window provides a list of all the features that are activated on the portal.contoso.com site collection. Another useful application of PowerShell for SharePoint Server 2010 administrators is the built-in ability to parse SharePoint log files. Creating Sites and Setting Properties In addition to retrieving information, the SharePoint snap-in for Windows PowerShell includes cmdlets that can set properties, create new items, and perform a wide range of other actions. In this task, you will explore how you can put these cmdlets to use in your SharePoint server farm. Let‟s start by examining the Set-SPSitecmdlet. You can use this cmdlet to configure a range of properties on a specific site collection. 1. Type the following command, and then press Enter: Set-SPSite –Identity http://portal.contoso.com –SecondaryOwnerAliascontoso\\andyr2. Open Central Administration. 3. On the Central Administration home page, click the Application Management heading. 4. Under Site Collections, click Change site collection administrators. 5. Click the site collection name dropdown and select Change Site Collection. 6. In the window that opens, click http://warrior:9749 in the Web Application dropdown and select Change Web Application. 7. Select SharePoint – portal.contoso.com from the list, then click OK. 8. On the Site Collection Administrators page, verify that Andy Ruth has been added as the Secondary Site Collection Administrator. In isolation, it may have been quicker to specify the site collection administrator through the Central Administration user interface. However, imagine you want to add a secondary site collection administrator to 200 site collections. Rather than configuring 200 site collections manually in Central Administration, you could write a few lines of PowerShell script to loop through the site collections and add a secondary site collection administrator to each one. For the final part of this task, let‟s take a look at how you can use Windows PowerShell to create and delete sites. 9. Switch back to the SharePoint 2010 Management Shell. Type the following commands and press Enter after each: New-SPSite –Url http://portal.contoso.com/sites/powershell –OwnerAliascontoso\\Administrator -Name "PowerShell Site" -Template STS#0 New-SPSite –Url http://portal.contoso.com/sites/project1 –OwnerAliascontoso\\Administrator -Name "Project Site" -Template STS#0 Note: If you do not specify a template parameter, you will be directed to a template picker page when you browse to the site for the first time. 10. When the command returns, switch to the browser window and browse to http://portal.contoso.com/sites/powershell. (If you are prompted for a login, use warrior\\ricktas the Username and Moroni1234 for the password.) Verify that a new team site has been created at the URL. 11. Browse to http://portal.contoso.com/sites/project1 and verify that a team site has also been created at this URL. 12. Switch back to the SharePoint 2010 Management Shell. Type the following command, and press Enter: Remove-SPSite http://portal.contoso.com/sites/powershell 13. At the confirmation prompt, type Y and press Enter. 14. When the command returns, switch to the browser window and attempt to browse to http://portal.contoso.com/sites/powershell. Verify that the site no longer exists. Note: If you wanted to suppress the confirmation prompt you could have added the option -confirm:$false to the command. Exercise 2: Get More from Windows PowerShell Up to this point, you have used simple SharePoint cmdlets in isolation. When you use cmdlets in this way, it can be somewhat difficult to fully understand the advantages of Windows PowerShell when compared to standard, non-interactive command line tools such as stsadm. The real benefits to adminstrators become apparent when you begin to use some of the more advanced features of Windows PowerShell, such as combining cmdlets, creating filters, and using wildcards. In this exercise, you will explore how to use these features to your advantage when you perform administrative tasks in the SharePoint 2010 Management Shell. Combining CmdletsIn this task, you will learn how to combine cmdlets and how to pass data from one cmdlet to another. 1. In the SharePoint 2010 Management Shell, type the following command, and then press Enter. Get-Help Get-SPWebNotice that the Site parameter accepts an object of type SPSitePipeBind. This indicates that in addition to providing a value for the parameter directly, you can also use the pipe character "|" to pass in the value from the output of another cmdlet. 2. Type the following command, and then press Enter. (Note: your results may be different than the screenshot below, depending on the configuration of your HOL VM.) Get-SPSite http://portal.contoso.com | Get-SPWebSo what does this command represent? You are using the Get-SPSitecmdlet to get a reference to the site collection at portal.contoso.com, then passing this reference to the Get-SPWebcmdlet. The Get-SPWebcmdlet then returns all the sites at the passed-in site collection. This is functionally equivalent to the following command: Get-SPWeb –Site http://portal.contoso.com So why use the pipe character, if you can achieve the same result without it? As your PowerShell scripts become more sophisticated, you may not always know the values that you need to pass into a cmdlet in advance. As you progress through the remainder of this lab, you will see examples where this is the case. You can also use cmdlets directly to provide parameter values for other cmdlets. Consider the Get-SPLogEventcmdlet that we examined earlier. Suppose you wanted to retrieve all events that happened in the last fifteen minutes. 3. Type the following command, and then press Enter. Get-SPLogEvent –StartTime (Get-Date).AddMinutes(-15) (Note: Normally, you could also use –Limit all with the Get-SPLogEventcmdlet, but testing has found that this particular HOL beta build contains an error with the Limit parameter) The console window displays a list of the events which occurred in the last fifteen minutes. As you have yet to configure event log throttling in your server farm, you will notice that the list is rather long. So what is actually happening here? The Get-Date cmdlet returns an object of type DateTime. The DateTimeclass includes a method named AddMinutes, that returns the current date and time adjusted by the number of minutes that you pass in. The Get-SPLogEventcmdlet uses this value as the input for the StartTimeparameter. If you use the same approach to specify the EndTimeparameter, you can retrieve all the events that occurred in a specific time window. 4. Type the following command, and then press Enter. Get-SPLogEvent –StartTime (Get-Date).AddMinutes(-15) –EndTime (Get-Date).AddMinutes(-5) The console window displays a list of the events which occurred between fifteen minutes ago and five minutes ago. One final technique to consider in this task is how you can use the select keyword to process the results returned by a cmdlet. For example, suppose you want to retrieve a list of all the event categories in which an event of severity "warning" has occurred. 5. Type the following command, and then press Enter. (Note: while most PowerShell cmdlets are not case-sensitive, in this instance “Warning” needs to be capitalized to follow proper syntax.) Get-SPLogEvent –MinimumLevel Warning | Select Category -Unique The console window in the screenshot below indicates that there are several categories returning warnings in the event log. (Note: Your results may be different based on VM) You can use the select keyword in conjunction with any property of the objects that you are retrieving. In this case you are retrieving objects of type SPLogEvent. The SPLogEventincludes a property named Category. Using Filters and Wildcards In this task, you will explore the use of filters and wildcards to refine the functionality of SharePoint cmdlets. To start with, lets look at the use of a simple wildcard character "*". Suppose you want to retrieve a list of site collections on the managed path http://portal.contoso.com/sites/. 1. Type the following command, and then press Enter. Get-SPSite http://portal.contoso.com/sites/* Note: This expression is shorthand for Get-SPSite –Identity http://portal.contoso.com/sites/* The command window displays a list of site collections that lie on the managed path you specified. The ability to use wildcards can be particularly useful when you combine cmdlets. For example, suppose you want to make Andy Ruth the secondary site collection administrator for all site collections on the managed path http://portal.contoso.com/sites/. 2. Type the following command, and then press Enter. Get-SPSite http://portal.contoso.com/sites/* -Limit All | Set-SPSite –SecondaryOwnerAliascontoso\\andyrAt this point, the efficiency of PowerShell should start to become apparent. With a single command, you have changed the secondary site collection administrator on multiple sites. Note: You can only use the Get-SPSitecmdlet if you are already a site owner. If this is not the case, you can use the Get-SPSiteAdministrationcmdlet to retrieve the site object. To verify that the command has worked, you can use another cmdlet with the select keyword we discussed earlier. 3. Type the following command, and then press Enter. Get-SPSite http://portal.contoso.com/* | Select Url, SecondaryContactThe command window displays a list of site collections by URL and secondary site collection administrator. You can see that all the sites on the http://portal.contoso.com/sites/ managed path now have Andy Ruth as the site collection administrator. A few cmdlets also provide a Filter parameter that you can use to constrain the results returned.
• #18: 4. Type the following command, and then press Enter. Get-SPSite –Filter {$_.OwnerAlias –eq “warrior\\rickt"} The command window displays a list of all site collections for which Andy Ruth is the Secondary Site Collection Administrator. Filter strings always take the format {$_.PropertyName <operator> "FilterValue"}. The variable "$_" represents the data in the pipe – in other words, it is a reference to the type returned by the query, which in this case is SPSite. The operator can take a number of forms:  -lt (less than)  -le (less than or equal to)  -eq (equal to)  -ge (greater than or equal to)  -gt (greater than)  -ne (not equal to)  -like (matches a wildcard pattern)  -notlike (does not match a wildcard pattern) Another approach to filtering is to pass your cmdlet output to the Where-Object cmdlet. You can use the question mark character "?" as shorthand for Where-Object. This cmdlet filters the objects that are passed along the command pipeline according to a filter string that you specify. You can use Where-Object to filter the output from any cmdlet. 5. Type the following command, and then press Enter. Get-SPLogEvent | ?{$_.Level –eq "High"} | Select Category, Message The command window displays a list of all log events where the value of the Level property is High. (Your log events may be different than the screenshot shown here.) If needed, you can interrupt the listing of events by pressing Ctrl-C. You can also use Regular Expressions to constrain the results returned by a cmdlet. The Get-SPSitecmdlet includes a RegExparameter that causes the URL provides for the Identity parameter to be treated as a Regular Expression. Suppose you want to retrieve a list of all site collections on the http://portal.contoso.com/sites/ and the http://portal.contoso.com/my/ managed paths. 6. Type the following command, and then press Enter. Get-SPSite “http://portal.contoso.com/(sites|my)/.*” -RegEx –Limit All | Select UrlThe command window displays a list of all the site collections that lie on the managed paths that you specified. Enumerating Collections When it comes to repetitive tasks, the ability to loop through collections of objects is an invaluable tool in the armory of the Windows PowerShell script writer. In this task, you will learn how to enumerate collections and perform actions on each object in the collection. Windows PowerShell includes the ForEach-Object cmdlet (or foreachin shorthand) that you can use to enumerate over a result set. To use the ForEach-Object cmdlet, you must pass in a collection of objects, and you must provide the actions to perform on each object within curly brackets. Suppose you want to provision a team blog site on every site collection on the http://portal.contoso.com/sites/ managed path. 1. Type the following command, and then press Enter. Get-SPSite http://portal.contoso.com/sites/* -Limit All | foreach{New-SPWeb –Url ($_.Url + "/blog") –Template BLOG#0} The command window returns a list of URLs at which new blog sites have been created. 2. Browse to one or more of the URLs to verify that the blog sites were created correctly. Sign in as contoso\\administrator with a password of pass@word1 if prompted. In the final exercise of this lab, when we discuss assigning variables and using the SharePoint object model, you will see more sophisticated ways of working with the ForEach-Object cmdlet. Exercise 3: Perform Advanced Tasks with PowerShell In the previous exercise, you saw how some of the features of Windows PowerShell enable you to create scripts that go way beyond the capabilities of previous command-line tools such as stsadm. In this exercise, you will take this a step further and learn how you can use the full power of the SharePoint object model from the Windows PowerShell command prompt. Using Local Variables The ability to create and assign values to local variables is a powerful benefit when you use Windows PowerShell. However, if you have previously worked with the SharePoint object model you will know that certain objects, such as SPSite and SPWeb, need to be managed carefully to avoid excessive memory use. In this task, you will learn how to assign and dispose of local variables in your Windows PowerShell scripts for SharePoint. The SharePoint snap-in for Windows PowerShell provides two key cmdlets that you can use to manage variable assignment: Start-SPAssignmentand Stop-SPAssignment. 1. In the SharePoint 2010 Management Shell, type the following command, and then press Enter. Start-SPAssignment -Global 2. Type the following command, and then press Enter. $Web = Get-SPWeb http://portal.contoso.com 3. Type the following command, and then press Enter. 4. Type the following command, and then press Enter. $Web.Update() 5. Type the following command, and then press Enter. Stop-SPAssignment -Global In this case, we are using the global assignment model. After we call Start-SPAssignment –Global, any objects that we create are assigned to a global assignment store. This ensures that the objects remain available while we use the object model to set properties and call methods (more on this later). When we call Stop-SPAssignment –Global, any objects in the global assignment store are disposed of and the memory is released. Note: Use global assignment with caution! For example, if you use Start-SPAssignment –Global with and then call Get-SPSite –Limit ALL, every site collection object will be loaded into memory. In a live server farm, this is likely to cause to cause serious performance issues. 6. Open a browser window and browse to http://portal.contoso.com. Log in as contoso\\administrator if prompted. 7. Click Site Actions > Site Settings. 8. Under Look and Feel, click Title, description, and icon. 9. Verify that the site description reflects the changes you just made using PowerShell. When you write complex, long-running scripts, you may require more granular control over how memory is assigned and released. Rather than assigning all your variables to a global assignment store, you can use named assignments stores that enable you to assign and release different objects at different points in your script. $Web.Description = "Testing variable assignment!" Suppose you want to create a News site on every site collection on a particular managed path, and then set a few properties on each News site. 10. Switch back to the Management Shell and type the following command, then press Enter. $SiteScope = Start-SPAssignment11. Type the following text, and then press Enter. Foreach($Site in ($SiteScope | Get-SPSite http://portal.contoso.com/sites/*)) Notice that when you press Enter, the PowerShell prompt changes to a double chevron (>>). This indicates that Windows PowerShell recognizes that your procedure is incomplete, and will accept multiline input without attempting to execute every time you press Enter. 12. Type the following text, and press Enter after each line. { Get-SPFeaturePublishingSite | Enable-SPFeature –Url $Site.UrlNew-SPWeb –Url ($Site.Url + "/news") $WebScope = Start-SPAssignment$Web = $WebScope | Get-SPWeb ($Site.Url + "/news") $Web.Title = "Team News" $Web.Description = "All the latest news and information" $Web.Update() Stop-SPAssignment $WebScope} Stop-SPAssignment $SiteScope13. Press Enter again. The entire command should now execute. (It may take a minute for the command to run.) Your output may differ slightly from the screenshot below. In this case, you are creating two different assignment scopes. The scope named $SiteScopeis used to store references to site collections, and is not cleared until the entire procedure is complete. The scope named $WebScopeis used to store references to individual sites, and is cleared after each individual site is processed. 14. Browse to one of the URLs returned by the command window and verify that the News site has been created and configured properly. Since no template was specified in the site creation process, choose Team Site from the Collaboration Tab and click OK to create the site. Note: In addition to enabling you to create and assign values to local variables, Windows PowerShell also provides access to environment variables. For example, you can use $env:osto retrieve the local operating system, or $env:computernameto retrieve the local computer name. Using the Object Model In the previous task, you saw some examples of how you can assign local variables and then use the SharePoint object model to set properties and call methods on those variables. In this task, you will learn more about how to use the SharePoint object model in your PowerShell scripts. When you start to use the object model, it is essential to be able to find out what methods and properties a particular object supports. Luckily, Windows PowerShell includes a cmdlet named Get-Member that can help. You can pass any object into the Get-Member cmdlet to return a list of the available properties and methods on that object. 1. In the SharePoint 2010 Management Shell, type the following command, and then press Enter. Get-SPSite | Get-Member The command window displays a long list of the methods and properties that you can access on an SPSite object. You can experiment with the object model by writing property values to the screen. Remember to create a memory assignment before you create a local variable. 2. Type the following command, and then press Enter. Start-SPAssignment -Global 3. Type the following command, and then press Enter. $Site = Get-SPSite http://portal.contoso.com 4. Type the following command, and then press Enter. Write-Host $Site.UrlThe console window displays the URL of the site collection. 5. Type the following command, and then press Enter. Write-Host $Site.ZoneThe console window indicates that the site collection is in the Default zone. 6. Type the following command, and then press Enter. Write-Host $Site.QuotaBecause the site quota is a complex type that is not well represented by a string, the console window simply displays the type name of the SPQuota object. As before, you can use the Get-Member cmdlet to find out more about the SPQuota object. 7. Type the following command, and then press Enter. $Site.Quota | Get-Member 8. Type the following command, and then press Enter. $Site.Quota | Select StorageMaximumLevelThe command window shows a maximum site storage of zero, which indicates that the site does not have a usage quota assigned. As an administrator, you find this deeply disturbing. You immediately put a quota of 50MB in place, together with a warning level of 40MB. 9. Type the following command, and then press Enter. $Site.Quota.StorageMaximumLevel = 52428800 Note: 52,428,800 represents 50MB in bytes. 10. Type the following command, and then press Enter. $Site.Quota.StorageWarningLevel = 41943040 Note: 41,943,040 represents 40MB in bytes. 11. To confirm your quota settings go to Central Administration. Open a browser window, browse to http://moss:5555. 12. Click on the Application Mangagementheading. 13. Under Site Collections, click on Configure quotas and locks. 14. Change the site collection to http://portal.contoso.com 15. Change the Web Application to http://portal.contoso.com and make sure the root site is selected. Click OK. 16. Confirm the new quota in the Site Quota Information section. Finally, when you have finished using the $Site variable, remember to clear the memory assignment. 17. Switch back to PowerShell and type the following command, and then press Enter. Stop-SPAssignment -Global