Working with the SharePoint 2010 Management Shell (part 7) - Using Parameters

12/13/2010 2:50:11 PM
2.3. Using Parameters

To find which parameters you can use with a cmdlet, type either Get-Help <cmdlet> or Get-Command <cmdlet> -syntax, where <cmdlet> is the name of the cmdlet you want parameter information about. For example, Get-Help New-SPSite or Get-Command New-SPSite –syntax will provide you with information about the parameters associated with New-SPSite. The Get-Help cmdlet also has several parameters associated with it, and depending on the amount of information you want, you can use them with the Get-Help command. If you know a cmdlet very well and do not want a descriptive explanation of what the cmdlet does, then you may simply want to see some examples of how to use the cmdlet, in which case you would type Get-Help New-SPSite –examples.

To learn about which parameters to use with a cmdlet, review the syntax section of the help results, as shown in the following output. Optional parameters are enclosed within square brackets ([ ]) and the values to be passed to the parameters are enclosed within angled brackets (<>). The following example shows the syntax section of the Get-SPSite cmdlet.

Get-SPSite [-AssignmentCollection <SPAssignmentCollection>]
[-Confirm [<SwitchParameter>]] [-Filter <ScriptBlock>] [-Limit <String>]
[-WebApplication <SPWebApplicationPipeBind>] [-WhatIf [<SwitchParameter>]]
Get-SPSite -Identity <SPSitePipeBind> [-AssignmentCollection
<SPAssignmentCollection>] [-Confirm [<SwitchParameter>]] [-Filter <ScriptBlock>]
[-Limit <String>] [-Regex <SwitchParameter>] [-WhatIf [<SwitchParameter>]]
Get-SPSite -ContentDatabase <SPContentDatabasePipeBind> [-AssignmentCollection
<SPAssignmentCollection>] [-Confirm [<SwitchParameter>]] [-Filter <ScriptBlock>]
[-Limit <String>] [-WhatIf [<SwitchParameter>]] [<CommonParameters>]
Get-SPSite -SiteSubscription <SPSiteSubscriptionPipeBind> [-AssignmentCollection
<SPAssignmentCollection>] [-Confirm [<SwitchParameter>]] [-Filter <ScriptBlock>]
[-Limit <String>] [-WhatIf [<SwitchParameter>]] [<CommonParameters>]

Notice that there are four ways to use Get-SPSite, and each syntax has an –AssignmentCollection parameter. The –AssignmentCollection parameter relates to an important aspect of the built-in SharePoint cmdlet, which is examined in more detail in the sidebar titled Memory Considerations When Using Windows PowerShell.

The first syntax example shown in the listing above has no mandatory parameter, so the Get-SPSite cmdlet would have a scope of the farm or Web application. The other three syntaxes have a mandatory parameter that defines the scope as site collection, content database, or collection of site collections that subscribe to shared settings, features, and services, as shown in the following code. As is the case with the other SPSite cmdlets, in a large installation, this cmdlet could output a large amount of information, and the queries to many content databases could severely affect the performance of the SharePoint servers. Therefore, by default, the output reports only on the first 20 objects.

You can alter this output limit by using the –limit parameter, as shown in the following example, which outputs all site collections that are stored in the Contoso_TeamsDB content database.

Get-SPSite -ContentDatabase Contoso_TeamsDB -limit all

You can provide the values for these scope parameters, or in the case of the –identity parameter, where the value is a URL, you can use the wildcard character (*). The default help with no parameter provides a limited description of the command.

For more information, use the –detailed or the –full parameter. The –full parameter provides additional information about the parameters. For example, additional information about the –identity parameter is shown on the following page.

