PowerShell Objects
Understanding exactly what an object is
can be complicated, but a car provides a useful analogy. Like an
object, a car has properties. Properties are information about the
object, such as the car’s color, make, model, weight, whether it has
been flooded or not, and so on. If you’re given the object car, instead
of the word “car,” you can use those properties to make decisions. If
you have a group of car objects, you can decide to view only the blue
ones by checking the car.color
property. That’s one aspect of strings that lets you down. When you get
a list of site collections from STSADM, you get text. If you want
information that isn’t in the text, you have no way to get more
information; and if the information you need is hidden somewhere in
that string, you have to do complicated text manipulation to get it
out. Objects make this type of work much easier.
Continuing with the analogy, like objects, cars
also have methods. Methods are actions you can take with your object.
For the car example, a method might be start, accelerate, slowdown,
rolldownwindows, driveoffcliff, and so on. Objects are treated the same
way — different methods are associated with different object types. The
car in your garage is an instance of the object car, and it has
different properties than other instances of the car object, such as
those in your neighbor’s driveway. Methods are one way in which you
interact with the objects. The SPSite object has a dispose method, which flushes it out of RAM. It also has a delete method, which is one way to delete an SPSite object.
PowerShell Pipeline
You’ve already seen how using objects
makes PowerShell better than STSADM. The pipeline is another PowerShell
feature that enables you to take your scripting up another notch. In
particular, it enables you to create the aforementioned one-liners by
chaining together the output of one cmdlet to the input of another
cmdlet. For example, the Get-SPSite command returns all site collections in the farm. The Get-SPWeb command returns 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 your farm (excluding any within the Central Administration web applications), use the following command (see Figure 5):
Get-SPSite –Limit ALL | Get-SPWeb –Limit ALL
What are being passed between these commands are
objects. You will soon see how you can use the methods and properties
of these objects to further control what is passed, and how the
recipient cmdlet can filter the incoming object to get to the property
on which it needs to act.
BLEEDING ON THE SCREEN
When you run the preceding Get-SPSite/Get-SPWeb
one-liners, instead of getting a friendly list of all the webs in your
farm you might instead get a screen full of red error messages. This is
how PowerShell shows its displeasure. Several things can raise
PowerShell’s ire, a fact that will become very evident the more you use
PowerShell. In this case, it’s probably caused by a lack of permissions
to the Config database or one of the content databases. PowerShell
accesses SharePoint and its SQL Server databases with the identity of
the user PowerShell is running as, so that user must have permission to
whatever he or she is trying to access.
There are two ways to do this. First,
you can make the user db_owner on all the SharePoint databases or give
the user the SYSADMIN role on the SQL Server instances being used. That
works, but from a security standpoint it’s not great. A second, better
way is to run the Add-SPShellAdmin
cmdlet to give the user permission to the databases to which he or she
needs access. This must be run as a user with db_owner rights to the
database in question. The Add-SPShellAdmin cmdlet must be run for all users against each database they need to run PowerShell against. You can run Get-Help Add-SPShellAdmin to get more information.
Controlling Output
Armed with a basic understanding of the
pipeline and its use of objects, this section takes a look at how to
control the output of these objects. While the pipeline passes objects
around, the input you provide to PowerShell and the output you expect
returned at the end is always text. PowerShell handles this with ease.
When an object hits the end of a pipeline, it must be captured to a
variable, set to void, or formatted for the screen as text. You have
already looked at using variables, so you should be familiar with the
concept of capturing. Void is a
fancy developer term for nothing, or a null value. You don’t need to
worry about void. Formatting, however, is something that you will
likely want to wrangle control of in order to view the data you want in
a form that makes sense to you.
By default, PowerShell formats the output of an
object in a table, with columns representing a handful of the most
useful properties of the object. In many cases it is fine to let
PowerShell format your objects for display in its own default fashion.
When an object makes it to the end of the pipeline, the default
formatters automatically take effect, unless overridden.
Consider the default formatting for the SPFarm object using the Get-SPFarm command. In Figure 6, you can see that the Config database Name and Status properties are returned from the SPFarm
object, which is the default format for output from that object.
However, while those are key properties, they are not the only
properties associated with the SPFarm object.
By controlling the output, you can view
additional properties and specify how you want the objects formatted.
You control the format using the format commands, the most common of
which are Format-List and Format-Table (fl and ft
are the respective aliases for these commands). There are a few others,
but this section looks at only these two common formatting commands.
A WORD ABOUT ALIASES
As you’re getting up to speed with
PowerShell you’ll probably “borrow” several PowerShell scripts from
various websites. There’s nothing wrong with that, as long as you
properly credit your sources. It’s a great way to learn how to use
specific PowerShell cmdlets. You’ll see weird symbols such as ? and %. What does it all mean?
To ease the transition from other
languages, such as Windows or Linux shell scripting, PowerShell
supports the use of aliases. An alias is an alternative way to
reference some PowerShell cmdlets. If you’re ever reading someone else’s PowerShell code and you see commands you don’t recognize, run the PowerShell cmdlet Get-Alias
to determine whether the unknown command is an alias for something
else. Because aliases can be confusing, it is recommended that you
avoid them while learning PowerShell.
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 outputs, you can assume that you
are looking at objects formatted in list style. The example shown in Figure 7 displays the SPFarm object’s returned properties in List view, after using the Format-List command. 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. Use Get-Member to get a list of the properties for the object you’re formatting.
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 properties 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 resembles The Matrix — 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 display only the
DisplayName, Status, and BuildVersion properties. Figure 8 shows an example result using the following command:
Get-SPFarm | Format-Table –Property DisplayName, Status, BuildVersion
Additionally, the –Property parameter is assumed to be the default value passed to the Format-Table command. The following example shows the preceding command but using the short name of the Format-Table command and passing the desired properties:
Get-SPFarm | Format-Table DisplayName, Status, BuildVersion
Of course, the output of the preceding two commands is identical.
To learn more, use these two help commands:
Get-Help Format
Get-Help Out
NOTE To clear the screen, use CLS, which is an alias for Clear-Host.
