PowerShell for Microsoft SharePoint 2010 : Variables in Windows PowerShell (part 3) - Properties and Methods

Properties and Methods

Since what is actually stored in a variable is a .NET object, you can use all of its methods and properties. You can use the Windows PowerShell Get-Member cmdlet to retrieve all members of an object. Let’s store an object of the type System.String in a variable and explore its methods and properties.

PS > [string]$url = "http://SPServer01"
PS > $url | Get-Member

The Get-Member cmdlet returns information about the properties and methods of the object, as well as its type, as shown in Figure 1.

Figure 1. Using the Get-Member cmdlet to retrieve methods and properties

Now that we know which methods and properties the object supports, we can use them to retrieve information and manipulate the object. For example, to find out how many characters the string contains, type the following:

PS > $url.Length
17

The output tells us that the string’s length is 17 characters. We can manipulate the string through the various methods available. For example, we could change all the characters to uppercase, like this:

PS > $url.ToUpper()
HTTP://SPSERVER01

Notice that method calls in Windows PowerShell end with parentheses, as is common syntax for method invocation in many scripting and programming languages. If a method accepts parameters, those need to be specified within the parentheses. Let’s look at the Replace() method of the System.String type as an example:

PS > $url.Replace("http://","https://")
https://SPServer01

When you use the Replace() method, you need to provide additional information to the method telling it what to replace and what to replace it with. A simple way of finding information about a method is by calling the method without the parentheses.

PS > $url.Replace

Figure 2 shows the information returned for the Replace() method.

Figure 2. Getting the Replace() method definition

Another resource is the MSDN library (http://msdn.microsoft.com), which provides information about the classes in .NET, including the methods and properties they support. To get information about the Replace() method, search for “System.String Replace.”

In the following example, we store the output from the Get-SPWeb cmdlet in a variable and use the various methods and properties to work with the stored object. We also use the value stored in the $url variable as input.

PS > $url = "http://SPServer01"
PS > $spWeb = Get-SPWeb -Identity $url

When we type the variable’s name, the default properties of the object are displayed in the console, as shown here:

PS > $spWeb

Url
---
http://spserver01

To display all of the object’s properties, pipe the object to the Format-List cmdlet, as shown in this example:

PS > $spWeb | Format-List

Let’s take a closer look at the methods and properties available on the SPWeb object.

PS > $spWeb | Get-Member

Figure 3 shows the available methods and properties.

Figure 3. Methods and properties of an SPWeb object

You can retrieve values of specific properties by using standard property notation—appending a property’s name to the object-containing variable with a dot.

PS > $spWeb.Url
http://spserver01
PS > $spWeb.Title
Home
PS > $spWeb.Created

Sunday, March 28, 2010 11:44:11 PM

You can also use a pipeline and the Select-Object cmdlet to retrieve specific properties from a site.

PS > $spWeb | Select-Object -property IsRootWeb, WebTemplate, WebTemplateID

IsRootWeb   WebTemplate   WebTemplateId
---------   -----------   -------------
     True   STS                     1

In the example, we select the IsRootWeb property, which tells us if the current site is the root site of a site collection, and the WebTemplate and WebTemplateId properties, which indicate the site definition and configuration (template) used to create the site (in this case, STS1, which corresponds to the Blank Site template).

Our new variable $spWeb is an instance of the Microsoft.SharePoint.SPWeb type, which lets us access the broad variety of methods and properties offered by this type. In the next example, we use this object’s EnsureUser method to check if a specific login name belongs to a valid user of a SharePoint site.

PS > $spWeb.EnsureUser("powershell\sezel")

UserLogin            DisplayName
---------            -----------
POWERSHELL\sezel     Sergey Zelenov

Since the user sezel is not currently a known user of the site, the user is added to the site’s User Info list.

You can also modify the site through the methods and properties available.

PS > $spWeb.Description
Home
PS > $spWeb.Description = "Changed through PowerShell"

PS > $spWeb.Update()
PS > $spWeb.Description
Changed through PowerShell

In the example, we begin by retrieving the current description. Then we assign a new string value to the Description property, and finally, we use the Update() method to commit the changes we made. When we retrieve the object again, the description is changed.

When you are finished working with an object, use the Dispose() method to ensure that the object is disposed of correctly.

PS > $spWeb.Dispose()

This is good practice because SPWeb, SPSite, and SPSiteAdministration objects may take up large amounts of memory.