-Identity <SPSitePipeBind>
Specifies the URL or GUID of the site collection to get.
The type must be a valid URL, in the form http://server_name or http://
server_name/sites/sitename, or a valid GUID (for example, 12345678-90ab
Required? true
Position? 1
Default value
Accept pipeline input? True
Accept wildcard characters? false

If you look at the last five lines of the output, you see that it provides more information on how to use the –identity parameter. For example, the required value is equal to True, which indicates that the –identity parameter is a mandatory parameter for the Get-SPSite cmdlet. However, the position value is equal to 1, which means that if you place a URL of a site collection immediate after the Get-SPSite cmdlet, you do not have to use the –identity parameter because the URL will be read as the identity (URL) of a site collection, where all the property values for site collections that exist under the personal managed path are displayed, as shown in the following example.

Get-SPSite http://MySite/personal/* | Select *

Many of the parameters have a value enclosed in angle brackets, with the suffix PipeBind. This indicates that the parameter can accept an object variable of a specific type. For example, [–ContentDatabase <SPContentDatabasePipeBind>] means that the –ContentDatabase parameter can accept a SharePoint content database object, and this object can be passed to the ContentDatabase object either as a variable, or it can be piped in from the results of another cmdlet. When you pipe an object into a cmdlet, you do not need to type or use a variable. When you pipe an object from one cmdlet into another cmdlet, you do not have to specify the parameter, because Windows PowerShell checks the type of object and will match it to the correct parameter. The following example lists all site collections that are stored in any content databases that have the characters oso anywhere in their names.

Get-SPContentDatabase | where {$ -match "oso"} | Get-SPSite -Limit 50

Get-SPContentDatabase returns a collection of content databases, and then you need to check each content database to see if it matches our condition. The Where-object cmdlet, which has the aliases where or ?, acts like a loop, so it will check each content database object returned from the Get-SPContentDatabase cmdlet. The variable $_ represents one content database object, and .name is the content database property that needs to be matched for our query. The operator is –match.

Windows PowerShell has a number of operators, such as –eq (equal to), –ne (not equal to), –lt (less than), –ge (greater than or equal to), –like (matches a wildcard pattern), and –notlike (does not match a wildcard pattern). The –like, –notlike, –match, and –notmatch operators are used for pattern matching. The –match and –notmatch operators use regular expressions to determine whether a value does or does not contain a match for an expression.

An alternative method to use instead of a WHERE statement is the –filter parameter, which uses the same syntax as the WHERE statement and can produce the same results. However, the –filter parameter executes on the server. Piping the results of the Get-SPContentDatabase cmdlet to the WHERE statement causes a SQL round trip to wherever the Windows PowerShell client is running. Using the –filter parameter can result in a faster performance, allowing the command to leverage the filtering abilities of SQL instead of attempting a local search. However, when you use the –filter parameter, only the Owner, SecondaryOwner, and LockState properties can be accessed for SPSite cmdlets. A number of cmdlets have other parameters that allow you to filter the resulting output. For example, SPWeb provides parameters to filter output on the template or title of the site (web). Still, in many cases the –filter parameter can save you time—for example, finding all the blog sites in a farm of 4300 webs takes about 1.2 seconds with the –filter parameter, but it takes approximately 15 minutes if you use a WHERE statement. Following are several examples that use the –filter parameter.
  • This example returns all site collections whose primary owner has the username peter.

    Get-SPSite -Filter {$_.Owner -eq "contoso\peter"}

  • This example returns all websites in the http://teams/sites/HR site collection that were created using the Blank Meeting Workspace template.

    Get-SPSite http://teams/sites/HR | Get-SPWeb -Filter {$_.Template -eq "STS#03"}


    When you create a new site collection, if you do not specify a template or the template cannot be found, then you will need to create a website as the root of the site collection. You can do this by using the New-SPWeb command or by selecting the appropriate site template when you display the site collection for the first time in the browser.

    To find details of the templates installed, together with the appropriate template ids, use the Get-SPWebTemplate cmdlet. A sample of the output of this command is shown here.

    Name                 Title                                    LocaleId   Custom
    ---- ----- -------- ------
    GLOBAL#0 Global template 1033 False
    STS#0 Team Site 1033 False
    STS#1 Blank Site 1033 False
    STS#2 Document Workspace 1033 False
    MPS#0 Basic Meeting Workspace 1033 False
    MPS#1 Blank Meeting Workspace 1033 False
    MPS#2 Decision Meeting Workspace 1033 False
    MPS#3 Social Meeting Workspace 1033 False
    MPS#4 Multipage Meeting Workspace 1033 False
    CENTRALADMIN#0 Central Admin Site 1033 False
    WIKI#0 Wiki Site 1033 False
    BLOG#0 Blog 1033 False
    SGS#0 Group Work Site 1033 False
    TENANTADMIN#0 Tenant Admin Site 1033 False
    ACCSRV#0 Access Services Site 1033 False
    ACCSRV#1 Assets Web Database 1033 False
    ACCSRV#3 Charitable Contributions Web Database 1033 False

    On the Get-SPSite and Get-SPSiteAdministration, provide two other filters that use the SQL-driven filtering: the “Wildcard URLs” and regular expression (–RegEx) parameter, for example:

    Get-SPSite http://intranet/sites/*
    Get-SPSite "http://intranet/(sites|teams)/HR" -RegEx

Memory Considerations When Using Windows PowerShell

The default behavior of Windows PowerShell is that it runs a multithread environment and that each line, function, or script runs in its own thread ($host.Runspace.ThreadOptions == “Default”). The SharePoint 2010 Management Shell runs each line, function, or script in the first thread ($host.Runspace.ThreadOptions =“ReuseThread”), which mitigates the problem—but memory leaks can still occur. Hence, the two SharePoint cmdlets that you should learn to use are the Start-SPAssignment and the Stop-SPAssignment. These relate to the –SPAssignmentCollection parameter that you may see used with a number of SharePoint cmdlets to return a “disposable object.” In developer-speak, these are objects that implement the IDisposable Interface. If these objects are not disposed of correctly, they can cause memory leaks. In particular, this relates to the SPSite, SPWeb, and SPSiteAdministration objects. If you use cmdlets associated with these objects in one pipe and don’t use variables to store the objects, the memory used is automatically disposed of at the end of a pipe. If you have a long pipe that obtains many objects, this can cause a shortage of memory on your SharePoint server, which then can have a noticeable effect on requests for pages from that server.

When you store any of the three objects in a variable, you then have to dispose of the memory assigned to that object. The following examples show the main methods of using these objects with variables and how to dispose of the memory.

  • Use the simple method of using the SPAssignment cmdlets, in which all objects are kept in a global memory store that is released when the Stop-SPAssignment cmdlet is called.

    Start-SPAssignment -Global
    $sc = Get-SPSite http://intranet
    Stop-SPAssignment -Global

  • Use the advanced method of using the SPAssignment cmdlet and tell it to track memory assigned to a specific variable. In the following example, the Start-SPAssignment cmdlet creates a named store that is pointed to by $o, and the variable $sc is associated with that named store and populated with information about the Internet site collection object. The Stop-SPAssignment cmdlet then releases the memory associated with the named store.

    $o = Start-SPAssignment
    $sc = $o | Get-SPSite http://intranet
    Get-SPSite -Limit all
    $o | Stop-SPAssignment

  • If you are used to developing on the SharePoint platform, then you can use a similar technique to that which you use in your code to overcome this issue. For example, use variables within one Windows PowerShell line and dispose of them at the end of that line.

    $sc = New-SPSite("http://Intranet"); $sc.Title; $sc.Dispose()

This stores the site collection object in the variable $sc. The next command then prints out the title of the intranet site collection, and the last command releases the memory that stored the site collection object.


This same command can be run safely using the following syntax.

New-SPSite(http://intranet) | Select Title

Be aware that the simple method of calling SPAssignment shown here also can cause memory problems. Any object you obtain between the Stop and Stop SPAssignment commands will be retained in the global assignment store and will not be released until the Stop-SPAssignment cmdlet is executed, whereas when you use the advanced method of calling SPAssignment, only the memory associated with variables you ask SPAssignment to track will be retained until the Stop-SPAssignment cmdlet is executed. Therefore, if you need to view large amount of information as you complete a task, and you do not want to starve the SharePoint server of memory, the advanced method of using SPAssigment is preferable. Use Get-Help About_SPAssignment to find more information.

Other -----------------
- Working with the SharePoint 2010 Management Shell (part 6)
- Working with the SharePoint 2010 Management Shell (part 5) - Using Verbs
- Working with the SharePoint 2010 Management Shell (part 4) - Understanding Properties and Methods
- Working with the SharePoint 2010 Management Shell (part 3) - Working with Objects
- Working with the SharePoint 2010 Management Shell (part 2) - Understanding cmdlets
- Working with the SharePoint 2010 Management Shell (part 1)
- SharePoint 2010 : Edit the Contents of a Page
- SharePoint 2010 : Change the Page Layout of a Publishing Page
- SharePoint 2010 : Authoring Pages - Edit the Properties of a Page
- SharePoint 2010 : Authoring Pages - Create a New Page (part 2)
- SharePoint 2010 : Authoring Pages - Create a New Page (part 1)
- SharePoint 2010 : Managing Systems Remotely with WinRM
- SharePoint 2010 : Installing Windows PowerShell
- SharePoint 2010 : Using Windows PowerShell: The Basics
- SharePoint 2010 : Modify a View
- SharePoint 2010 : Create Mobile Views
- Uninstalling SharePoint 2010
- Configuring a SharePoint 2010 Installation (part 1) - Renaming the Central Administration Database
- Configuring a SharePoint 2010 Installation (part 1) - Running the Farm Configuration Wizard
- SharePoint 2010 : Enable or Disable Inline Editing in a View
Most View
- Configuring Windows 7 for Secure Networking
- Developing an SEO-Friendly Website : Keyword Targeting (part 1) - Title Tags
- Windows Server 2008 R2 : Installing Windows SharePoint Services (part 1)
- SOA with .NET and Windows Azure : Windows Workflow Foundation (part 4) - Activities
- Microsoft Dynamics GP 2010 : Populating Initial Data - Open receivables transactions
- Exchange 2007: Choose the Right Hardware for the Role
- Windows 7 : Securing the File System - Encrypting Files and Folders
- Identity and Access Management : Trust Boundaries and IAM
- ASP.NET Security : Security-Related Controls (part 2)
- SQL Server 2008 : SQL Server Profiler Architecture
Top 10
- Implementing Edge Services for an Exchange Server 2007 Environment : Utilizing the Basic Sender and Recipient Connection Filters (part 3) - Configuring Recipient Filtering
- Implementing Edge Services for an Exchange Server 2007 Environment : Utilizing the Basic Sender and Recipient Connection Filters (part 2)
- Implementing Edge Services for an Exchange Server 2007 Environment : Utilizing the Basic Sender and Recipient Connection Filters (part 1)
- Implementing Edge Services for an Exchange Server 2007 Environment : Installing and Configuring the Edge Transport Server Components
- What's New in SharePoint 2013 (part 7) - BCS
- What's New in SharePoint 2013 (part 6) - SEARCH
- What's New in SharePoint 2013 (part 6) - WEB CONTENT MANAGEMENT
- What's New in SharePoint 2013 (part 5) - ENTERPRISE CONTENT MANAGEMENT
- What's New in SharePoint 2013 (part 4) - WORKFLOWS
- What's New in SharePoint 2013 (part 3) - REMOTE EVENTS