252 ❘ CHAPTER 10 admiNisteriNg sharePoiNt 2010 With WiNdoWs PoWershell COMMANDS PowerShell is powered by commands. Commands get things done. There are four basic types of commands: cmdlets, functions, scripts, and native commands. It is not necessarily important to know the differences among these command types to work with PowerShell and SharePoint, but it doesn’t hurt either. If you are just starting out with PowerShell, you can fi nd a wealth of general information at http://microsoft.com/PowerShell. Cmdlets Cmdlets (pronounced command-lets) are compiled commands that are registered with PowerShell. They have a very specifi c naming convention: All cmdlets are named with a verb-noun combina- tion. The verb portion of the name should be one of the PowerShell accepted verbs. PowerShell defi nes a list of these verbs and what they mean at http://msdn.microsoft.com/en-us/library/ ms714428(VS.85).aspx . Because the verbs are “standardized,” you can usually guess the verb portion of the cmdlet. An example of a cmdlet is New-SPWebApplication, which has a corresponding Remove- SPWebApplication. You might have expected to use the verb “delete” to delete a SPWebApplication, but delete is not one of the standardized verbs, so it cannot be used. Cmdlets are installed and registered. As you might have already guessed, the SharePoint commands that we will be using are cmdlets. You saw that SharePoint installed the cmdlets on the server, and the Management Shell registered them with the host using the PSC1 fi le; and you now know how to manually register them in the ISE. You can also create custom cmdlets, but that is a topic beyond the scope of this book. You can learn more about writing your own cmdlets in this MSDN article: http://msdn.microsoft.com/en-us/library/dd878294(VS.85).aspx. Functions Functions can contain one or more commands to accomplish a task, and can accept parameters that allow the creation of custom reusable code. They are defi ned in PowerShell by typing the function into the host. PowerShell then compiles the function and verifi es the syntax. Functions can be reused for the lifetime of the host session. If you close the host, then you lose the function; and it will need to be entered again when you start another session with the host. You can enter functions into your profi le so they will be available whenever you start a session. There’s nothing worse than working on an award-winning function, only to lose it when you shut down the host. Consider yourself warned and save your func- tion in your profi le or at least to a text fi le so you can copy it later. Functions have their place and are great for containing code that you will want to call from various other scripts or commands, but with a single chapter for administering SharePoint using PowerShell, we have no space to cover them in depth here. Basic PowerShell ❘ 253 Scripts Scripts are a combination of commands, functions, and practically anything PowerShell. Because SharePoint 2007 did not have cmdlets, PowerShell scripts were very important. Now that we have more than enough cmdlets with SharePoint 2010, they are not as important for daily work. Scripts are useful for common reusable code, but SharePoint administration often results in the use of “one-liners.” There is no big secret behind scripts; create a script in your favorite text editor or ISE and save it to the fi le system with a . PS1 fi le extension. Later you can run the script by typing in the fi lename. Scripts, in contrast to functions or PowerShell snap-ins, survive the host shutdown and can easily be recalled. Another great benefi t of the script is that once a script is created and tested, it can be saved to a script library and reused. By default, the hosts do not run unsigned scripts. Hosts will warn if you attempt to run a script that has not been signed. You can modify the security setting using the cmdlet Set-ExecutionPolicy. Because so much can be accomplished using the SharePoint cmdlets, we will not be doing much with scripts in this chapter. Scripts are only necessary if you want to chain together a complicated series of cmdlets, or walk through complicated loops. For security reasons, the PowerShell application is not associated with .PS1 fi les. The default application associated with . PS1 fi les is Notepad, so double-clicking a . PS1 fi le will open the fi le in Notepad. This effectively stops the user from double-clicking a malicious script and running it. If you change the fi le associa- tion, which is not recommended, you run the risk of inadvertently running a malicious script. Native Commands Native commands are commands that run outside of the host process. We have already used a native command, Notepad. If you are still hooked on STSADM.exe, you can use STSADM as a native command in the host. But with all the PowerShell goodness and the SharePoint commands, why would you? BASIC POWERSHELL Entire books have been written on PowerShell, so it is not possible to cover the basics in a single chapter. But we won’t just you throw you to the wolves with PowerShell. Here we cover a few key things to help the newer “PowerShellers” out there (or is it “SharePointShellers”?). Many of the SharePoint PowerShell commands can be used as a one-liner or “standalone,” so a true understand- ing of PowerShell is not always required. That said, understanding a few PowerShell concepts in conjunction with the SharePoint commands can help you along the way. 254 ❘ CHAPTER 10 admiNisteriNg sharePoiNt 2010 With WiNdoWs PoWershell Listing the SharePoint Commands PowerShell provides the Get-Command cmdlet to retrieve a list of available commands. The Get-Command parameter will retrieve all commands that are known to the host. Get-Command, like many commands, accepts optional parameters. Since we are interested in only the SharePoint 2010 commands, we can limit the commands displayed to just the SharePoint 2010 commands by using the optional -Module parameter. To list only SharePoint commands, execute the following command: Get-Command -Module Microsoft.SharePoint.PowerShell Figure 10-4 displays the output of the Get-Command cmdlet using the –Module parameter. FIGURE 104 Did you catch all that? At last count there were over 500 PowerShell cmdlets included with SharePoint 2010. This might still be a few more commands than you want to list. The list can be pared down some if you use the optional - noun or -verb parameter for Get-Command. For example, if you were wondering what commands work with a Web application, use the following command: Get-Command –Module Microsoft.SharePoint.PowerShell –noun SPWebApplication If you need to know which command to use for backups, use the following command: Get-Command –Module Microsoft.SharePoint.PowerShell –verb Backup Figure 10-5 shows how you can control the output of Get-Command with the –noun and –verb parameters. Basic PowerShell ❘ 255 FIGURE 105 PowerShell Help As shown in the preceding section, Get-Command will help you determine which command you should use to accomplish a task. Get-Help will help you understand the usage of a command. The Get-Help command is a standard PowerShell cmdlet. To get help for a particular command, simply call Get- Help, passing in the name of the command for which you want help. For example, if you wanted to see help about New-SPWebApplication, you would use the following: Get-Help New-SPWebApplication Figure 10-6 shows the help returned for New-SPWebApplication. It provides you with numerous details about the command, including parameters, examples, and usage. Get-Help accepts the optional param- eters of - detailed and -examples. Examples of your options are shown at the bottom of Figure 10-6 under the Remarks heading. To learn more about Get-Help, simply use Get-Help Get-Help — a little redundant but it works. PowerShell Variables We can’t ignore the topic of variables, which gets us frighteningly close to developer work. In a basic sense, variables hold information. Typically, variables don’t come into play until you start doing more of the common one-liner commands. All PowerShell variables start with the $ character and can hold any type of object. Certain objects in SharePoint such as SPWeb, SPSite, and SPSiteAdministration, must be properly disposed of. One-liner SharePoint commands will dispose of all objects correctly. Storing these SharePoint objects in variables can lead to performance issues and memory leaks if the variable is not handled correctly. This section on variables specifi cally avoids using these SharePoint objects until the dispose subject can be addressed later in the chapter. 256 ❘ CHAPTER 10 admiNisteriNg sharePoiNt 2010 With WiNdoWs PoWershell FIGURE 106 In Figure 10-7, the variable $webApps is set to the output of Get-SPWebApplications. $webApps now contains all of the Web application ( SPWebApplication) objects. You use the count property to determine how many Web applications are contained in the variable. You can display the Web applications by simply typing the variable name. FIGURE 107 Wondering which commands were used to get the output displayed in the screen- shots of the Management Shell? Just take a look at the top of the fi gures to see the commands following the Administrator prompt. Basic PowerShell ❘ 257 THE FORMERLY DREADED “OBJECTS” We thought we would add a few words about our friends, the objects. As admin- istrators, we have been able to stay blissfully ignorant of these pesky little devils. Until now. In previous versions of SharePoint we had STSADM. STSADM was good to us. When we needed to interact with it, we gave it strings like http:// portal.company.com , WSS_ContentDB, or domain\username. And when STSADM replied back to us, it reciprocated with easy to understand strings. Strings are just text, so they’re easy to use. We managed SharePoint with strings and we liked it. Then this fancy PowerShell comes along with its snap-ins and its cmdlets and its objects. What exactly is an object? It’s complicated, but it helps to think of an object like a car. Like an object, a car has properties. Properties are information about the object, things like color, numberoftires, make, model, smellslikefeet, and so on. If we’re given the object car, instead of the word “car” we can use those properties to make decisions. If we get a group of car objects, we can decide to only view the blue ones by checking the car.color property. That’s one place where strings let us down. When we got a list of site collections from STSADM we got text. If we wanted information that wasn’t in the text, we had no way to get more information, and if the information we needed was hidden somewhere in that string, we had to do complicated text manipulation to get it out. Objects make sorting this out easier. Like our objects, cars also have methods. Methods are actions you can do with your object. In our car example a method might be start, accelerate, slowdown, rolldownwindows, driveoffcliff, and so on. Objects are the same way. We have methods associated with different object types. Those methods are one way we interact with the objects. The SPSite object has a dispose method, which fl ushes it out of RAM. It also has a delete method, which is one way to delete an SPSite object. See, objects aren’t scary at all. Okay, maybe a little. Hopefully after this little chat we’ve all become fans of objects and we appreci- ate them for the functionality they provide, and no longer hold their complexity against them. It’s important to note that the Get-SPWebApplication cmdlet does not include your Central Admin web application by default. You have to include the parameter –IncludeCentralAdministration for Central Administration to be included. Also, if you have only a single content web application the . count does not return 1, like you would expect. It returned nothing, nada, zilch. Variables enable you to hold onto objects and data for later use in your commands and scripts. Obviously, variables do not survive a host shutdown, but you can create and set a variable in your profi le. This book generally avoids using variables because so much can be done to administer SharePoint 2010 without them, which also avoids any disposal issues. 258 ❘ CHAPTER 10 admiNisteriNg sharePoiNt 2010 With WiNdoWs PoWershell PowerShell Pipeline The PowerShell pipeline is how you chain commands together. Why chain together commands? Cmdlets are usually good at one specific task such as listing SPSite objects (think site collections). You can chain together many commands to do a more specific or targeted task. The Get-SPSite command will return all site collections in the farm. The Get-SPWeb command will return a specific web object. If you needed to retrieve all SPWeb objects, you could chain the Get-SPSite command to the Get-SPWeb command using the PowerShell pipeline. To get all the SPWeb objects on the farm (excluding any within the Central Administration Web applications), use the following command, as shown in Figure 10-8: Get-SPSite –Limit ALL | Get-SPWeb –Limit ALL FIGURE 108 We cannot leave this discussion of the pipeline without at least mentioning .NET objects. The pipe- line passes .NET objects between commands. The word “objects” might scare you a little, but you have been working with objects for some time now — with VBScript, CScript, and WMI, to name a few. Objects simply contain information and methods to act on the information or the environment. While you might shy away from objects, the fact that PowerShell uses .NET objects makes life a lot easier. For example, you can use a function such as Get-SPSite to return SPSite objects and send them to a command that will alter the objects. For a lot of what you do, objects will be sitting in the background. Basic PowerShell ❘ 259 Controlling Output Now that you know a little about the pipeline and its use of objects, we need to take a look at how to control the output of these objects. The pipeline uses objects, but all we really work with in the Management Shell is text. No problem; PowerShell is a smart application. When an object hits the end of a pipeline, it must be captured, set to void, or formatted for the screen as text. We have already looked at using variables, so you should be familiar with the concept of capturing. Void is a fancy developer term for nothing, get lost, I don’t want you. We won’t worry much about void. Formatting, however, is something to worry about, because if you don’t take care of formatting, PowerShell will. In many cases it is not a big deal that we let PowerShell format our objects for display. When an object makes it to the end of the pipeline, the default formatters take effect. Many SharePoint objects have a default format, which is usually a table format with a few key properties. Let’s take a look at the default formatting for the SPFarm object using the Get-SPFarm command. In Figure 10-9 it appears that there are only two properties associated with the SPFarm object: Name and Status. While those are key properties, they are not the only properties associated with the SPFarm object. The default format for the SPFarm object displays only the Name and Status properties. FIGURE 109 So how do you get to look at more properties? When you control the output, you get to decide how you want the objects formatted. You control the format using the format commands, the most com- mon of which are Format-List and Format-Table. There are a few others, but this section looks at only these two common formatting commands. Format-List will display object properties in list format. Each object gets one or more rows to display a property and a value. When you see text fly across the screen during some of your out- puts, you can probably assume that you are looking at objects formatted in list style. At this point, we’ll go ahead and send our SPFarm object to the Format-List command. Figure 10-10 displays the SPFarm object’s properties in List view. The Format-List command also accepts an optional Properties parameter, which enables you to provide a comma-separated list of property names to be displayed. 260 ❘ CHAPTER 10 admiNisteriNg sharePoiNt 2010 With WiNdoWs PoWershell FIGURE 1010 Format-Table will display an object’s properties in tabular fashion. Each object gets a single row and one or more columns depending on what properties should be displayed. The default format for most objects is table style, so simply piping the objects to the Format-Table might not get you much further. What will help is the optional Property parameter, which accepts a comma-separated list of proper- ties to display. You could choose to display all SPFarm properties using the following command: Get-SPFarm | Format-Table * If you do that, however, you will get a result that is practically unreadable because you attempted to put too many columns in such a small amount of space. The Format-List command is better for showing a large number of properties. For example, instead of displaying all properties, you can dis- play only the DisplayName, Status, and BuildVersion properties. Figure 10-11 shows the result of using the following command: Get-SPFarm |Format-Table –Property DisplayName, Status, BuildVersion Using SharePoint Commands ❘ 261 Due to space limitations, this chapter doesn’t cover many other formatting commands and even out- put commands to pipe content to fi les, including CSV. To learn more, use these two help commands: Get-Help Format Get-Help Out FIGURE 1011 To clear the screen, use CLS, which is an alias for Clear-Host. USING SHAREPOINT COMMANDS With more than 500 individual SharePoint 2010commands, one chapter cannot possibly cover them all. This section will get you started working with some of the more common SharePoint commands for PowerShell. Working with the Farm The Farm is the top-most SharePoint administrator object, containing key properties and collections associated with the SharePoint farm. The term “farm” can be confusing, especially in a single-sever environment. A farm is one or more servers that share the same confi guration database. The associa- tion of farm and confi guration database is carried through as the farm’s name is the confi guration database name. In SharePoint 2007, we used the Farm object quite often when we scripted commands to get to all the collections and properties. With the many SharePoint 2010 commands, you can now access many of these properties using a more specifi c command. The farm still contains many key proper- ties and methods that can be used for administration. For example, you can determine the farm’s status, display name, and version. You can access the farm using the Get-SPFarm command (refer back to Figure 10-9). The output of this command is nothing special. The default formatting for the SPFarm object is to display the Status and DisplayName. However, you learned earlier how to control formatting of the objects, so feel free to modify the output of the SPFarm object. . interested in only the SharePoint 2010 commands, we can limit the commands displayed to just the SharePoint 2010 commands by using the optional -Module parameter. To list only SharePoint commands,. concepts in conjunction with the SharePoint commands can help you along the way. 254 ❘ CHAPTER 10 admiNisteriNg sharePoiNt 2010 With WiNdoWs PoWershell Listing the SharePoint Commands PowerShell. because so much can be done to administer SharePoint 2010 without them, which also avoids any disposal issues. 258 ❘ CHAPTER 10 admiNisteriNg sharePoiNt 2010 With WiNdoWs PoWershell PowerShell