PowerShell Cmdlets « SharePoint Automation

16Mar/124

Exporting and Importing SharePoint 2010 Terms

Ever had the need to migrate Terms from the Managed Metadata Term Store from one environment to another? Do you find the flat, CSV, import approach provided out of the box to be insufficient (especially with its lack of support for alternate labels)? When I first started working with Terms over two years ago I was extremely frustrated by the lack of export and import capabilities so I decided to solve the problem myself by creating two cmdlets, Export-SPTerms and Import-SPTerms. I’ve actually had these cmdlets publicly available for about two years now but I suspect very few people actually know they exist so I thought I’d put together this short post just to highlight them (I also recently pushed out an update which adds support for Site Collection scoped Groups if you have SP1 deployed).

I don’t want to go into a lot of detail regarding how these cmdlets work as they’re really very simple and the bulk of the code is just about iterating through the Term Store structure and turning the various objects into an XML structure (you can download the code from my downloads page). So with brevity in mind, here’s the full help for the Export-SPTerms cmdlet:

NAME      
    Export-SPTerms       
    
SYNOPSIS       
    Export the Managed Metadata Terms.       
    
SYNTAX       
    Export-SPTerms [-TaxonomySession] <SPTaxonomySessionPipeBind> [[-OutputFile] <String>] [-AssignmentCollection <SPAssignmentCollection>] [<CommonParameters>]       
    
    Export-SPTerms [-TermStore] <SPTaxonomyTermStorePipeBind> [[-OutputFile] <String>] [-AssignmentCollection <SPAssignmentCollection>] [<CommonParameters>]       
    
    Export-SPTerms [-Group] <SPTaxonomyGroupPipeBind> [[-OutputFile] <String>] [-AssignmentCollection <SPAssignmentCollection>] [<CommonParameters>]       
    
    Export-SPTerms [-TermSet] <SPTaxonomyTermSetPipeBind> [[-OutputFile] <String>] [-AssignmentCollection <SPAssignmentCollection>] [<CommonParameters>]       
    
    Export-SPTerms [-Term] <SPTaxonomyTermPipeBind> [[-OutputFile] <String>] [-AssignmentCollection <SPAssignmentCollection>] [<CommonParameters>]       
    
    
DESCRIPTION       
    Export the Managed Metadata Terms.       
    
    Copyright 2011 Falchion Consulting, LLC       
    > For more information on this cmdlet and others:       
    >http://blog.falchionconsulting.com/       
    > Use of this cmdlet is at your own risk.       
    > Gary Lapointe assumes no liability.       
    
PARAMETERS      
    -TaxonomySession <SPTaxonomySessionPipeBind>       
        The TaxonomySession object containing the Term Stores to export.       
        
        Required?                    true       
        Position?                    1       
        Default value                
        Accept pipeline input?       true (ByValue)       
        Accept wildcard characters?  false       
        
    -TermStore <SPTaxonomyTermStorePipeBind>       
        The TermStore object containing the terms to export.       
        
        Required?                    true       
        Position?                    1       
        Default value                
        Accept pipeline input?       true (ByValue, ByPropertyName)       
        Accept wildcard characters?  false       
        
    -Group <SPTaxonomyGroupPipeBind>       
        The Group object containing the terms to export.       
        
        Required?                    true       
        Position?                    1       
        Default value                
        Accept pipeline input?       true (ByValue, ByPropertyName)       
        Accept wildcard characters?  false       
        
    -TermSet <SPTaxonomyTermSetPipeBind>       
        The TermSet object containing the terms to export.       
        
        Required?                    true       
        Position?                    1       
        Default value                
        Accept pipeline input?       true (ByValue, ByPropertyName)       
        Accept wildcard characters?  false       
        
    -Term <SPTaxonomyTermPipeBind>       
        The Term object containing the terms to export.       
        
        Required?                    true       
        Position?                    1       
        Default value                
        Accept pipeline input?       true (ByValue, ByPropertyName)       
        Accept wildcard characters?  false       
        
    -OutputFile [<String>]       
        The path to the file to save the terms to.       
        
        Required?                    false       
        Position?                    2       
        Default value                
        Accept pipeline input?       false       
        Accept wildcard characters?  false       
        
    -AssignmentCollection [<SPAssignmentCollection>]       
        Manages objects for the purpose of proper disposal. Use of objects, such as SPWeb or SPSite, can use large amounts of memory and use of these objects in Windows PowerShell scripts requires proper memory management. Using the SPAssignment object, you can assign objects to a variable and dispose of the objects after they are needed to free up memory. When SPWeb, SPSite, or SPSiteAdministration objects are used, the objects are automatically disposed of if an assignment collection or the Global parameter is not used.       
        
        When the Global parameter is used, all objects are contained in the global store. If objects are not immediately used, or disposed of by using the Stop-SPAssignment command, an out-of-memory scenario can occur.       
        
        Required?                    false       
        Position?                    named       
        Default value                
        Accept pipeline input?       true (ByValue)       
        Accept wildcard characters?  false       
        
    <CommonParameters>       
        This cmdlet supports the common parameters: Verbose, Debug,       
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,       
        OutBuffer and OutVariable. For more information, type,       
        "get-help about_commonparameters".       
    
INPUTS       
    
    
    
OUTPUTS       
    
    
    
NOTES       
    
    
    For more information, type "Get-Help Export-SPTerms -detailed". For technical information, type "Get-Help Export-SPTerms -full".       
    
    ------------------EXAMPLE 1-----------------------       
    
    PS C:\> Export-SPTerms -TaxonomySession "http://site/" -OutputFile "c:\terms.xml"       
    
    
    This example exports the terms for all term stores associated with the site and saves to c:\terms.xml.       
    
    ------------------EXAMPLE 2-----------------------       
    
    PS C:\> Export-SPTerms -Group (Get-SPTaxonomySession -Site "http://site/").TermStores[0].Groups[0] -OutputFile "c:\terms.xml"       
    
    
    This example exports the first Group of the first Term Store and saves to c:\terms.xml.       
    
    
RELATED LINKS       
    Import-SPTerms       
    Get-SPTaxonomySession

Now lets look at the Import-SPTerms cmdlet (it’s very similar):

     
NAME       
    Import-SPTerms       
    
SYNOPSIS       
    Import the Managed Metadata Terms.       
    
SYNTAX       
    Import-SPTerms [-TaxonomySession] <SPTaxonomySessionPipeBind> [-InputFile] <XmlDocumentPipeBind> [-AssignmentCollection <SPAssignmentCollection>] [<CommonParameters>]       
    
    Import-SPTerms [-ParentTermStore] <SPTaxonomyTermStorePipeBind> [-InputFile] <XmlDocumentPipeBind> [-AssignmentCollection <SPAssignmentCollection>] [<CommonParameters>]       
    
    Import-SPTerms [-ParentGroup] <SPTaxonomyGroupPipeBind> [-InputFile] <XmlDocumentPipeBind> [-AssignmentCollection <SPAssignmentCollection>] [<CommonParameters>]       
    
    Import-SPTerms [-ParentTermSet] <SPTaxonomyTermSetPipeBind> [-InputFile] <XmlDocumentPipeBind> [-AssignmentCollection <SPAssignmentCollection>] [<CommonParameters>]       
    
    Import-SPTerms [-ParentTerm] <SPTaxonomyTermPipeBind> [-InputFile] <XmlDocumentPipeBind> [-AssignmentCollection <SPAssignmentCollection>] [<CommonParameters>]       
    
    
DESCRIPTION       
    Import the Managed Metadata Terms.       
    
    Copyright 2011 Falchion Consulting, LLC       
    > For more information on this cmdlet and others:       
    > http://blog.falchionconsulting.com/       
    > Use of this cmdlet is at your own risk.       
    > Gary Lapointe assumes no liability.       
    
PARAMETERS      
    -TaxonomySession <SPTaxonomySessionPipeBind>       
        The TaxonomySession object to import Term Stores into.       
        
        Required?                    true       
        Position?                    1       
        Default value                
        Accept pipeline input?       true (ByValue)       
        Accept wildcard characters?  false       
        
    -ParentTermStore <SPTaxonomyTermStorePipeBind>       
        The TermStore object to import Groups into.       
        
        Required?                    true       
        Position?                    1       
        Default value                
        Accept pipeline input?       true (ByValue, ByPropertyName)       
        Accept wildcard characters?  false       
        
    -ParentGroup <SPTaxonomyGroupPipeBind>       
        The Group object to import Term Sets into.       
        
        Required?                    true       
        Position?                    1       
        Default value                
        Accept pipeline input?       true (ByValue, ByPropertyName)       
        Accept wildcard characters?  false       
        
    -ParentTermSet <SPTaxonomyTermSetPipeBind>       
        The TermSet object to import Terms into.       
        
        Required?                    true       
        Position?                    1       
        Default value                
        Accept pipeline input?       true (ByValue, ByPropertyName)       
        Accept wildcard characters?  false       
        
    -ParentTerm <SPTaxonomyTermPipeBind>       
        The Term object to import Terms into.       
        
        Required?                    true       
        Position?                    1       
        Default value                
        Accept pipeline input?       true (ByValue, ByPropertyName)       
        Accept wildcard characters?  false       
        
    -InputFile <XmlDocumentPipeBind>       
        The path to the file containing the terms to import or an XmlDocument object or XML string.       
        
        Required?                    true       
        Position?                    2       
        Default value                
        Accept pipeline input?       true (ByValue)       
        Accept wildcard characters?  false       
        
    -AssignmentCollection [<SPAssignmentCollection>]       
        Manages objects for the purpose of proper disposal. Use of objects, such as SPWeb or SPSite, can use large amounts of memory and use of these objects in Windows PowerShell scripts requires proper memory management. Using the SPAssignment object, you can assign objects to a variable and dispose of the objects after they are needed to free up memory. When SPWeb, SPSite, or SPSiteAdministration objects are used, the objects are automatically disposed of if an assignment collection or the Global parameter is not used.       
        
        When the Global parameter is used, all objects are contained in the global store. If objects are not immediately used, or disposed of by using the Stop-SPAssignment command, an out-of-memory scenario can occur.       
        
        Required?                    false       
        Position?                    named       
        Default value                
        Accept pipeline input?       true (ByValue)       
        Accept wildcard characters?  false       
        
    <CommonParameters>       
        This cmdlet supports the common parameters: Verbose, Debug,       
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,       
        OutBuffer and OutVariable. For more information, type,       
        "get-help about_commonparameters".       
    
INPUTS       
    
    
    
OUTPUTS       
    
    
    
NOTES       
    
    
    For more information, type "Get-Help Import-SPTerms -detailed". For technical information, type "Get-Help Import-SPTerms -full".       
    
    ------------------EXAMPLE 1-----------------------       
    
    PS C:\> Import-SPTerms -ParentTermStore (Get-SPTaxonomySession -Site "http://site/").TermStores[0] -InputFile "c:\terms.xml"       
    
    
    This example imports the Group from c:\terms.xml to the first Term Store.       
    
    ------------------EXAMPLE 2-----------------------       
    
    PS C:\> Import-SPTerms -TaxonomySession "http://site/" -InputFile "c:\terms.xml"       
    
    
    This example imports the terms from c:\terms.xml to the Term Store associated with http://site.       
    
    
RELATED LINKS       
    Export-SPTerms       
    Get-SPTaxonomySession       

Using these cmdlets I can easily export terms from one environment, such as production, to another environment, such as my test environment. This avoids the need to have backup and restore the database associated with the term store (which requires removing and re-provisioning the service application. And the way I’ve written the cmdlets all the Term Set, Group, and Term IDs remain consistent and, because the exported XML is easily modified, when it comes to Site Collection scoped Groups you can do a simple search and replace to change Site Collection URLs to match the new target (note that I first check for a Site Collection with the specified URL and if not found then I use the ID and if I still can’t locate the Site Collection then I create the Group as a standard shared Group).

-Gary

Tagged as: Cmdlets, Managed Terms, SharePoint 2010 4 Comments

20Aug/116

Resetting SharePoint 2010 Themes – Part 2, the Reset-SPTheme cmdlet

Yesterday I threw up a quick post showing how to reset a SharePoint 2010 theme using a reasonably simple Windows PowerShell script. In that post I promised that I’d convert the script to a cmdlet and make it part of my downloadable extensions. Well, as promised I’ve updated my extensions so that they now include a Reset-SPTheme cmdlet. I added on minor enhancement over the previously shown script in that I allow you to pass in either an SPSite or an SPWeb object and by default it will not force all child webs to inherit from the relevant SPWeb object. This way, if you have a child Site with it’s own theme it won’t wipe out that theme. If you have multiple Sites with a custom theme setting within a Site Collection then you’ll want to provide the -Site parameter and pass in an SPSite reference – this will result in all Sites with custom themes within the Site Collection to be reset. If you only wish to reset a single Site then use the -Web parameter and pass in a SPWeb reference.

Here’s the full help for the Reset-SPTheme cmdlet:

NAME
Reset-SPTheme

SYNOPSIS
Resets a theme by applying all user specified theme configuration settings to the original source files. This is particularly helpful when the original source files have changed to a Feature upgrade.

SYNTAX
Reset-SPTheme [-Web] <SPWebPipeBind> [-SetSubWebsToInherit <SwitchParameter>] [-AssignmentCollection <SPAssignmentCollection>] [<CommonParameters>]

Reset-SPTheme [-Site] <SPSitePipeBind> [-SetSubWebsToInherit <SwitchParameter>] [-AssignmentCollection <SPAssignmentCollection>] [<CommonParameters>]

DESCRIPTION
Resets a theme by applying all user specified theme configuration settings to the original source files. This is particularly helpful when the original source files have changed to a Feature upgrade.

    Copyright 2011 Falchion Consulting, LLC
    > For more information on this cmdlet and others:
    > http://blog.falchionconsulting.com/
    > Use of this cmdlet is at your own risk.
    > Gary Lapointe assumes no liability.

PARAMETERS
-Web <SPWebPipeBind>
Specifies the URL or GUID of the Web containing the theme to reset.

The type must be a valid GUID, in the form 12345678-90ab-cdef-1234-567890bcdefgh; a valid name of Microsoft SharePoint Foundation 2010 Web site (for example, MySPSite1); or an instance of a valid SPWeb object.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?       true (ByValue, ByPropertyName)
        Accept wildcard characters? false

-Site <SPSitePipeBind>
The site containing the theme to reset.

The type must be a valid GUID, in the form 12345678-90ab-cdef-1234-567890bcdefgh; a valid URL, in the form http://server_name; or an instance of a valid SPSite object.

-SetSubWebsToInherit [<SwitchParameter>]
If specified, all child webs will be reset to inherit the theme of the specified web or root web.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?       false
        Accept wildcard characters? false

-AssignmentCollection [<SPAssignmentCollection>]
Manages objects for the purpose of proper disposal. Use of objects, such as SPWeb or SPSite, can use large amounts of memory and use of these objects in Windows PowerShell scripts requires proper memory management. Using the SPAssignment object, you can assign objects to a variable and dispose of the objects after they are needed to free up memory. When SPWeb, SPSite, or SPSiteAdministration objects are used, the objects are automatically disposed of if an assignment collection or the Global parameter is not used.

When the Global parameter is used, all objects are contained in the global store. If objects are not immediately used, or disposed of by using the Stop-SPAssignment command, an out-of-memory scenario can occur.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?       true (ByValue)
        Accept wildcard characters? false

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        "get-help about_commonparameters".

INPUTS

OUTPUTS

NOTES

For more information, type "Get-Help Reset-SPTheme -detailed". For technical information, type "Get-Help Reset-SPTheme -full".

------------------EXAMPLE 1-----------------------

PS C:\> Get-SPSite http://server_name | Reset-SPTheme -SetSubWebsToInherit

This example resets the theme for the site collection http://server_name and resets all child webs to inherit from the root web.

------------------EXAMPLE 2-----------------------

PS C:\> Get-SPWeb http://server_name/sub-web | Reset-SPTheme

This example resets the theme for the web http://server_name/sub-web.

Programmatically Setting SharePoint 2010 Calendar Overlays

I recently did a project where my client needed several calendars provisioned via a Feature Receiver when a particular type of Site Collection was created; they had one primary calendar and they wanted all the other calendars to be overlaid onto the primary one using SharePoint 2010’s Calendar overlay capabilities.

Here’s a quick summary of this feature if you’re not familiar with it. When you are looking at a calendar you should notice that there is a ribbon button titled “Calendar Overlay”:

Clicking this button brings you to the Calendar Overlay Settings page; from this page you can add or edit the overlay calendars. Clicking “New Calendar” brings you to an application page where you can define what calendar to overlay:

As you can see from the above screenshot, you can add not just a SharePoint calendar as an overlay but also an Exchange calendar. After configuring calendar overlays you will see overlaid items when looking at the month view for the calendar:

In this example, the pink item is coming from the overlay calendar. Overlay items are added dynamically after the page loads (some JavaScript and Ajax take care of loading the items and rendering them on the page).

So that’s the basics from the end-users perspective. Now what about the technical details? Well, there’s not a lot of information out there that describes how this is done but here’s the gist of it – there’s a simple XML structure that is stored in the SPView’s CalendarSettings property; this property defines the overlays. Once you know that the rest is just a matter of figuring out what that structure looks like. The easiest way to start is to simply go through the browser and set up one or two overlays and then use some simple PowerShell to dump out that XML:

Here’s a better view of what that XML looks like:

<AggregationCalendars>
    <AggregationCalendar Id="{26ddb82c-9e2b-4c5d-9b7e-4ee25cf5c357}" 
                         Type="SharePoint" 
                         Name="My Overlay Calendar" 
                         Description="" 
                         Color="5" 
                         AlwaysShow="False" 
                         CalendarUrl="/Lists/MyOverlayCalendar/calendar.aspx">
        <Settings WebUrl="http://demo" 
                  ListId="{428bd2cb-a32d-4867-b658-6498158636a8}" 
                  ViewId="{09928cd4-9a5e-44ed-9bf2-dfe1fc85661b}" 
                  ListFormUrl="/Lists/MyOverlayCalendar/DispForm.aspx" />
    </AggregationCalendar>
</AggregationCalendars>

I want to call particular attention to the WebUrl attribute of the Settings element; this value *must* be the full URL of the SPWeb object that contains the overlay calendar list. Okay, you’re thinking, not a huge deal, SharePoint stores the full URL for lots of things and it doesn’t really pose issues right? WRONG! Think about a scenario where you have an extended web application. So in my example I have an authoring site located at http://demo and I’ve extended this site for anonymous access under the URL http://demo.aptillon.com. Due to what I consider a design flaw with the overlays, the overlay feature will only work when the web application you are accessing the site as matches the web application defined for the WebUrl attribute. So if I were to try and access my overlay using the anonymous site I’d get the following error:

And of course, due to this error, the overlays will not show up. So even if I’ve only changed the protocol (http to https) I’d still get this same error. This means that, effectively, calendar overlays using SharePoint lists will only work under the context of the Web Application (and protocol) from which the overlay was defined. (I’ve torn through the code that does this and it’s something that Microsoft should be very embarrassed about – very poor performance and just flat out horribly implemented. Okay, I digress, let’s get back to the details.

Another thing you’ll want to do to understand this XML structure is to look at the code that constructs it. There’s two places to look and both require Reflector or some equivalent disassembler; the first is the SerializeAccessors() method of the Microsoft.SharePoint.ApplicationPages.Calendar.CalendarAccessorManagerImpl class. This method takes the properties provided to it and constructs the XML structure shown above. So where are these properties set? For that we need to look at the BtnOk_Click() method of the Microsoft.SharePoint.ApplicationPages.AggregationCustomizePage class. I’m not going to show the details of these methods here but suffice it to say these methods have everything you need to understand this structure.

As I previously noted, for my particular client I needed to set several overlays within a Feature Activated event; to make this easier (because there was technically several places I had to do this) I created a simple method that I could call; this method took in my target list and the list I wanted to overlay as well as several other properties. For this post I’ve taken that code and created a modified version of it which supports adding Exchange-based calendars. Here’s that code:

using System;
using System.Collections.Generic;
using System.Globalization;
using System.Linq;
using System.Text;
using System.Xml;
using Microsoft.SharePoint;

namespace Lapointe.SharePoint2010.Automation.Common.Lists
{
    public enum CalendarOverlayColor
    {
        LightYellow = 1,
        LightGreen = 2,
        Orange = 3,
        LightTurquise = 4,
        Pink = 5,
        LightBlue = 6,
        IceBlue1 = 7,
        IceBlue2 = 8,
        White = 9
    }

    public class SetListOverlay
    {
        public static void AddCalendarOverlay(SPList targetList, string viewName, string owaUrl, string exchangeUrl, string overlayName, string overlayDescription, CalendarOverlayColor color, bool alwaysShow, bool clearExisting)
        {
            AddCalendarOverlay(targetList, viewName, owaUrl, exchangeUrl, null, overlayName, overlayDescription, color, alwaysShow, clearExisting);
        }
        public static void AddCalendarOverlay(SPList targetList, string viewName, SPList overlayList, string overlayName, string overlayDescription, CalendarOverlayColor color, bool alwaysShow, bool clearExisting)
        {
            AddCalendarOverlay(targetList, viewName, null, null, overlayList, overlayName, overlayDescription, color, alwaysShow, clearExisting);
        }
        private static void AddCalendarOverlay(SPList targetList, string viewName, string owaUrl, string exchangeUrl, SPList overlayList, string overlayName, string overlayDescription, CalendarOverlayColor color, bool alwaysShow, bool clearExisting)
        {
            bool sharePoint = overlayList != null;
            string linkUrl = owaUrl;
            if (sharePoint)
                linkUrl = overlayList.DefaultViewUrl;

            SPView targetView = targetList.DefaultView;
            if (!string.IsNullOrEmpty(viewName))
                targetView = targetList.Views[viewName];

            XmlDocument xml = new XmlDocument();
            XmlElement aggregationElement = null;
            int count = 0;
            if (string.IsNullOrEmpty(targetView.CalendarSettings) || clearExisting)
            {
                xml.AppendChild(xml.CreateElement("AggregationCalendars"));
                aggregationElement = xml.CreateElement("AggregationCalendar");
                xml.DocumentElement.AppendChild(aggregationElement);
            }
            else
            {
                xml.LoadXml(targetView.CalendarSettings);
                XmlNodeList calendars = xml.SelectNodes("/AggregationCalendars/AggregationCalendar");
                if (calendars != null)
                    count = calendars.Count;
                aggregationElement = xml.SelectSingleNode(string.Format("/AggregationCalendars/AggregationCalendar[@CalendarUrl='{0}']", linkUrl)) as XmlElement;
                if (aggregationElement == null)
                {
                    if (count >= 10)
                        throw new SPException(string.Format("10 calendar ovarlays already exist for the calendar {0}.",targetList.RootFolder.ServerRelativeUrl));
                    aggregationElement = xml.CreateElement("AggregationCalendar");
                    xml.DocumentElement.AppendChild(aggregationElement);
                }
            }
            if (!aggregationElement.HasAttribute("Id"))
                aggregationElement.SetAttribute("Id", Guid.NewGuid().ToString("B", CultureInfo.InvariantCulture));

            aggregationElement.SetAttribute("Type", sharePoint ? "SharePoint" : "Exchange");
            aggregationElement.SetAttribute("Name", !string.IsNullOrEmpty(overlayName) ? overlayName : (overlayList == null ? "" : overlayList.Title));
            aggregationElement.SetAttribute("Description", !string.IsNullOrEmpty(overlayDescription) ? overlayDescription : (overlayList == null ? "" : overlayList.Description));
            aggregationElement.SetAttribute("Color", ((int)color).ToString());
            aggregationElement.SetAttribute("AlwaysShow", alwaysShow.ToString());
            aggregationElement.SetAttribute("CalendarUrl", linkUrl);

            XmlElement settingsElement = aggregationElement.SelectSingleNode("./Settings") as XmlElement;
            if (settingsElement == null)
            {
                settingsElement = xml.CreateElement("Settings");
                aggregationElement.AppendChild(settingsElement);
            }
            if (sharePoint)
            {
                settingsElement.SetAttribute("WebUrl", overlayList.ParentWeb.Site.MakeFullUrl(overlayList.ParentWebUrl));
                settingsElement.SetAttribute("ListId", overlayList.ID.ToString("B", CultureInfo.InvariantCulture));
                settingsElement.SetAttribute("ViewId", overlayList.DefaultView.ID.ToString("B", CultureInfo.InvariantCulture));
                settingsElement.SetAttribute("ListFormUrl", overlayList.Forms[PAGETYPE.PAGE_DISPLAYFORM].ServerRelativeUrl);
            }
            else
            {
                settingsElement.SetAttribute("ServiceUrl", exchangeUrl);
            }
            targetView.CalendarSettings = xml.OuterXml;
            targetView.Update();
            /*
            <AggregationCalendars>
                <AggregationCalendar 
                    Id="{cfc22c0b-688e-4555-b1d0-784081a91464}" 
                    Type="SharePoint" 
                    Name="My Overlay Calendar"
                    Description="" 
                    Color="1" 
                    AlwaysShow="True" 
                    CalendarUrl="/Lists/MyOverlayCalendar/calendar.aspx">
                    <Settings 
                        WebUrl="http://demo" 
                        ListId="{4a15e596-674f-4af7-a548-0b01470e8d75}" 
                        ViewId="{594c2916-14e7-4b08-ba36-1126b825bf45}" 
                        ListFormUrl="/Lists/MyOverlayCalendar/DispForm.aspx" />
                </AggregationCalendar>
                <AggregationCalendar 
                    Id="{cfc22c0b-688e-4555-b1d0-784081a91465}" 
                    Type="Exchange" 
                    Name="My Overlay Calendar"
                    Description="" 
                    Color="1" 
                    AlwaysShow="True" 
                    CalendarUrl="<url>">
                    <Settings ServiceUrl="<url>" />
                </AggregationCalendar>
            </AggregationCalendars>
            */
        }
    }
}

I’m not going to bore you with the details of this code as all I’m doing is basic XML manipulation. I created a couple of method overloads to allow for creating SharePoint or Exchange-based overlays. So, did you notice the namespace? Yup, no point in releasing code here if I’m not going to turn it into a cmdlet

I’m not sure how useful this cmdlet will be in everyday use but imagine the scenario in which you have a primary calendar on your company portal and you want to add it as an overlay on every calendar throughout portal – you could easily do this using this cmdlet. Before we get to that, let’s see the full help for the cmdlet, which I called Set-SPListOverlay:

PS C:\Users\spadmin> help Set-SPListOverlay -full

NAME
Set-SPListOverlay

SYNOPSIS
Sets calendar overlays for the given list.

SYNTAX
Set-SPListOverlay -Color -OverlayTitle [-OverlayDescription ] -OwaUrl -WebServiceUrl [-TargetList] [-ViewName ] [-DoNotAlwaysShow ] [-ClearExisting ] [-AssignmentCollection ] []

Set-SPListOverlay -Color [-OverlayList] [-OverlayTitle ] [-OverlayDescription ] [-TargetList] [-ViewName ] [-DoNotAlwaysShow ] [-ClearExisting ] [-AssignmentCollection ] []

Set-SPListOverlay [-OverlayLists] [-TargetList] [-ViewName ] [-DoNotAlwaysShow ] [-ClearExisting ] [-AssignmentCollection ] []

DESCRIPTION
Sets calendar overlays for the given list.

Copyright 2010 Falchion Consulting, LLC
> For more information on this cmdlet and others:
> http://blog.falchionconsulting.com/
> Use of this cmdlet is at your own risk.
> Gary Lapointe assumes no liability.

PARAMETERS
-Color
The color to use for the overlay calendar.

Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-TargetList
The calendar list to add the overlays to.

Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false

-ViewName []
The name of the view to add the overlays to. If not specified the default view will be used.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-OverlayList
The calendar list to add as an overlay.

Required? true
Position? 2
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false

-OverlayLists
The calendar lists to add as an overlay.

Required? true
Position? 2
Default value
Accept pipeline input? false
Accept wildcard characters? false

-OverlayTitle []
The title to give the overlay calendar when viewed in the target calendar.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-OverlayDescription []
The description to give the overlay calendar when viewed in the target calendar.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-OwaUrl
Outlook Web Access URL.

Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-WebServiceUrl
Exchange Web Service URL.

Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-DoNotAlwaysShow []
Don't always show the calendar overlay.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-ClearExisting []
Clear existing overlays. If not specified then all overlays will be appended to the list of existing over lays (up until 10 - anything after 10 will be ignored)

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-AssignmentCollection []
Manages objects for the purpose of proper disposal. Use of objects, such as SPWeb or SPSite, can use large amounts of memory and use of these objects in Windows PowerShell scripts requires proper memory management. Using the SPAssignment object, you can assign objects to a variable and dispose of the objects after they are needed to free up memory. When SPWeb, SPSite, or SPSiteAdministration objects are used, the objects are automatically disposed of if an assignment collection or the Global parameter is not used.

Required? false
Position? named
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false

This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".

INPUTS

OUTPUTS

NOTES

For more information, type "Get-Help Set-SPListOverlay -detailed". For technical information, type "Get-Help Set-SPListOverlay -full".

------------------EXAMPLE------------------

PS C:\> Get-SPList "http://server_name/lists/MyCalendar" | Set-SPListOverlay -TargetList "http://server_name/lists/MyOverlayCalendar" -Color "Pink" -ClearExisting

This example adds the MyOverlayCalendar calendar as an overlay to the MyCalendar list.

Retrieving and Configuring the SharePoint 2010 Developer Dashboard using PowerShell

It’s been almost a year to the day since I’ve released my SharePoint 2010 cmdlets and, despite many good intentions to get them documented on my blog, things have just fallen by the wayside; this was primarily due to me going out on my own and writing my first book – but now that the book is done and I’ve begun to establish myself as an independent consultant, I believe it’s about time I start blogging about all these hidden cmdlets that I’ve created. So, to start I’m going to take a couple of cmdlets that I originally developed for some conference presentations; specifically Get-SPDeveloperDashboard and Set-SPDeveloperDashboard.

Before I show these two new cmdlets, let’s look at what it currently takes to retrieve and manipulate the developer dashboard using Windows PowerShell:

As you can see from the preceding figure, you obtain an instance of the SPDeveloperDashboardSettings object via the DeveloperDashboardSettings property of an SPWebService instance (obtained using the static ContentService property of the SPWebService class). Note that there are several properties that we can manipulate beyond just the simple DisplayLevel property that is used to enable or disable the developer dashboard (or to put it into on demand mode). Some people still like to use STSADM to change the DisplayLevel property but doing so doesn’t allow you to manipulate the other properties available; often the reason people use STSADM is because it’s slightly less verbose if all you wish to do is change the DisplayLevel property. Here’s an example of how you would do it with PowerShell:

$dds = [Microsoft.SharePoint.Administration.SPWebService]::ContentService.DeveloperDashboardSettings
$dds.DisplayLevel = "On"
$dds.Update()

So, not a whole lot of code but still more than the single STSADM line (that and people have a hard time remembering the full object path to get to the SPDeveloperDashboardSettings object – I personally can remember this easier than the STSADM key names).

Because of this slightly higher level of complexity I decided to create these cmdlets, but I also went ahead and added some PowerShell type extensions so that I could get to the developer dashboard from an SPFarm instance. I’ll examine that before we get into the cmdlets; if you download my source code you should notice a file named Lapointe.SharePoint2010.Automation.Cmdlets.Types.ps1xml in the {Project Root}\PowerShell\Types folder. Here’s the relevant contents of that file:

<?xml version="1.0" encoding="utf-8"?>
<Types>
  <Type>
    <Name>Microsoft.SharePoint.Administration.SPFarm</Name>
    <Members>
      <ScriptProperty>
        <Name>DeveloperDashboard</Name>
        <GetScriptBlock>[Microsoft.SharePoint.Administration.SPWebService]::ContentService.DeveloperDashboardSettings</GetScriptBlock>
      </ScriptProperty>
    </Members>
  </Type>
</Types>

What I’ve done here is essentially create a type extension using XML; the <Name /> element defines the full type name that you want to extend and the <Members /> element contains all the extensions. In this case I’ve added a new property named DeveloperDashboard and I provided the same script we saw previously so that the SPDeveloperDashboardSettings object will be returned. It’s important to understand that you are not limited to just get properties – you can create set properties as well as methods (type help about_types for more information about creating type extensions). With this type extension added we can now access the developer dashboard in a slightly simpler manner:

$dds = (Get-SPFarm).DeveloperDashboard

Using this approach there really isn’t a need for the Get-SPDeveloperDashboard cmdlet that I created, as the cmdlet only saves about seven characters; however, this approach isn’t obvious – what I want is users to be able to type Get-Command *dashboard* so that they can see all the cmdlets related to the developer dashboard. (Plus, I created the cmdlet originally just for demonstration purposes but it does make things a little more obvious). So now that we have the type extension out of the way, let’s take a look at the cmdlet. Here’s a dump of the full help for the Get-SPDeveloperDashboard cmdlet:

PS C:\> help Get-SPDeveloperDashboard -Full

NAME
Get-SPDeveloperDashboard

SYNOPSIS
Retrieves the Developer Dashboard Settings object.

SYNTAX
Get-SPDeveloperDashboard [-AssignmentCollection <spassignmentcollection>] [<commonparameters>]

DESCRIPTION
Retrieves the Developer Dashboard Settings object.

PARAMETERS
-AssignmentCollection [<spassignmentcollection>]
Manages objects for the purpose of proper disposal. Use of objects, such as SPWeb or SPSite,
can use large amounts of memory and use of these objects in Windows PowerShell scripts requires
proper memory management. Using the SPAssignment object, you can assign objects to a variable
and dispose of the objects after they are needed to free up memory. When SPWeb, SPSite, or
SPSiteAdministration objects are used, the objects are automatically disposed of if an assignment
collection or the Global parameter is not used.

When the Global parameter is used, all objects are contained in the global store. If objects are
not immediately used, or disposed of by using the Stop-SPAssignment command, an out-of-memory
scenario can occur.

Required? false
Position? named
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false

<commonparameters>
This cmdlet supports the common parameters: Verbose, Debug, ErrorAction, ErrorVariable,
WarningAction, WarningVariable, OutBuffer and OutVariable. For more information,
type, "get-help about_commonparameters".

INPUTS

OUTPUTS

NOTES

For more information, type "Get-Help Get-SPDeveloperDashboard -detailed".
For technical information, type "Get-Help Get-SPDeveloperDashboard -full".

------------------EXAMPLE------------------

PS C:\> $dash = Get-SPDeveloperDashboard

This example returns back the developer dashboard settings object.

Creating PowerShell Help Files Dynamically

It’s been a while since I’ve blogged anything useful due to all my writing efforts going to the book that I’ve been working on. However, I’ve recently wrapped up my last chapter for the book so I figured what better time to start focusing on my blog again.

The first thing I wanted to cover was something that I should have documented back in May of 2010 when I released my SharePoint 2010 cmdlets and it is something that I just finished referencing in my last book chapter: creating help files for custom cmdlets.

In the book I emphasize that creating these help files is not a trivial task and there are virtually no good tools available to help you with the effort. When I created my SharePoint 2007 cmdlets, I had first tried using the Cmdlet Help Editor v1.0 that the Windows PowerShell team released back in May of 2007; I quickly found that this wasn’t very practical for long term use for numerous reasons, particularly when looking at SharePoint cmdlets where I don’t have a snap-in that I can point the tool to. But the biggest issue I had with using this tool, or any other tool that required me to add descriptions manually, was that I just couldn’t keep up with the changes. I was making new cmdlets and extending existing ones so fast that it was taking me longer to update the help file than it was to create/update the cmdlet – that was just unacceptable to me.

As you may know, I’m all about automation; so I figured, how hard could it possibly be to automate the creation of the help file? All I needed to do was to decorate my cmdlets with some metadata that I could then use with a little reflection to spit out the required XML. I could then generate this XML on the Post Build event of my assembly so that the help file would be automatically updated just prior to the SharePoint Solution Package (WSP) being generated. So, back during the beta days of SharePoint 2010, while migrating my 2007 STSADM extensions to cmdlets, I decided to go ahead and implement my idea. I released it along with my SharePoint 2010 source code with little fanfare (not very many people are generating PowerShell cmdlets and even fewer are creating help files for them). However, with my book having a reference to this code I figured I would write a short post about it and, along the way, break the code out of the SharePoint project and into it’s own project, thereby making it useful for anyone who wishes to dynamically develop Windows PowerShell help files for their cmdlets.

Downloads
You can download the .NET Assembly (Lapointe.PowerShell.MamlGenerator.dll) alone or the source code to the assembly from my downloads page. I thought about providing a separate download for the source but I’m lazy and really didn’t want to have to manage two different download packages; so, if you wish to download the source, just download the SharePoint 2010 source code and you’ll find the Lapointe.PowerShell.MamlGenerator project.

So how does it work? It’s actually quite simple; I’ve created a series of custom Attribute classes which you can use to decorate your cmdlet class. I then use reflection to interrogate the Assembly for any classes that are based on PSCmdlet; for each class I look for these attributes. The rest is just simple XML generation. The Attributes are defined in the following table:

Name	Example
CmdletDescriptionAttribute This Attribute is assigned to the class and contains the main, verbose description, as well as the synopsis for the cmdlet (or shorter description). You can only have one CmdletDescriptionAttribute assigned to the class.	[CmdletDescription("Delete a list from a web site.")]
ExampleAttribute This Attribute is assigned to the class and contains any example code and corresponding descriptions. You may assign multiple instances of the ExampleAttribute to the class (one for each example).	[Example( Code = "PS C:\\> Get-SPList \"http://server_name/lists/mylist\" \| Remove-SPList -BackupDirectory \"c:\\backups\\mylist\"", Remarks = "This example deletes the list mylist and creates a backup of the list in the c:\\backups\\mylist folder.")]
RelatedCmdletsAttribute This Attribute is assigned to the class and contains the listing of related cmdlets. The related cmdlets can be added using the cmdlet's type or any applicable string representation of the cmdlet (appropriate for related cmdlets that are external to the current project). You can only have one RelatedCmdletsAttribute assigned to the class.	[RelatedCmdlets( typeof(SPCmdletGetList), ExternalCmdlets = new[] {"Get-SPWeb"})]
SupportsWildcardsAttribute This Attribute is assigned to the class and indicates whether the cmdlet supports wildcards. This Attribute is a marker only and contains no properties. You can only have one SupportsWildcardsAttribute assigned to the class.	[SupportsWildcards]

These are all the custom Attributes that I’m using; the rest are are native to PowerShell and can be found in the System.Management.Automation namespace. Primarily I’m using CmdletAttribute and ParameterAttribute.

The example is taken from my SharePoint 2010 cmdlets and demonstrates how most of these Attributes are used:

using System.Collections.Generic;
using Microsoft.SharePoint;
using Microsoft.SharePoint.PowerShell;
using System.Management.Automation;
using Lapointe.SharePoint2010.Automation.Cmdlets.PipeBindObjects;
using Lapointe.PowerShell.MamlGenerator.Attributes;

namespace Lapointe.SharePoint2010.Automation.Cmdlets.Lists
{
    [Cmdlet(VerbsCommon.Get, "SPList", SupportsShouldProcess = false),
    SPCmdlet(RequireLocalFarmExist = true)]
    [CmdletDescription("Retrieve an SPList object by name or type. Use the AssignmentCollection parameter to ensure parent objects are properly disposed.")]
    [RelatedCmdlets(typeof(SPCmdletDeleteList), typeof(SPCmdletCopyList), typeof(SPCmdletCopyListSecurity),
        typeof(SPCmdletExportListSecurity), ExternalCmdlets = new[] {"Get-SPWeb", "Start-SPAssignment", "Stop-SPAssignment"})]
    [Example(Code = "PS C:\\> $list = Get-SPList \"http://server_name/lists/mylist\"",
        Remarks = "This example retrieves the list at http://server_name/lists/mylist.")]
    public class SPCmdletGetList : SPGetCmdletBaseCustom<SPList>
    {
        #region Parameters

        [Parameter(Mandatory = false,
            ValueFromPipeline = true,
            Position = 0,
            ParameterSetName = "AllListsInIdentity")]
        public SPListPipeBind Identity { get; set; }

        [Parameter(Mandatory = false,
            ValueFromPipeline = false,
            ParameterSetName = "AllListsByType")]
        public SPBaseType ListType { get; set; }

        [Parameter(Mandatory = false,
            ValueFromPipeline = true,
            HelpMessage = "Specifies the URL or GUID of the Web containing the list to be retrieved.\r\n\r\nThe type must be a valid GUID, in the form 12345678-90ab-cdef-1234-567890bcdefgh; a valid name of Microsoft SharePoint Foundation 2010 Web site (for example, MySPSite1); or an instance of a valid SPWeb object.")]
        public SPWebPipeBind Web { get; set; }

        #endregion

        protected override IEnumerable<SPList> RetrieveDataObjects()
        {
            List<SPList> lists = new List<SPList>();
            SPWeb web = null;
            if (this.Web != null)
                web = this.Web.Read();

            if (Identity == null && ParameterSetName != "AllListsByType")
            {
                foreach (SPList list in web.Lists)
                    lists.Add(list);
            }
            else if (Identity == null && ParameterSetName == "AllListsByType")
            {
                foreach (SPList list in web.GetListsOfType(ListType))
                    lists.Add(list);
            }
            else
            {
                SPList list = this.Identity.Read(web);
                if (list != null)
                    lists.Add(list);
            }

            AssignmentCollection.Add(web);
            foreach (SPList list1 in lists)
            {
                AssignmentCollection.Add(list1.ParentWeb);
                AssignmentCollection.Add(list1.ParentWeb.Site);
            }

            return lists;
        }
    }
}

With the cmdlet properly decorated I can make quick changes to my code and update the help documentation as I update the cmdlet. I don’t have to remember to go to another class file and remember this extremely cryptic MAML based XML format. This makes me considerably more efficient and it keeps my help files more up to date and inline with the actual cmdlet (I wish Microsoft would do something like this as much of the help for the SharePoint 2010 cmdlets is inaccurate, incomplete, or missing entirely).

The following shows a snippet of the help file that gets generated based on the attributes defined (I also use the Assembly’s CopyrightAttribute and DescriptionAttribute to add the copyright details that you see in the XML below):

<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/1" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10">
  <command:details>
    <command:name>Get-SPList</command:name>
    <maml:description>
      <maml:para>Retrieve an SPList object by name or type. Use the AssignmentCollection parameter to ensure parent objects are properly disposed.</maml:para>
    </maml:description>
    <maml:copyright>
      <maml:para>Copyright 2010 Falchion Consulting, LLC</maml:para>
      <maml:para>  &gt; For more information on this cmdlet and others:</maml:para>
      <maml:para>  &gt; http://blog.falchionconsulting.com/</maml:para>
      <maml:para>  &gt; Use of this cmdlet is at your own risk.</maml:para>
      <maml:para>  &gt; Gary Lapointe assumes no liability.</maml:para>
    </maml:copyright>
    <command:verb>Get</command:verb>
    <command:noun>SPList</command:noun>
    <dev:version>1.0.0.0</dev:version>
  </command:details>
  <maml:description>
    <maml:para>Retrieve an SPList object by name or type. Use the AssignmentCollection parameter to ensure parent objects are properly disposed.</maml:para>
    <maml:para />
    <maml:para>Copyright 2010 Falchion Consulting, LLC</maml:para>
    <maml:para>  &gt; For more information on this cmdlet and others:</maml:para>
    <maml:para>  &gt; http://blog.falchionconsulting.com/</maml:para>
    <maml:para>  &gt; Use of this cmdlet is at your own risk.</maml:para>
    <maml:para>  &gt; Gary Lapointe assumes no liability.</maml:para>
  </maml:description>
  <command:syntax>
    <command:syntaxItem>
      <maml:name>Get-SPList</maml:name>
      <command:parameter required="false" position="1">
        <maml:name>Identity</maml:name>
        <command:parameterValue required="true">SPListPipeBind</command:parameterValue>
      </command:parameter>
      <command:parameter required="false" position="named">
        <maml:name>Web</maml:name>
        <command:parameterValue required="true">SPWebPipeBind</command:parameterValue>
      </command:parameter>
      <command:parameter required="false" position="named">
        <maml:name>AssignmentCollection</maml:name>
        <command:parameterValue required="true">SPAssignmentCollection</command:parameterValue>
      </command:parameter>
    </command:syntaxItem>
    <command:syntaxItem>
      <maml:name>Get-SPList</maml:name>
      <command:parameter required="false" position="named">
        <maml:name>ListType</maml:name>
        <command:parameterValue required="true">GenericList | DocumentLibrary | Unused | DiscussionBoard | Survey | Issue | UnspecifiedBaseType</command:parameterValue>
      </command:parameter>
      <command:parameter required="false" position="named">
        <maml:name>Web</maml:name>
        <command:parameterValue required="true">SPWebPipeBind</command:parameterValue>
      </command:parameter>
      <command:parameter required="false" position="named">
        <maml:name>AssignmentCollection</maml:name>
        <command:parameterValue required="true">SPAssignmentCollection</command:parameterValue>
      </command:parameter>
    </command:syntaxItem>
  </command:syntax>
  <command:parameters>
    <command:parameter required="false" globbing="false" pipelineInput="true (ByValue)" position="1" variableLength="false">
      <maml:name>Identity</maml:name>
      <maml:description>
        <maml:para />
      </maml:description>
      <command:parameterValue required="false" variableLength="false">SPListPipeBind</command:parameterValue>
      <dev:type>
        <maml:name>SPListPipeBind</maml:name>
        <maml:uri />
        <maml:description>
          <maml:para />
        </maml:description>
      </dev:type>
    </command:parameter>
    <command:parameter required="false" globbing="false" pipelineInput="false" position="named" variableLength="false">
      <maml:name>ListType</maml:name>
      <maml:description>
        <maml:para />
      </maml:description>
      <command:parameterValue required="false" variableLength="false">SPBaseType</command:parameterValue>
      <dev:type>
        <maml:name>SPBaseType</maml:name>
        <maml:uri />
        <maml:description>
          <maml:para />
        </maml:description>
      </dev:type>
    </command:parameter>
    <command:parameter required="false" globbing="false" pipelineInput="true (ByValue)" position="named" variableLength="false">
      <maml:name>Web</maml:name>
      <maml:description>
        <maml:para>Specifies the URL or GUID of the Web containing the list to be retrieved.</maml:para>
        <maml:para />
        <maml:para>The type must be a valid GUID, in the form 12345678-90ab-cdef-1234-567890bcdefgh; a valid name of Microsoft SharePoint Foundation 2010 Web site (for example, MySPSite1); or an instance of a valid SPWeb object.</maml:para>
      </maml:description>
      <command:parameterValue required="false" variableLength="false">SPWebPipeBind</command:parameterValue>
      <dev:type>
        <maml:name>SPWebPipeBind</maml:name>
        <maml:uri />
        <maml:description>
          <maml:para />
        </maml:description>
      </dev:type>
    </command:parameter>
    <command:parameter required="false" globbing="false" pipelineInput="true (ByValue)" position="named" variableLength="false">
      <maml:name>AssignmentCollection</maml:name>
      <maml:description>
        <maml:para>Manages objects for the purpose of proper disposal. Use of objects, such as SPWeb or SPSite, can use large amounts of memory and use of these objects in Windows PowerShell scripts requires proper memory management. Using the SPAssignment object, you can assign objects to a variable and dispose of the objects after they are needed to free up memory. When SPWeb, SPSite, or SPSiteAdministration objects are used, the objects are automatically disposed of if an assignment collection or the Global parameter is not used.</maml:para>
        <maml:para />
        <maml:para>When the Global parameter is used, all objects are contained in the global store. If objects are not immediately used, or disposed of by using the Stop-SPAssignment command, an out-of-memory scenario can occur.</maml:para>
      </maml:description>
      <command:parameterValue required="false" variableLength="false">SPAssignmentCollection</command:parameterValue>
      <dev:type>
        <maml:name>SPAssignmentCollection</maml:name>
        <maml:uri />
        <maml:description>
          <maml:para />
        </maml:description>
      </dev:type>
    </command:parameter>
  </command:parameters>
  <command:inputTypes>
    <command:inputType>
      <dev:type>
        <maml:name />
        <maml:uri />
        <maml:description>
          <maml:para />
        </maml:description>
      </dev:type>
    </command:inputType>
  </command:inputTypes>
  <command:returnValues>
    <command:returnValue>
      <dev:type>
        <maml:name />
        <maml:uri />
        <maml:description>
          <maml:para />
        </maml:description>
      </dev:type>
    </command:returnValue>
  </command:returnValues>
  <command:terminatingErrors />
  <command:nonTerminatingErrors />
  <maml:alertSet>
    <maml:title />
    <maml:alert>
      <maml:para>For more information, type "Get-Help Get-SPList -detailed". For technical information, type "Get-Help Get-SPList -full".</maml:para>
    </maml:alert>
  </maml:alertSet>
  <command:examples>
    <command:example>
      <maml:title>------------------EXAMPLE------------------</maml:title>
      <dev:code>PS C:\&gt; $list = Get-SPList "http://server_name/lists/mylist"</dev:code>
      <dev:remarks>
        <maml:para>This example retrieves the list at http://server_name/lists/mylist.</maml:para>
      </dev:remarks>
    </command:example>
  </command:examples>
  <maml:relatedLinks>
    <maml:navigationLink>
      <maml:linkText>Remove-SPList</maml:linkText>
      <maml:uri />
    </maml:navigationLink>
    <maml:navigationLink>
      <maml:linkText>Copy-SPList</maml:linkText>
      <maml:uri />
    </maml:navigationLink>
    <maml:navigationLink>
      <maml:linkText>Copy-SPListSecurity</maml:linkText>
      <maml:uri />
    </maml:navigationLink>
    <maml:navigationLink>
      <maml:linkText>Export-SPListSecurity</maml:linkText>
      <maml:uri />
    </maml:navigationLink>
    <maml:navigationLink>
      <maml:linkText>Get-SPWeb</maml:linkText>
      <maml:uri />
    </maml:navigationLink>
    <maml:navigationLink>
      <maml:linkText>Start-SPAssignment</maml:linkText>
      <maml:uri />
    </maml:navigationLink>
    <maml:navigationLink>
      <maml:linkText>Stop-SPAssignment</maml:linkText>
      <maml:uri />
    </maml:navigationLink>
  </maml:relatedLinks>
</command:command>

As you can see, there is a lot of XML that you would have to manually generate (with over 50 cmdlets at the time of writing this and close to a hundred additional planned, you can hopefully understand why I wouldn't want to generate this manually).

So how do you call out to the assembly to generate the help file? Pretty easily! In the Lapointe.PowerShell.MamlGenerator Assembly there is a static class called CmdletHelpGenerator. This class has three static methods that you can call based on how you want to pass in the cmdlet's Assembly information:

public static void GenerateHelp(string outputPath, bool oneFile);
public static void GenerateHelp(string inputFile, string outputPath, bool oneFile);
public static void GenerateHelp(Assembly asm, string outputPath, bool oneFile);

If you want to run this code from PowerShell you can do so using the following syntax:

$asm = "W:\Lapointe.SharePoint2010.Automation.dll"
$cmdletAsm = "W:\Lapointe.PowerShell.MamlGenerator.dll"
$targetPath = "W:\MyProject\POWERSHELL\Help"
[System.Reflection.Assembly]::LoadFrom($asm) | Out-Null
[Lapointe.PowerShell.MamlGenerator.CmdletHelpGenerator]::GenerateHelp($asm, $targetPath, $true)

And again, this works with any cmdlet development, not just SharePoint cmdlet development. Hopefully all you ambitious PowerShell developers out there who appreciate the need to provide your IT Administrators with proper help documentation will find this code as useful as I have.

Good luck and happy PowerShelling!

Tagged as: Help, PowerShell 2 Comments

14May/1016

Announcing My SharePoint 2010 PowerShell Cmdlets & STSADM Commands Now Available for Download

I’ve been wanting to release the SharePoint 2010 version of my STSADM extensions for quite some time but honestly just haven’t had the time to migrate as many as I would have liked. With over 145 STSADM extensions for SharePoint 2007 it was a challenge determining which ones I should focus on initially for the migration.

But today I’m happy to announce my initial release which contains 46 PowerShell cmdlets and 56 STSADM commands specific to SharePoint 2010. Yup, you read right, I’ve decided to maintain support for my STSADM commands and have been migrating them over as I create the equivalent replacement PowerShell cmdlet (though I recommend you don’t use them and suck it up and get used to PowerShell). You should note that there are more STSADM commands than PowerShell cmdlets – that’s because some of the things I was doing with STSADM can now easily be done with out of the box PowerShell cmdlets (I also have new PowerShell cmdlets that do not have an STSADM equivalent – everything new I create will be a cmdlet and I’ll create no new STSADM commands).

It’s going to take me a while to create all the posts needed to explain each cmdlet (assuming I create one at all) so for now I’ve created this simple table which lists all the STSADM commands and PowerShell cmdlets that are available in this initial release (I’ll eventually update my command index page but for now let this serve as the main reference for what is available as of 5/14/2010):

STSADM Commands	PowerShell Cmdlets	Notes
gl-activatefeature	Enable-SPFeature2	There’s an OOTB Enable-SPFeature cmdlet, this one simple adds some capabilities which were present in my existing STSADM command.
gl-addaudiencerule	New-SPAudienceRule
gl-addavailablesitetemplate		I’ll eventually create a cmdlet for this.
gl-adduser2		Use the OOTB New-SPUser cmdlet.
gl-adduserpolicyforwebapp	Add-SPWebApplicationUserPolicy
gl-applytheme		This can be done pretty easily using Get-SPWeb and the ApplyTheme() method of the SPWeb object.
gl-backup		Use the OOTB Backup-SPFarm and Backup-SPSite cmdlets.
gl-backupsites	Backup-SPSite2	Extends Backup-SPSite by including IIS settings.
gl-convertsubsitetositecollection	ConvertTo-SPSite
gl-copycontenttypes	Copy-SPContentType
gl-copylist	Copy-SPList
gl-copylistsecurity	Copy-SPListSecurity
gl-createaudience	New-SPAudience
gl-createcontentdb		Use the OOTB New-SPContentDatabase cmdlet.
gl-createpublishingpage	New-SPPublishingPage
gl-createquotatemplate	New-SPQuotaTemplate
gl-createwebapp		Use the OOTB New-SPWebApplication cmdlet
gl-deactivatefeature	Disable-SPFeature2	Extends the OOTB Disable-SPFeature cmdlet.
gl-deleteallusers		I probably won’t replicate this as it is easily done using the OOTB Remove-SPUser cmdlet.
gl-deleteaudience	Remove-SPAudience
gl-deletelist	Remove-SPList
gl-deletewebapp		Use the OOTB Remove-SPWebApplication cmdlet.
gl-disableuserpermissionforwebapp		This is fairly easy to do OOTB so I may not create a cmdlet for it.
gl-editquotatemplate	Set-SPQuotaTemplate
gl-enableuserpermissionforwebapp		This is fairly easy to do OOTB so I may not create a cmdlet for it.
gl-enumaudiencerules	Export-SPAudienceRules
gl-enumavailablepagelayouts	Get-SPPublishingPageLayout
gl-enumavailablesitetemplates	Get-SPAvailableWebTemplates
gl-enumeffectivebaseperms		This is fairly easy to do OOTB so I may not create a cmdlet for it.
gl-enumfeatures		Use the OOTB Get-SPFeature cmdlet.
gl-enuminstalledsitetemplates		Use the OOTB Get-SPWebTemplate cmdlet.
gl-enumpagewebparts	Get-SPWebPartList
gl-enumunghostedfiles	Get-SPCustomizedPages
gl-execadmsvcjobs	Start-SPAdminJob2	I honestly need to research this a bit more as I’m not sure it’s necessary anymore but I’ve replicated the functionality in case someone finds it useful.
gl-exportaudiences	Export-SPAudiences
gl-exportcontenttypes	Export-SPContentType
gl-exportlist	Export-SPWeb2	I’ve just extended the Export-SPWeb2 cmdlet to add additional parameters.
gl-exportlistsecurity	Export-SPListSecurity
gl-extendwebapp		Use the OOTB New-SPWebApplicationExtension cmdlet.
gl-fixpublishingpagespagelayouturl	Repair-SPPageLayoutUrl
gl-importaudiences	Import-SPAudiences
gl-importlist	Import-SPWeb2	I’ve just extended the Import-SPWeb2 cmdlet to add additional parameters.
gl-importlistsecurity	Import-SPListSecurity
gl-listaudiencetargeting	Set-SPListAudienceTargeting
gl-managecontentdbsettings		Use the OOTB Set-SPContentDatabase cmdlet.
gl-propagatecontenttype	Propagate-SPContentType
gl-publishitems	Publish-SPListItems
gl-reghostfile	Reset-SPCustomizedPages
gl-removeavailablesitetemplate		I’ll eventually create a cmdlet for this (maybe).
gl-repairsitecollectionimportedfromsubsite	Repair-SPSite
gl-replacewebpartcontent	Replace-SPWebPartContent
gl-setbackconnectionhostnames	Set-SPBackConnectionHostNames
gl-setselfservicesitecreation		Not sure if I’ll migrate this or not.
gl-syncquotas	Set-SPQuota
gl-tracelog		Use the OOTB Set-SPDiagnosticConfig cmdlet.
gl-unextendwebapp		Use the OOTB Remove-SPWebApplication cmdlet.
	Get-SPAudience
	Get-SPAudienceManager
	Get-SPContentType
	Get-SPFile
	Get-SPLimitedWebPartManager
	Get-SPList
	Get-SPPublishingPage
	Get-SPQuotaTemplate
	Set-SPAudience

For those that know a thing or two about cmdlet development you might be interested in knowing that I am dynamically generating the help XML file for the cmdlets. If you download the source you’ll find a class which uses reflection to interrogate the assembly and dynamically build the help file just prior to building the WSP package. This saved me literally days of hand editing XML.

You can download the source and WSP files here or from the Downloads page:

After you deploy the package you can type “help <cmdlet name>” to get detailed help about each cmdlet, including parameter descriptions and example usage. If you want to see the list of cmdlets installed type the following:

gcm | where {$_.DLL –like "*lapointe*"}

As always, your use of these cmdlets/stsadm commands is at your own risk – I do as much testing as I can but every environment is different and there’s simply not enough time in a day. If you have any suggestions or feedback please don’t hesitate to leave a comment – I appreciate all of them!

Tagged as: Cmdlets, Commands, Downloads, PowerShell, SharePoint Foundation 2010, SharePoint Server 2010, STSADM 16 Comments

19Oct/095

Creating Custom SharePoint 2010 Cmdlets using Visual Studio 2010

With SharePoint 2010 we now have the ability to create custom PowerShell cmdlets that can be deployed just like any other SharePoint artifact using SharePoint Solution Packages (WSP) created with Visual Studio 2010. With SharePoint 2007 it was necessary to build a custom setup (MSI) package which had to be run on every server in the farm. This setup package would register a custom snap-in that you'd have to create which would be responsible for registering all of your custom cmdlets with the PowerShell runtime.

With SharePoint 2010 we no longer have to create a custom snap-in or setup package. When the Microsoft.SharePoint.PowerShell snap-in is loaded it examines the {SharePointRoot}/Config/PowerShell/Registration folder for any XML files and dynamically registers the cmdlets specified in the XML. As long as the SharePoint binaries have been installed on the server then you can utilize this feature (if the farm has not yet been created then you'll have to manually GAC the assembly and deploy the registration XML file as solution deployments only work when the farm exists).

To facilitate a standard and consistent scripting experience SharePoint 2010 introduces five new base classes that all SharePoint 2010 PowerShell cmdlets should be derived from:

When creating your custom cmdlet you should carefully choose the correct base class for your cmdlet. When creating a cmdlet that is meant to work with persistent objects (objects that are to be used across calls) you should utilize one of the four task based base classes: SPRemoveCmdletBase, SPNewCmdletBase, SPSetCmdletBase, or SPGetCmdletBase. When creating cmdlets that return non-persistent objects/data or perform tasks that do not require a persistent object (e.g., Start-SP*) then you should use the SPCmdlet base class. A good example of a cmdlet that would use the SPCmdlet base class would be one what returns a report or some other information without returning back any specific objects.

Let's now take a look at an example of a custom cmdlet that we'll eventually package up in a SharePoint Solution Package:

using System;
using System.Collections.Generic;
using System.Text;
using Microsoft.SharePoint;
using Microsoft.SharePoint.PowerShell;
using Microsoft.SharePoint.Administration;
using System.Management.Automation;

namespace Lapointe.SharePoint2010.PowerShell.Demo.Quotas
{
    [Cmdlet(VerbsCommon.Get, "SPQuotaTemplate"),
    SPCmdlet(RequireLocalFarmExist = true, RequireUserFarmAdmin = true)]
    public class SPCmdletGetQuotaTemplate : SPGetCmdletBase<SPQuotaTemplate>
    {
        protected override void InternalValidate()
        {
            if (this.Identity != null)
            {
                base.DataObject = this.Identity.Read();
                if (base.DataObject == null)
                {
                    base.WriteError(new PSArgumentException("The quota template does not exist."), ErrorCategory.InvalidArgument, this.Identity);
                    base.SkipProcessCurrentRecord();
                }
            }
        }

        protected override IEnumerable<SPQuotaTemplate> RetrieveDataObjects()
        {
            List<SPQuotaTemplate> list = new List<SPQuotaTemplate>();
            if (base.DataObject != null)
            {
                list.Add(base.DataObject);
                return list;
            }
            SPWebService webService = SPWebService.ContentService;
            if (webService != null)
            {
                foreach (SPQuotaTemplate quota in webService.QuotaTemplates)
                {
                    list.Add(quota);
                }
            }

            return list;
        }

        [Parameter(Mandatory = false, ValueFromPipeline = true, Position = 0), Alias(new string[] { "Name" })]
        public SPQuotaTemplatePipeBind Identity
        {
            get;
            set;
        }
    }
}

In the code example above I'm returning back SPQuotaTemplate objects based on the Identity (or Name) passed into the cmdlet. If the Identity parameter is not provided then all quota templates are returned to the pipeline. In the InternalValidate method I'm checking if the Identity parameter has been provided, and if it has, I set the base class's DataObject property by calling the Read method of the SPQuotaTemplatePipeBind object. In the override RetrieveDataObjects method I then check the DataObject property and return the value as an item in a generic list. If the DataObject property has not been set then I loop through all existing quota templates and return them as generic list. Note that if you are returning lots of items or large items it is better, and preferable, to directly call the WriteResult method and return back null - for this case I know there are typically not a lot of templates and they are not large so I just return back a single collection rather than calling WriteResult.

Pay particular attention to the SPQuotaTemplatePipeBind type - In SharePoint an object can be represented in numerous ways, for example, an SPSite object can be represented by either an URL or a GUID. In order to prevent the need to multiple parameters to support these various types Microsoft has introduced the PipeBind object which eliminates the need for these superfluous parameters and from having to create multiple parameter sets to support them. In the case of the SPQuotaTemplatePipeBind object I can pass in either an actual instance of an SPQuotaTemplate object or a name representing a quota template.

You're not limited to what is available out of the box. You can easily create your own PipeBind objects by simply inheriting from the SPCmdletPipeBind class. Take a look at the following example which demonstrates how to create a custom SPListPipeBind object:

using System;
using System.Collections.Generic;
using Microsoft.SharePoint;
using Microsoft.SharePoint.PowerShell;
using System.Management.Automation;
using System.Globalization;

namespace Lapointe.SharePoint2010.PowerShell.Demo.Lists
{
    public sealed class SPListPipeBind : SPCmdletPipeBind<SPList>
    {
        private bool m_IsAbsoluteUrl;
        private bool m_IsCollection;
        private Guid m_SiteGuid;
        private Guid m_WebGuid;
        private Guid m_ListGuid;
        private string m_WebUrl;
        private string m_ListUrl;

        public SPListPipeBind(SPList instance)
            : base(instance)
        {
        }

        public SPListPipeBind(Guid guid)
        {
            this.m_ListGuid = guid;
        }

        public SPListPipeBind(string inputString)
        {
            if (inputString != null)
            {
                inputString = inputString.Trim();
                try
                {
                    this.m_ListGuid = new Guid(inputString);
                }
                catch (FormatException)
                {
                }
                catch (OverflowException)
                {
                }
                if (this.m_ListGuid.Equals(Guid.Empty))
                {
                    this.m_ListUrl = inputString;
                    if (this.m_ListUrl.StartsWith("http", true, CultureInfo.CurrentCulture))
                    {
                        this.m_IsAbsoluteUrl = true;
                    }
                    if (WildcardPattern.ContainsWildcardCharacters(this.m_ListUrl))
                    {
                        this.m_IsCollection = true;
                    }
                }
            }
        }

        public SPListPipeBind(Uri listUri)
        {
            this.m_ListUrl = listUri.ToString();
        }

        protected override void Discover(SPList instance)
        {
            this.m_ListGuid = instance.ID;
            this.m_WebGuid = instance.ParentWeb.ID;
            this.m_SiteGuid = instance.ParentWeb.Site.ID;
        }

        public override SPList Read()
        {
            return this.Read(null);
        }

        public SPList Read(SPWeb web)
        {
            SPList list = null;
            string parameterDetails = string.Format(CultureInfo.CurrentCulture, "Id or Url : {0}", new object[] { "Empty or Null" });
            if (this.IsCollection)
            {
                return null;
            }
            try
            {
                if (Guid.Empty != this.ListGuid)
                {
                    if (web == null && Guid.Empty != this.m_WebGuid && Guid.Empty != this.m_SiteGuid)
                    {
                        parameterDetails = string.Format(CultureInfo.CurrentCulture, "Id or Url: {0} and Web Id: {1}", new object[] { this.ListGuid.ToString(), this.m_WebGuid.ToString() });
                        using (SPSite site = new SPSite(this.m_SiteGuid))
                        {
                            web = site.OpenWeb(this.m_WebGuid);
                            list = web.Lists[ListGuid];
                        }
                    }
                    else
                    {
                        parameterDetails = string.Format(CultureInfo.CurrentCulture, "Id or Url: {0} and web Url {1}", new object[] { this.ListUrl, web.Url });
                        list = web.Lists[ListGuid];
                    }
                }
                else if (!string.IsNullOrEmpty(this.ListUrl))
                {
                    string serverRelativeListUrl = null;
                    if (this.m_IsAbsoluteUrl)
                    {
                        serverRelativeListUrl = Utilities.GetServerRelUrlFromFullUrl(this.ListUrl).Trim('/');
                    }
                    else
                    {
                        serverRelativeListUrl = this.ListUrl.Trim('/');
                    }
                    if (web == null)
                    {
                        parameterDetails = string.Format(CultureInfo.CurrentCulture, "Id or Url : {0}", new object[] { this.ListUrl });
                        using (SPSite site = new SPSite(this.ListUrl))
                        {
                            web = site.OpenWeb();
                        }
                    }
                    else
                    {
                        parameterDetails = string.Format(CultureInfo.CurrentCulture, "Id or Url : {0} and web Url {1}", new object[] { this.ListUrl, web.Url });
                    }
                    if (!web.Exists)
                    {
                        list = null;
                    }
                    else
                    {
                        list = web.GetList(serverRelativeListUrl);
                    }
                }
            }
            catch (Exception exception)
            {
                throw new SPCmdletPipeBindException(string.Format("The SPList Pipebind object could not be found ({0}).", parameterDetails), exception);
            }
            if (list == null)
            {
                throw new SPCmdletPipeBindException(string.Format("The SPList Pipebind object could not be found ({0}).", parameterDetails));
            }
            return list;
        }

        public bool IsCollection
        {
            get
            {
                return this.m_IsCollection;
            }
        }

        public Guid ListGuid
        {
            get
            {
                return this.m_ListGuid;
            }
        }

        public string ListUrl
        {
            get
            {
                return this.m_ListUrl;
            }
        }
    }
}

There are two core components that are required for a custom PipeBind object. The first is to have a constructor that takes in the type that you wish to convert (in this example, a string, URI, or GUID) to the target object. The second is to override the Read method which is used to convert the argument value passed into the constructor into the target type. In some cases you'll need additional information which must be provided by the calling code - for example, if a GUID is passed in, representing the List ID, then you will also need to provide the SPWeb object which contains the List; this is done by creating an overload for the Read method which accepts an SPWeb object. It's up to the calling code to determine which overload to call.

Let's now look at how we can package our SPCmdletGetQuotaTemplate class into a SharePoint Solution Package using Visual Studio 2010.

From a new instance of Visual Studio 2010:

Click File > New > Project to create a new Visual Studio Project
In the New Project dialog select Visual C#/SharePoint/2010 in the Installed Templates panel and then select Empty Project:
After you click OK you will be taken to the SharePoint Configuration Wizard:

You can specify any site to use for debugging as we won't be using it for PowerShell development (note that when you start the debugger you'll be given a warning if the specified site's web.config does not allow debugging). PowerShell cmdlets must be deployed to the GAC so select Deploy as full-trust solution and click the Finish button to create the project.

The first thing we need to do with our new empty project is to add a couple of project references:

Right-click the References folder in the project and select Add Reference...
In the Add Reference dialog's .NET tab select Microsoft.SharePoint.PowerShell and System.Management.Automation
Click OK to add the references to the project

Now that we have our references added we can setup our project structure. PowerShell cmdlets are not deployed using Features so we can delete the starting Feature folder that is created:

Expand the Features folder
Right-click the Feature1 Feature and click Delete

The next step is to add a SharePoint Mapped Folder:

Right-click the project and click Add > SharePoint Mapped Folder...
Add the {SharePointRoot}/Config/PowerShell/Registration folder
1. Note that you can add the Format and Help folders as well but I won't be using those in this example as creating help and format files are outside the scope of this article (I usually will add the {SharePointRoot}/Config/PowerShell folder and then manually add the three sub-folders so that I can keep things grouped together in one parent folder within my project).
Click OK to add the mapped folder
1. If a folder is created under the Registration folder then go ahead and delete it (this sub-folder is automatically added in Beta1 but may not be added come RTM)

In the new Registration mapped folder create a new XML file (you can name it anything you like but I usually give it the same name as my project) and paste the following XML into the file:

<?xml version="1.0" encoding="utf-8" ?>
<ps:Config xmlns:ps="urn:Microsoft.SharePoint.PowerShell"
                     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                     xsi:schemaLocation="urn:Microsoft.SharePoint.PowerShell  SPCmdletSchema.xsd">

  <ps:Assembly Name="$SharePoint.Project.AssemblyFullName$">
    <ps:Cmdlet>
      <ps:VerbName>Get-SPQuotaTemplate</ps:VerbName>
      <ps:ClassName>Lapointe.SharePoint2010.PowerShell.Demo.Quotas.SPCmdletGetQuotaTemplate</ps:ClassName>
      <ps:HelpFile>Lapointe.SharePoint2010.PowerShell.Demo.dll-help.xml</ps:HelpFile>
    </ps:Cmdlet>
  </ps:Assembly>
</ps:Config>

Note that the <ps:HelpFile /> element does require a value but the file specified does not have to exist.

Now we simply need to paste in the code for the SPCmdletGetQuotaTemplate class from above:

Create a folder below the project root called Quotas
Add a new class file named SPCmdletGetQuotaTemplate.cs
Paste the code from above into this file (be sure to adjust your namespaces in the class file and the XML file if you used a different project name than the one shown)

You now have a complete SharePoint 2010 PowerShell Solution - all that's left is to build and deploy it:

Right-click the project name and select Deploy

Notice what is happening in the output window - IIS application pools are being recycled along with the retraction and deployment of the solution. Because this is a PowerShell solution we don't need IIS to be recycled so let's create a new deployment configuration to remove the recycling of the application pools which should speed up our deployment time:

Right-click the project and select Properties
In the properties dialog select the Deploy tab
In the Edit Configurations group select New to create a new deployment action
Name the new deployment action PowerShell and configure the deployment steps as shown below:
Click OK to save the new deployment configuration

Now that we have our custom deployment configuration we need to tell our project to use this configuration. Make sure the Properties Window is visible (type F4 if not) and select the project. Select the PowerShell configuration we just created in the Active Deployment Configuration drop-down.

Our final configuration setting change is to configure the project so that it will open PowerShell when we start the debugger:

Right-click the project and select Properties to return to the project's properties dialog
Click the Debug tab
Select the radio button next to Start external program and specify the following value: C:\Windows\System32\WindowsPowerShell\v1.0\PowerShell.exe
Paste the following into the Command line arguments text box: -NoExit " & ' C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\CONFIG\POWERSHELL\Registration\sharepoint.ps1 ' "

You can now start the debugger (F5) which will load a PowerShell console and register the SharePoint 2010 snap-in which results in the loading of your new custom cmdlet. To verify that the cmdlet is loaded type Get-Command Get-SPQuotaTemplate | Format-List. You should see the following output:

PS C:\> Get-Command Get-SPQuotaTemplate | Format-List

Name             : Get-SPQuotaTemplate
CommandType      : Cmdlet
Definition       : Get-SPQuotaTemplate [[-Identity] <SPQuotaTemplatePipeBind>]
                   [-AssignmentCollection <SPAssignmentCollection>] [-Verbose]
                   [-Debug] [-ErrorAction <ActionPreference>] [-WarningAction <
                   ActionPreference>] [-ErrorVariable <String>] [-WarningVariab
                   le <String>] [-OutVariable <String>] [-OutBuffer <Int32>]

Path             :
AssemblyInfo     :
DLL              : C:\Windows\assembly\GAC_MSIL\Lapointe.SharePoint2010.PowerSh
                   ell.Demo\1.0.0.0__xxxxxxxxxxxxxxxx\Lapointe.SharePoint2010.P
                   owerShell.Demo.dll
HelpFile         : C:\Program Files\Common Files\Microsoft Shared\Web Server Ex
                   tensions\14\CONFIG\PowerShell\Help\Lapointe.SharePoint2010.P
                   owerShell.Demo.dll-help.xml
ParameterSets    : {[[-Identity] <SPQuotaTemplatePipeBind>] [-AssignmentCollect
                   ion <SPAssignmentCollection>] [-Verbose] [-Debug] [-ErrorAct
                   ion <ActionPreference>] [-WarningAction <ActionPreference>]
                   [-ErrorVariable <String>] [-WarningVariable <String>] [-OutV
                   ariable <String>] [-OutBuffer <Int32>]}
ImplementingType : Lapointe.SharePoint2010.PowerShell.Demo.Quotas.SPCmdletGetQu
                   otaTemplate
Verb             : Get
Noun             : SPQuotaTemplate

As you can see, creating and deploying custom PowerShell cmdlets for SharePoint 2010 using Visual Studio 2010 is now super easy. The only complexity lies in the logic of the cmdlet itself.

As you probably expected I have already been hard at work on creating some new cmdlets to replace some of my old PowerShell cmdlets as well as a few select STSADM commands. I'll be releasing these new cmdlets with full source shortly - keep checking back here for more example code and downloads!

Tagged as: Cmdlets, PowerShell, SharePoint Foundation 2010, SharePoint Server 2010, Visual Studio 2010 5 Comments

19Oct/0923

SharePoint 2010: PSConfig and PowerShell

The information in this article is based on BETA 2 of SharePoint 2010 - there may be differences with the RTM release.

Update 12/18/2009: I've updated the post to reflect BETA 2 changes and have considerably simplified the script removing all the dependencies on helper functions so that the core pieces required to build a basic farm are focused on rather than the complex elements to support tracing and error handling as I previously had it.

If you've ever done a scripted install of SharePoint 2007 then you are familiar with how to script the initial farm creation using psconfig.exe. Unfortunately psconfig is still with us in SharePoint 2010 but we do have some PowerShell cmdlets which replace all the psconfig commands.

Before we look at how to use PowerShell lets refresh our memories by looking at an install script for SharePoint 2007. I usually have two scripts, one for the first server and a second script for additional servers - here's the first script (I've omitted the variable declarations):

        1: ECHO %DATE% %TIME%:  Building configuration database

       2: psconfig -cmd configdb -create -server %SERVER_DB% -database %DB_CONFIG_NAME% -user %ACCT_SPFARM% -password %ACCT_SPFARM_PWD% -admincontentdatabase %DB_CENTRALADMINCONTENT_NAME% 

       3: if not errorlevel 0 goto errhnd

       4:  

       5: ECHO %DATE% %TIME%: Installing help content

       6: psconfig -cmd helpcollections -installall 

       7: if not errorlevel 0 goto errhnd

       8:  

       9: ECHO %DATE% %TIME%: Securing resources

psconfig -cmd secureresources 

if not errorlevel 0 goto errhnd

  

ECHO %DATE% %TIME%: Installing services

psconfig -cmd services -install 

if not errorlevel 0 goto errhnd

  

ECHO %DATE% %TIME%: Installing features

psconfig -cmd installfeatures 

if not errorlevel 0 goto errhnd

  

ECHO %DATE% %TIME%: Creating central admin site

psconfig -cmd adminvs -provision -port %CENTRALADMIN_PORT% -windowsauthprovider enablekerberos 

if not errorlevel 0 goto errhnd

  

ECHO %DATE% %TIME%: Adding application content to central admin site

psconfig -cmd applicationcontent -install

if not errorlevel 0 goto errhnd

  

goto end

  

:errhnd

  

echo An error occured - terminating script.

  

:end

And here's the second script (variable declarations omitted):

       1: ECHO %DATE% %TIME%: Connecting to farm

       2: psconfig -cmd configdb -connect -server %SERVER_DB% -database %DB_CONFIG_NAME% -user %ACCT_SPFARM% -password %ACCT_SPFARM_PWD%

       3: if not errorlevel 0 goto errhnd

       4:  

       5: ECHO %DATE% %TIME%: Installing services

       6: psconfig -cmd services install

       7: if not errorlevel 0 goto errhnd

       8:  

       9: ECHO %DATE% %TIME%: Installing features

      10: psconfig -cmd installfeatures

      11: if not errorlevel 0 goto errhnd

      12:  

      13: ECHO %DATE% %TIME%: Setting security on registry and file system

      14: psconfig -cmd secureresources

      15: if not errorlevel 0 goto errhnd

      16:  

      17: goto end

      18:  

      19: :errhnd

      20:  

      21: echo An error occured - terminating script.

      22:  

      23: :end

Obviously the two scripts are very similar with the main difference being the parameters passed to the configdb command and with fewer commands being called. So how would we do this using SharePoint 2010's PowerShell cmdlets? First lets list each psconfig command and what the PowerShell equivalent is:

PSConfig Command	PowerShell Cmdlet
configdb -create	New-SPConfigurationDatabase
configdb -connect	Connect-SPConfigurationDatabase
helpcollections -installall	Install-SPHelpCollection
secureresources	Initialize-SPResourceSecurity
services -install	Install-SPService
installfeatures	Install-SPFeature (provide the -AllExistingFeatures parameter)
adminvs -provision	New-SPCentralAdministration
applicationcontent -install	Install-SPApplicationContent

Now that we know what PowerShell cmdlets to use lets rework our install script. Instead of using a batch file for variables I'm going to use an XML file which can be read in and parsed as needed. I'm also going to make it so that you can run the same script from any server and just specify a switch parameter indicating whether or not you are connecting to an existing farm or not.

Let's first take a look at the XML that we'll use to manage our settings - we'll store this in a file called FarmConfigurations.xml:

<Farm FarmAccount="sp2010\spfarm" 
      ConfigDB="SharePoint_ConfigDB" 
      AdminContentDB="SharePoint_Content_Admin"
      DatabaseServer="spsql1" 
      Passphrase="Pa$$w0rd">
    <CentralAdmin Port="1234" AuthProvider="NTLM">
        <Servers>
            <Server Name="spsvr1" />
        </Servers>
    </CentralAdmin>
</Farm>

In this XML I'm storing the core farm settings in the <Farm /> element which includes attributes for the farm account to use as well as the database server and names for the configuration and central admin content database. I then have a <CentralAdmin /> element which contains the servers that the Central Admin site should be installed on along with the port and authentication provider to use.

So now that we have our configuration settings all we need now is the core script to actually create our farm. I named this script BuildFarm.ps1 but you can name it whatever you want:

function Install-SharePointFarm([bool]$connectToExisting, 
    [string]$settingsFile = "FarmConfigurations.xml") {
    
    [xml]$config = Get-Content $settingsFile

    $farmAcct = Get-Credential $config.Farm.FarmAccount

    $configDb = $config.Farm.ConfigDB
    $adminContentDb = $config.Farm.adminContentDb
    $server = $config.Farm.DatabaseServer
    if ($config.Farm.Passphrase.Length -gt 0) {
        $passphrase = (ConvertTo-SecureString $config.Farm.Passphrase `
            -AsPlainText -force)
    } else {
        Write-Warning "Using the Farm Admin's password for a passphrase"
        $passphrase = $farmAcct.Password
    }
    
    #Only build the farm if we don't currently have a farm created
    if (([Microsoft.SharePoint.Administration.SPFarm]::Local) -eq $null) {
        if ($connectToExisting) {
            #Connecting to farm
            Connect-SPConfigurationDatabase -DatabaseName $configDb `
                -DatabaseServer $server -Passphrase $passphrase
        } else {
            #Creating new farm
            New-SPConfigurationDatabase -DatabaseName $configDb `
                -DatabaseServer $server `
                -AdministrationContentDatabaseName $adminContentDb `
                -Passphrase $passphrase -FarmCredentials $farmAcct
        }
        #Verifying farm creation
        $spfarm = Get-SPFarm -ErrorAction SilentlyContinue -ErrorVariable err
        if ($spfarm -eq $null -or $err) {
            throw "Unable to verify farm creation."
        }
        
        #ACLing SharePoint Resources
        Initialize-SPResourceSecurity

        #Installing Services
        Install-SPService
        
        #Installing Features
        Install-SPFeature -AllExistingFeatures
    } else {
        Write-Warning "Farm already exists. Skipping creation."
    }
    
    $installSCA = (($config.Farm.CentralAdmin.Servers.Server | `
        where {$_.Name -eq $env:computername}) -ne $null)
    $url = "http://$($env:computername):$($config.Farm.CentralAdmin.Port)"
    $sca=[Microsoft.SharePoint.Administration.SPWebApplication]::Lookup($url)
    if ($installSCA -and $sca -eq $null) {
        #Provisioning Central Administration
        New-SPCentralAdministration -Port $config.Farm.CentralAdmin.Port `
            -WindowsAuthProvider $config.Farm.CentralAdmin.AuthProvider
       
        #Installing Help
        Install-SPHelpCollection -All

        #Installing Application Content
        Install-SPApplicationContent
    }
}

Notice that the script takes a parameter which allows you to specify whether you are connecting to an existing farm. We can call the script using the following syntax (replace $false with $true if connecting to an existing farm):

PS C:\> . .\buildfarm.ps1
PS C:\> Install-SharePointFarm $false "FarmConfigurations.xml"

In a series of upcoming post I'll be building on what I created here by demonstrating how to create web applications and how to start each of the services that are included, including the extremely complex search service (gone are the days of a single line setup for search - we now have a dozen or so cmdlets that have to be run to get search started).

Tagged as: PowerShell, PSConfig, SharePoint Foundation 2010, SharePoint Server 2010 23 Comments

19Oct/091

SharePoint 2010: STSADM and PowerShell

The information in this article is based on BETA 2 of SharePoint 2010 - there will likely be differences with the RTM release.

Finally, the NDA is lifted and we can openly talk about SharePoint 2010! There's so many cool things to talk about it's hard to decide where to begin, but as the focus of my blog has generally been on STSADM then I suppose that's a good place to start. The first thing we should do is load the new SharePoint 2010 Management Shell which can be found under the Microsoft SharePoint 2010 Products section of the start menu:

This new console window is actually just a PowerShell console which pre-loads the SharePoint PowerShell Snap-in. You can see that by looking at the target for the shortcut:

C:\Windows\System32\WindowsPowerShell\v1.0\PowerShell.exe -NoExit " & ' C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\CONFIG\POWERSHELL\Registration\\sharepoint.ps1 ' "

If you look at the SharePoint.ps1 file you'll see the following:

From this you can see that you can easily load up any PowerShell console app (either the native PowerShell console or a any other editor such as PowerGUI or the PowerShell ISE) and simply run the Add-PsSnapin cmdlet to load the new SharePoint 2010 cmdlets as shown above.

Note that the script is also changing the threading model of PowerShell so that commands are entered in the same thread rather than a different thread for each line of execution (I'll cover this in more detail in a later post but it's important to understand that this has a huge impact on how objects are disposed within PowerShell - see Zach's post about threading here: http://sharepoint.microsoft.com/blogs/zach/Lists/Posts/Post.aspx?ID=34)

I'll cover the PowerShell stuff in bit but first lets take a look at the STSADM changes. I did a simple stsadm -help command and saved that to a file in both my 2007 and 2010 environment and then compared those files. Here's what I found:

The following STSADM commands no longer exist:
- associatewebapp
- createcmsmigrationprofile
- createssp
- deletecmsmigrationprofile
- deletessp
- deletessptimerjob
- editcmsmigrationprofile
- editssp
- enablecmsurlredirect
- enumssp
- enumssptimerjobs
- grantiis7permission
- listqueryprocessoroptions
- mysite
- preupgradecheck
- restoressp
- runcmsmigrationprofile
- setdefaultssp
- setqueryprocessoroptions
- setsharedwebserviceauthn
- setsspport
- trimauditlog
The following STSADM commands have been added:
- add-adsdefaultapplication
- add-ecsblockedexcelfiletype
- monitordb
- patchpostaction
- remove-adsdefaultapplication
- remove-ecsblockedexcelfiletype

From the list above you can see that the bulk of the items removed have to do with the SSP and CMS migration features which were part of the 2007 product but have been removed from the 2010 product (2010 has a whole new services architecture which is really cool, but outside the scope of this article - stay tuned! - 2010 also does not support upgrading from Microsoft CMS, you must upgrade to SharePoint 2007 and then SharePoint 2010).

Also note that very few new commands have been added - in fact I was surprised to see that any were added - why? Because PowerShell is what we should all be using - STSADM is dead - just don't use it, forget that these new commands have been added as there are PowerShell equivalents (I wouldn't be surprised if they get pulled come RTM). That said, at beta there may be some stuff that still only exists with STSADM but expect that not to be the case going forward.

So now that we have that out of the way, lets talk about some PowerShell (as of this post I'm officially done creating STSADM extensions - at least for 2010, I may still have need for some new stuff with the 2007 product). In your new SharePoint 4.0 Management Console type the following command: gcm -pssnapin microsoft.sharepoint.powershell | select Name, Definition | fl > .\sp2010cmdlets.txt

Take a look at the file you just generated, you now have a listing of the 535 new PowerShell cmdlets that ship with SharePoint 2010. For brevity sake I won't show the syntax but here's a listing of all the new cmdlets that are available:

Add-PluggableSecurityTrimmer
Add-SPClaimTypeMapping
Add-SPDiagnosticsPerformanceCounter
Add-SPInfoPathUserAgent
Add-SPServiceApplicationProxyGroupMember
Add-SPShellAdmin
Add-SPSiteSubscriptionFeaturePackMember
Add-SPSiteSubscriptionProfileConfig
Add-SPSolution
Add-SPUserSolution
Backup-SPConfigurationDatabase
Backup-SPFarm
Backup-SPSite
Clear-SPLogLevel
Clear-SPMetadataWebServicePartitionData
Clear-SPPerformancePointServiceApplicationTrustedLocation
Clear-SPSecureStoreCredentialMapping
Clear-SPSecureStoreDefaultProvider
Clear-SPSiteSubscriptionBusinessDataCatalogConfig
Connect-SPConfigurationDatabase
Copy-SPBusinessDataCatalogAclToChildren
Disable-SPBusinessDataCatalogEntity
Disable-SPFeature
Disable-SPInfoPathFormTemplate
Disable-SPSessionStateService
Disable-SPSingleSignOn
Disable-SPTimerJob
Disable-SPWebApplicationHttpThrottling
Disconnect-SPConfigurationDatabase
Dismount-SPContentDatabase
Dismount-SPStateServiceDatabase
Enable-SPBusinessDataCatalogEntity
Enable-SPFeature
Enable-SPInfoPathFormTemplate
Enable-SPSessionStateService
Enable-SPTimerJob
Enable-SPWebApplicationHttpThrottling
Export-SPBusinessDataCatalogModel
Export-SPEnterpriseSearchTopology
Export-SPInfoPathAdministrationFiles
Export-SPMetadataWebServicePartitionData
Export-SPSiteSubscriptionBusinessDataCatalogConfig
Export-SPSiteSubscriptionProfileConfig
Export-SPSiteSubscriptionSettings
Export-SPWeb
Get-PluggableSecurityTrimmer
Get-SPAccessServiceApplication
Get-SPAlternateURL
Get-SPAuthenticationProvider
Get-SPBackupHistory
Get-SPBrowserCustomerExperienceImprovementProgram
Get-SPBusinessDataCatalogMetadataObject
Get-SPBusinessDataCatalogThrottleConfig
Get-SPCertificateAuthority
Get-SPClaimProvider
Get-SPClaimProviderManager
Get-SPContentDatabase
Get-SPContentDeploymentJob
Get-SPContentDeploymentPath
Get-SPCustomLayoutsPage
Get-SPDatabase
Get-SPDataConnectionFile
Get-SPDataConnectionFileDependent
Get-SPDesignerSettings
Get-SPDiagnosticConfig
Get-SPDiagnosticsPerformanceCounter
Get-SPDiagnosticsProvider
Get-SPEnterpriseSearchAdministrationComponent
Get-SPEnterpriseSearchCrawlComponent
Get-SPEnterpriseSearchCrawlContentSource
Get-SPEnterpriseSearchCrawlCustomConnector
Get-SPEnterpriseSearchCrawlDatabase
Get-SPEnterpriseSearchCrawlExtension
Get-SPEnterpriseSearchCrawlMapping
Get-SPEnterpriseSearchCrawlRule
Get-SPEnterpriseSearchCrawlTopology
Get-SPEnterpriseSearchExtendedClickThroughExtractorJobDefinition
Get-SPEnterpriseSearchExtendedConnectorProperty
Get-SPEnterpriseSearchExtendedQueryProperty
Get-SPEnterpriseSearchIndexPartition
Get-SPEnterpriseSearchLanguageResourcePhrase
Get-SPEnterpriseSearchMetadataCategory
Get-SPEnterpriseSearchMetadataCrawledProperty
Get-SPEnterpriseSearchMetadataManagedProperty
Get-SPEnterpriseSearchMetadataMapping
Get-SPEnterpriseSearchPropertyDatabase
Get-SPEnterpriseSearchQueryAndSiteSettingsService
Get-SPEnterpriseSearchQueryAndSiteSettingsServiceInstance
Get-SPEnterpriseSearchQueryAndSiteSettingsServiceProxy
Get-SPEnterpriseSearchQueryAuthority
Get-SPEnterpriseSearchQueryComponent
Get-SPEnterpriseSearchQueryDemoted
Get-SPEnterpriseSearchQueryKeyword
Get-SPEnterpriseSearchQueryScope
Get-SPEnterpriseSearchQueryScopeRule
Get-SPEnterpriseSearchQuerySuggestionCandidates
Get-SPEnterpriseSearchQueryTopology
Get-SPEnterpriseSearchRankingModel
Get-SPEnterpriseSearchSecurityTrimmer
Get-SPEnterpriseSearchService
Get-SPEnterpriseSearchServiceApplication
Get-SPEnterpriseSearchServiceApplicationProxy
Get-SPEnterpriseSearchServiceInstance
Get-SPEnterpriseSearchSiteHitRule
Get-SPExcelBlockedFileType
Get-SPExcelDataConnectionLibrary
Get-SPExcelDataProvider
Get-SPExcelFileLocation
Get-SPExcelServiceApplication
Get-SPExcelUserDefinedFunction
Get-SPFarm
Get-SPFarmConfig
Get-SPFeature
Get-SPHelpCollection
Get-SPIisWebServiceApplicationPool
Get-SPIisWebServiceSettings
Get-SPInfoPathFormsService
Get-SPInfoPathFormTemplate
Get-SPInfoPathUserAgent
Get-SPInfoPathWebServiceProxy
Get-SPLogEvent
Get-SPLogLevel
Get-SPManagedAccount
Get-SPManagedPath
Get-SPMetadataServiceApplication
Get-SPMetadataServiceApplicationProxy
Get-SPMobileMessagingAccount
Get-SPPerformancePointSecureDataValues
Get-SPPerformancePointServiceApplication
Get-SPPerformancePointServiceApplicationTrustedLocation
Get-SPProcessAccount
Get-SPProduct
Get-SPProfileServiceApplicationSecurity
Get-SPSearchService
Get-SPSearchServiceInstance
Get-SPSecureStoreApplication
Get-SPSecurityTokenService
Get-SPServer
Get-SPServiceApplication
Get-SPServiceApplicationProxy
Get-SPServiceApplicationProxyGroup
Get-SPServiceApplicationSecurity
Get-SPServiceContext
Get-SPServiceEndpoint
Get-SPServiceInstance
Get-SPSessionStateService
Get-SPShellAdmin
Get-SPSite
Get-SPSiteAdministration
Get-SPSiteSubscription
Get-SPSiteSubscriptionConfig
Get-SPSiteSubscriptionEdiscoveryHub
Get-SPSiteSubscriptionEdiscoverySearchScope
Get-SPSiteSubscriptionFeaturePack
Get-SPSiteSubscriptionMetadataConfig
Get-SPSolution
Get-SPStateServiceApplication
Get-SPStateServiceApplicationProxy
Get-SPStateServiceDatabase
Get-SPTaxonomySession
Get-SPTimerJob
Get-SPTopologyWebServiceApplication
Get-SPTopologyWebServiceProxy
Get-SPTrustedIdentityTokenIssuer
Get-SPTrustedRootAuthority
Get-SPTrustedServiceTokenIssuer
Get-SPUsageApplication
Get-SPUsageDefinition
Get-SPUsageService
Get-SPUser
Get-SPUserSolution
Get-SPVisioExternalData
Get-SPVisioPerformance
Get-SPVisioSafeDataProvider
Get-SPVisioServiceApplication
Get-SPVisioServiceApplicationProxy
Get-SPWeb
Get-SPWebAnalyticsServiceApplication
Get-SPWebAnalyticsServiceApplicationProxy
Get-SPWebApplication
Get-SPWebApplicationHttpThrottlingMonitor
Get-SPWebPartPack
Get-SPWebTemplate
Get-SPWorkflowConfig
Grant-SPBusinessDataCatalogMetadataObject
Grant-SPObjectSecurity
Import-SPBusinessDataCatalogModel
Import-SPEnterpriseSearchTopology
Import-SPInfoPathAdministrationFiles
Import-SPMetadataWebServicePartitionData
Import-SPSiteSubscriptionBusinessDataCatalogConfig
Import-SPSiteSubscriptionProfileConfig
Import-SPSiteSubscriptionSettings
Import-SPWeb
Initialize-SPContentDatabase
Initialize-SPResourceSecurity
Initialize-SPStateServiceDatabase
Install-SPApplicationContent
Install-SPDataConnectionFile
Install-SPFeature
Install-SPHelpCollection
Install-SPInfoPathFormTemplate
Install-SPService
Install-SPSolution
Install-SPUserSolution
Install-SPWebPartPack
Install-SPWebTemplate
Merge-SPLogFile
Mount-SPContentDatabase
Mount-SPStateServiceDatabase
Move-SPBlobStorageLocation
Move-SPProfileManagedMetadataProperty
Move-SPSite
Move-SPUser
New-SPAccessServiceApplication
New-SPAlternateURL
New-SPAuthenticationProvider
New-SPBusinessDataCatalogServiceApplication
New-SPBusinessDataCatalogServiceApplicationProxy
New-SPCentralAdministration
New-SPClaimProvider
New-SPClaimsObject
New-SPClaimsPrincipal
New-SPClaimTypeMapping
New-SPConfigurationDatabase
New-SPContentDatabase
New-SPContentDeploymentJob
New-SPContentDeploymentPath
New-SPEnterpriseSearchCrawlComponent
New-SPEnterpriseSearchCrawlContentSource
New-SPEnterpriseSearchCrawlCustomConnector
New-SPEnterpriseSearchCrawlDatabase
New-SPEnterpriseSearchCrawlExtension
New-SPEnterpriseSearchCrawlMapping
New-SPEnterpriseSearchCrawlRule
New-SPEnterpriseSearchCrawlTopology
New-SPEnterpriseSearchExtendedConnectorProperty
New-SPEnterpriseSearchLanguageResourcePhrase
New-SPEnterpriseSearchMetadataCategory
New-SPEnterpriseSearchMetadataCrawledProperty
New-SPEnterpriseSearchMetadataManagedProperty
New-SPEnterpriseSearchMetadataMapping
New-SPEnterpriseSearchPropertyDatabase
New-SPEnterpriseSearchQueryAuthority
New-SPEnterpriseSearchQueryComponent
New-SPEnterpriseSearchQueryDemoted
New-SPEnterpriseSearchQueryKeyword
New-SPEnterpriseSearchQueryScope
New-SPEnterpriseSearchQueryScopeRule
New-SPEnterpriseSearchQueryTopology
New-SPEnterpriseSearchRankingModel
New-SPEnterpriseSearchSecurityTrimmer
New-SPEnterpriseSearchServiceApplication
New-SPEnterpriseSearchServiceApplicationProxy
New-SPEnterpriseSearchSiteHitRule
New-SPExcelBlockedFileType
New-SPExcelDataConnectionLibrary
New-SPExcelDataProvider
New-SPExcelFileLocation
New-SPExcelServiceApplication
New-SPExcelUserDefinedFunction
New-SPIisWebServiceApplicationPool
New-SPLogFile
New-SPManagedAccount
New-SPManagedPath
New-SPMetadataServiceApplication
New-SPMetadataServiceApplicationProxy
New-SPObaSolutionPackage

New-SPPerformancePointServiceApplication
New-SPPerformancePointServiceApplicationProxy
New-SPPerformancePointServiceApplicationTrustedLocation
New-SPProfileServiceApplication
New-SPProfileServiceApplicationProxy
New-SPSecureStoreApplication
New-SPSecureStoreApplicationField
New-SPSecureStoreServiceApplication
New-SPSecureStoreServiceApplicationProxy
New-SPSecureStoreTargetApplication
New-SPServiceApplicationProxyGroup
New-SPSite
New-SPSiteSubscription
New-SPSiteSubscriptionFeaturePack
New-SPStateServiceApplication
New-SPStateServiceApplicationProxy
New-SPStateServiceDatabase
New-SPSubscriptionSettingsServiceApplication
New-SPSubscriptionSettingsServiceApplicationProxy
New-SPTrustedIdentityTokenIssuer
New-SPTrustedRootAuthority
New-SPTrustedServiceTokenIssuer
New-SPUsageApplication
New-SPUsageLogFile
New-SPUser
New-SPVisioSafeDataProvider
New-SPVisioServiceApplication
New-SPVisioServiceApplicationProxy
New-SPWeb
New-SPWebAnalyticsServiceApplication
New-SPWebAnalyticsServiceApplicationProxy
New-SPWebApplication
New-SPWebApplicationExtension
New-SPWordConversionServiceApplication
Ping-SPEnterpriseSearchContentService
Publish-SPServiceApplication
Receive-SPSharedServiceApplicationInfo
Remove-PluggableSecurityTrimmer
Remove-SPAlternateURL
Remove-SPBusinessDataCatalogModel
Remove-SPBusinessDataCatalogSiteSubscriptionConfig
Remove-SPBusinessDataCatalogThrottleConfig
Remove-SPClaimProvider
Remove-SPClaimTypeMapping
Remove-SPConfigurationDatabase
Remove-SPContentDatabase
Remove-SPContentDeploymentJob
Remove-SPContentDeploymentPath
Remove-SPDiagnosticsPerformanceCounter
Remove-SPEnterpriseSearchCrawlComponent
Remove-SPEnterpriseSearchCrawlContentSource
Remove-SPEnterpriseSearchCrawlCustomConnector
Remove-SPEnterpriseSearchCrawlDatabase
Remove-SPEnterpriseSearchCrawlExtension
Remove-SPEnterpriseSearchCrawlMapping
Remove-SPEnterpriseSearchCrawlRule
Remove-SPEnterpriseSearchCrawlTopology
Remove-SPEnterpriseSearchExtendedConnectorProperty
Remove-SPEnterpriseSearchLanguageResourcePhrase
Remove-SPEnterpriseSearchMetadataCategory
Remove-SPEnterpriseSearchMetadataManagedProperty
Remove-SPEnterpriseSearchMetadataMapping
Remove-SPEnterpriseSearchPropertyDatabase
Remove-SPEnterpriseSearchQueryAuthority
Remove-SPEnterpriseSearchQueryComponent
Remove-SPEnterpriseSearchQueryDemoted
Remove-SPEnterpriseSearchQueryKeyword
Remove-SPEnterpriseSearchQueryScope
Remove-SPEnterpriseSearchQueryScopeRule
Remove-SPEnterpriseSearchQueryTopology
Remove-SPEnterpriseSearchRankingModel
Remove-SPEnterpriseSearchSecurityTrimmer
Remove-SPEnterpriseSearchServiceApplication
Remove-SPEnterpriseSearchServiceApplicationProxy
Remove-SPEnterpriseSearchSiteHitRule
Remove-SPExcelBlockedFileType
Remove-SPExcelDataConnectionLibrary
Remove-SPExcelDataProvider
Remove-SPExcelFileLocation
Remove-SPExcelUserDefinedFunction
Remove-SPIisWebServiceApplicationPool
Remove-SPInfoPathUserAgent
Remove-SPManagedAccount
Remove-SPManagedPath
Remove-SPPerformancePointServiceApplication
Remove-SPPerformancePointServiceApplicationProxy
Remove-SPPerformancePointServiceApplicationTrustedLocation
Remove-SPSecureStoreApplication
Remove-SPServiceApplication
Remove-SPServiceApplicationProxy
Remove-SPServiceApplicationProxyGroup
Remove-SPServiceApplicationProxyGroupMember
Remove-SPShellAdmin
Remove-SPSite
Remove-SPSiteSubscription
Remove-SPSiteSubscriptionFeaturePack
Remove-SPSiteSubscriptionFeaturePackMember
Re move-SPSiteSubscriptionMetadataConfig
Remove-SPSiteSubscriptionProfileConfig
Remove-SPSiteSubscriptionSettings
Remove-SPSocialItemByDate
Remove-SPSolution
Remove-SPSolutionDeploymentLock
Remove-SPStateServiceDatabase
Remove-SPTrustedIdentityTokenIssuer
Remove-SPTrustedRootAuthority
Remove-SPTrustedServiceTokenIssuer
Remove-SPUsageApplication
Remove-SPUser
Remove-SPUserSolution
Remove-SPVisioSafeDataProvider
Remove-SPWeb
Remove-SPWebApplication
Remove-SPWordConversionServiceJobHistory
Rename-SPServer
Restart-SPEnterpriseSearchQueryComponent
Restore-SPEnterpriseSearchServiceApplication
Restore-SPFarm
Restore-SPSite
Resume-SPEnterpriseSearchServiceApplication
Resume-SPStateServiceDatabase
Revoke-SPBusinessDataCatalogMetadataObject
Revoke-SPObjectSecurity
Set-SPAccessServiceApplication
Set-SPAlternateURL
Set-SPBrowserCustomerExperienceImprovementProgram
Set-SPBusinessDataCatalogMetadataObject
Set-SPBusinessDataCatalogServiceApplication
Set-SPBusinessDataCatalogThrottleConfig
Set-SPCentralAdministration
Set-SPClaimProvider
Set-SPContentDatabase
Set-SPContentDeploymentJob
Set-SPContentDeploymentPath
Set-SPCustomLayoutsPage
Set-SPDataConnectionFile
Set-SPDesignerSettings
Set-SPDiagnosticConfig
Set-SPDiagnosticsProvider
Set-SPEnterpriseSearchAdministrationComponent
Set-SPEnterpriseSearchCrawlContentSource
Set-SPEnterpriseSearchCrawlDatabase
Set-SPEnterpriseSearchCrawlRule
Set-SPEnterpriseSearchCrawlTopology
Set-SPEnterpriseSearchExtendedConnectorProperty
Set-SPEnterpriseSearchExtendedQueryProperty
Set-SPEnterpriseSearchIndexPartition
Set-SPEnterpriseSearchMetadataCategory
Set-SPEnterpriseSearchMetadataCrawledProperty
Set-SPEnterpriseSearchMetadataManagedProperty
Set-SPEnterpriseSearchMetadataMapping
Set-SPEnterpriseSearchPropertyDatabase
Set-SPEnterpriseSearchQueryAuthority
Set-SPEnterpriseSearchQueryComponent
Set-SPEnterpriseSearchQueryKeyword
Set-SPEnterpriseSearchQueryScope
Set-SPEnterpriseSearchQueryScopeRule
Set-SPEnterpriseSearchQueryTopology
Set-SPEnterpriseSearchRankingModel
Set-SPEnterpriseSearchService
Set-SPEnterpriseSearchServiceApplication
Set-SPEnterpriseSearchServiceApplicationProxy
Set-SPEnterpriseSearchServiceInstance
Set-SPExcelDataConnectionLibrary
Set-SPExcelDataProvider
Set-SPExcelFileLocation
Set-SPExcelServiceApplication
Set-SPExcelUserDefinedFunction
Set-SPFarmConfig
Set-SPIisWebServiceApplicationPool
Set-SPIisWebServiceSettings
Set-SPInfoPathFormsService
Set-SPInfoPathFormTemplate
Set-SPInfoPathWebServiceProxy
Set-SPLogLevel
Set-SPManagedAccount
Set-SPMetadataServiceApplication
Set-SPMetadataServiceApplicationProxy
Set-SPMobileMessagingAccount
Set-SPPassPhrase
Set-SPPerformancePointSecureDataValues
Set-SPPerformancePointServiceApplication
Set-SPProfileServiceApplication
Set-SPProfileServiceApplicationProxy
Set-SPProfileServiceApplicationSecurity
Set-SPSearchService
Set-SPSearchServiceInstance
Set-SPSecureStoreApplication
Set-SPSecureStoreDefaultProvider
Set-SPSecureStoreServiceApplication
Set-SPSecurityTokenService
Set-SPServiceApplication
Set-SPServiceApplicationSecurity
Set-SPServiceEndpoint
Set-SPSessionStateService
Set-SPSite
Set-SPSiteAdministration
Set-SPSiteSubscriptionConfig
Set-SPSiteSubscriptionEdiscoveryHub
Set-SPSiteSubscriptionMetadataConfig
Set-SPSiteSubscriptionProfileConfig
Set-SPStateServiceApplication
Set-SPStateServiceApplicationProxy
Set-SPStateServiceDatabase
Set-SPSubscriptionSettingsServiceApplication
Set-SPTimerJob
Set-SPTopologyWebServiceApplication
Set-SPTopologyWebServiceProxy
Set-SPTrustedIdentityTokenIssuer
Set-SPTrustedRootAuthority
Set-SPTrustedServiceTokenIssuer
Set-SPUsageApplication
Set-SPUsageDefinition
Set-SPUsageService
Set-SPUser
Set-SPVisioExternalData
Set-SPVisioPerformance
Set-SPVisioSafeDataProvider
Set-SPVisioServiceApplication
Set-SPWeb
Set-SPWebAnalyticsServiceApplication
Set-SPWebAnalyticsServiceApplicationProxy
Set-SPWebApplication
Set-SPWebApplicationHttpThrottlingMonitor
Set-SPWebTemplate
Set-SPWordConversionServiceApplication
Set-SPWorkflowConfig
Start-SPAdminJob
Start-SPAssignment
Start-SPContentDeploymentJob
Start-SPEnterpriseSearchQueryAndSiteSettingsServiceInstance
Start-SPEnterpriseSearchServiceInstance
Start-SPInfoPathFormTemplate
Start-SPServiceInstance
Start-SPTimerJob
Stop-SPAssignment
Stop-SPEnterpriseSearchQueryAndSiteSettingsServiceInstance
Stop-SPEnterpriseSearchServiceInstance
Stop-SPInfoPathFormTemplate
Stop-SPServiceInstance
Suspend-SPEnterpriseSearchServiceApplication
Suspend-SPStateServiceDatabase
Test-SPContentDatabase
Test-SPInfoPathFormTemplate
Uninstall-SPDataConnectionFile
Uninstall-SPFeature
Uninstall-SPHelpCollection
Uninstall-SPInfoPathFormTemplate
Uninstall-SPSolution
Uninstall-SPUserSolution
Uninstall-SPWebPartPack
Uninstall-SPWebTemplate
Unpublish-SPServiceApplication
Update-SPFarmEncryptionKey
Update-SPInfoPathAdminFileUrl
Update-SPInfoPathFormTemplate
Update-SPInfoPathUserFileUrl
Update-SPProfilePhotoStore
Update-SPSecureStoreApplicationServerKey
Update-SPSecureStoreCredentialMapping
Update-SPSecureStoreGroupCredentialMapping
Update-SPSecureStoreMasterKey
Update-SPS olution
Update-SPUserSolution
Upgrade-SPContentDatabase
Upgrade-SPEnterpriseSearchServiceApplication
Upgrade-SPSingleSignOnDatabase

If you're going to be working with the SharePoint PowerShell cmdlets then there are two cmdlets that you should learn before any others: Start-SPAssignment and Stop-SPAssignment. If you've used the custom cmdlets that I created for the 2007 product and read my articles around them then you should be familiar with the core issue that I was trying to solve with some of them - the handling of disposable objects. When you use a cmdlet such as Get-SPSite you are returning back a disposable object, an object that implements the IDisposable interface in order to release handles to unmanaged resources which cause memory leaks if not released. I chose to solve the issue by simply not returning back disposable objects and instead using a proxy object. Microsoft chose a different route.

If you look closely at the definitions of the cmdlets from the text file you created above you should notice that every cmdlet has an -AssignmentCollection parameter which takes in an SPAssignmentCollection object type. The purpose of this collection is to store disposable objects so that they can be disposed when your operations complete. You create a new assignment collection by calling the Start-SPAssignment cmdlet. You can then optionally pass the created assignment collection object into your subsequent calls by either using the pipeline or directly setting the parameter (otherwise the global collection will be used). Lets look at the help for the cmdlet to understand this better:

PS C:\> help start-spassignment

NAME
    Start-SPAssignment

SYNOPSIS
    Initiates a new assignment store.


SYNTAX
    Start-SPAssignment [-Global <SwitchParameter>] [<CommonParameters>]


DETAILED DESCRIPTION
    Use this command to properly dispose of objects used with variable assignme
    nts.
    Using SPWeb, SPSite, or SPSiteAdminsitration objects can use large amounts
    of memory and using these objects, or lists of these objects, in PowerShell
     scripts requires proper memory management. By default, all Get commands di
    spose of these objects immediately after the pipeline finishes, but using S
    PAssignment, you can assign the list of objects to a variable and dispose o
    f the objects after they are no longer needed. You can also ensure that the
     objects will remain as long as you need them, even throughout multiple ite
    rations of commands.
    There are three levels of assignment:
    * No assignment - The object is not assigned to a variable and is disposed
      of after each iteration of the command.
    * Simple assignment - All objects are assigned to the global assignment sto
      re. This is done by using the Global parameter. When using this level, al
      l objects are assigned to a global store and are disposed of when the Sto
      p-SPAssignment command is called.
    * Advanced assignment - Objects are assigned to named stores for disposal.
      You can dispose of objects by using the -Identity parameter with the Stop
      -SPAssignment command.
    Regardless of the level used, all objects are disposed of when the PowerShe
    ll runspace is closed.


RELATED LINKS

REMARKS
    To see the examples, type: "get-help Start-SPAssignment -examples".
    For more information, type: "get-help Start-SPAssignment -detailed".
    For technical information, type: "get-help Start-SPAssignment -full".

As you can see from the help text there are three levels of assignment: No assignment (dispose immediately), simple assignment (use a global store), and advanced assignment (use a named store). Let's take a look at the syntax (note that in Beta 1 most of the help files do not match the actual syntax so I rarely rely on the help text to tell me what the cmdlet syntax is - instead I use the Get-Command (gcm) cmdlet):

PS C:\> gcm Start-SPAssignment -syntax
Start-SPAssignment [-Global] [-AssignmentCollection <SPAssignmentCollection>] [
-Verbose] [-Debug] [-ErrorAction <ActionPreference>] [-WarningAction <ActionPre
ference>] [-ErrorVariable <String>] [-WarningVariable <String>] [-OutVariable <
String>] [-OutBuffer <Int32>]

If you specify the -Global switch then you do not need to store the returned object or pass it into your cmdlets - internally this cmdlet stores the object in a static variable which is used by all subsequent calls - this is the "simple assignment" method mentioned in the help text. If you do not specify the -Global switch then you must store the returned object in a variable and pass that variable into all subsequent cmdlet calls that return disposable objects and provide the variable to the Stop-SPAssignment cmdlet with the same variable via the -SemiGlobal parameter (this may change to Identity for the RTM) - this is the "advanced assignment" mentioned in the help text. So what about the "no assignment" option? The "no assignment" option is basically when you do not create an SPAssignmentCollection using the Start-SPAssignment cmdlet which causes cmdlets that return disposable objects to dispose of the object immediately after the call to WriteObject. So as long as the pipeline is active the object remains un-disposed but at the end of the pipeline the object is disposed.

So now we'll look at the syntax for the Stop-SPAssignment cmdlet:

PS C:\> gcm Stop-SPAssignment -syntax
Stop-SPAssignment [[-SemiGlobal] <SPAssignmentCollection>] [-Global] [-Assignme
ntCollection <SPAssignmentCollection>] [-Verbose] [-Debug] [-ErrorAction <Actio
nPreference>] [-WarningAction <ActionPreference>] [-ErrorVariable <String>] [-W
arningVariable <String>] [-OutVariable <String>] [-OutBuffer <Int32>]

As you can see this is pretty straightforward, if you used the -Global switch for the Start-SPAssignment cmdlet then you'll use it here, otherwise you would use the -SemiGlobal parameter and pass the variable you created earlier.

Here's a complete example demonstrating both approaches:

#Use of the Global assignment variable
Start-SPAssignment -Global
$site = Get-SPSite "http://portal"
$site | fl
Stop-SPAssignment -Global

#Use of a semi-global, or named variable
$gc = Start-SPAssignment
$site = $gc | Get-SPSite "http://mysites"
$site | fl
$gc | Stop-SPAssignment

For the second example you can see that I'm passing in the variable using the pipeline rather than setting the parameter directly (for both the Get-SPSite cmdlet and the Stop-SPAssignment cmdlet). I could have easily set the parameter names directly but this just results in less code.

So one thing you should be asking is when do I need to do this - every cmdlet takes an SPAssignmentCollection so does that mean that I always have to deal with this stuff? My simple answer is, no, you don't have to do this all the time, only when you know you are working with disposable objects. The problem is that most people don't know when they are working with disposable objects, and in many cases what disposable objects are. So my first best practice recommendation for SharePoint 2010 will be to always use the simple assignment approach (use the global assignment variable) unless you specifically know to do otherwise. So wrap all your scripts with a call to Start-SPAssignment and Stop-SPAssignment. If you have functions that do not return values then wrap those using the advanced approach as shown below:

function Set-SomethingInteresting([string]$siteUrl)
{
    trap {
        $gc | Stop-SPAssignment
    }

    $gc = Start-SPAssignment
    $site = $gc | Get-SPSite $siteUrl
    Write-Host "Doing something interesting..."
    $gc | Stop-SPAssignment
}
Set-SomethingInteresting "http://mysites"

So as you can see SharePoint 2010 introduces all kinds of really cool stuff - I've literally not even scratched the surface with what you can do with PowerShell and SharePoint 2010, let alone all the cool new features that 2010 introduces. Over the coming weeks and months I hope to provide details on how to do a full scripted install of SharePoint 2010 including detail on how to script out every single service - this will be critical information that every administrator and developer should have as PowerShell is going to be the recommended way to start and configure your services in the new architecture.

Tagged as: PowerShell, SharePoint Foundation 2010, SharePoint Server 2010, STSADM 1 Comment

26Apr/091

Getting an SPWebApplication object using PowerShell

A SharePoint deployment isn’t much of a deployment if there are no web applications. A web application in SharePoint contains one or more content databases, each of which can contain one or more site collections, etc., etc. The SPWebApplication class has tons of methods and properties for directly or indirectly manipulating all things related to web applications - you can do backups, add content databases and site collections, set alert settings, manipulate the web.config file, etc.

There are a couple of different ways in which we can work with the SPWebApplication using PowerShell. The first is to get a specific object using the static Lookup method and the second, which is useful for looping through all web applications, is to use the SPFarm object’s Service property. The first approach is shown below:

[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint")
$webapp = [Microsoft.SharePoint.Administration.SPWebApplication]::Lookup("http://portal")

If you need to loop through all web applications you would write something like the following:

[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint")
$farm = [Microsoft.SharePoint.Administration.SPFarm]::Local
$websvcs = $farm.Services | where -FilterScript {$_.GetType() -eq [Microsoft.SharePoint.Administration.SPWebService]}
$webapps = @()
foreach ($websvc in $websvcs) {
    foreach ($webapp in $websvc.WebApplications) {
        $webapps = $webapps + $webapp
    }
}

The code above isn’t the most intuitive but could be easily wrapped into a function to abstract out the complexity (note that there may be a better way to do the above - I’m still figuring this whole PowerShell thing out:) ). Personally I think the above sucks - it’s not intuitive and it’s difficult to maintain and forces me to do additional filtering if I want a subset of the items returned - thus the motivation behind my Get-SPWebApplication cmdlet. Here’s a couple examples that do the same thing as the above two examples but using my cmdlet instead:

$webapp = Get-SPWebApplication http://portal
$webapps = Get-SPWebApplication *

On the first line I’m retrieving a specific web application and on the second line I’m using a wildcard character to retrieve all web applications in the farm. You could easily utilize the wildcard capabilities to reduce the set of web applications that are returned to those matching a specific pattern. You can also pass in multiple, comma separated URLs such as in the following example:

$webapps = Get-SPWebApplication http://portal,http://mysites

The code for the cmdlet is reasonably simple - most of the work is in dealing with the fact that wildcards are allowed thus making it necessary to loop through all the web applications and the corresponding alternate URL mappings in order to identify the web applications to return:

       1: using System;

       2: using System.Management.Automation;

       3: using Lapointe.SharePoint.PowerShell.Commands.OperationHelpers;

       4: using Lapointe.SharePoint.PowerShell.Commands.Validators;

       5: using Microsoft.SharePoint;

       6: using Microsoft.SharePoint.Administration;

       7:  

       8: namespace Lapointe.SharePoint.PowerShell.Commands.WebApplications

       9: {

    [Cmdlet(VerbsCommon.Get, "SPWebApplication", SupportsShouldProcess=true, DefaultParameterSetName = "Url")]

    public class GetSPWebApplicationCommand : PSCmdletBase

    {

        /// <summary>

        /// Gets or sets the URL.

        /// </summary>

        /// <value>The URL.</value>

        [Parameter(

            ParameterSetName = "Url",

            Mandatory = true,

            Position = 0,

            ValueFromPipeline = true,

            ValueFromPipelineByPropertyName = true,

            HelpMessage = "The URL of the web application to return.  Supports wildcards.")]

        [ValidateNotNullOrEmpty]

        [ValidateUrl(true)]

        public string[] Url { get; set; }

  

  

        /// <summary>

        /// Processes the record.

        /// </summary>

        protected override void ProcessRecordEx()

        {

            foreach (string url in Url)

            {

                if (!WildcardPattern.ContainsWildcardCharacters(url))

                {

                    string webApp = url.TrimEnd('/');

                    WriteObject(SPWebApplication.Lookup(new Uri(webApp)));

                }

                else

                {

                    WildcardPattern wildCard = new WildcardPattern(url.TrimEnd('/'), WildcardOptions.IgnoreCase);

                    if (SPFarm.Local == null)

                        throw new SPException(

                            "The SPFarm object is null.  Make sure you are running as a Farm Administrator.");

  

                    foreach (SPService svc in SPFarm.Local.Services)

                    {

                        if (!(svc is SPWebService))

                            continue;

  

                        foreach (SPWebApplication webApp in ((SPWebService) svc).WebApplications)

                        {

                            foreach (SPAlternateUrl altUrl in webApp.AlternateUrls)

                            {

                                if (wildCard.IsMatch(altUrl.Uri.AbsolutePath.TrimEnd('/')))

                                {

                                    WriteObject(webApp);

                                    break;

                                }

                            }

                        }

                    }

                }

            }

        }

    }

}

Here’s the full help for the cmdlet:

NAME
Get-SPWebApplication

SYNOPSIS
Gets one or more SPWebApplication objects representing a SharePoint 2007 Web Application.

SYNTAX
Get-SPWebApplication [-Url] <String[]> [-WhatIf] [-Confirm] [<CommonParameters>]

DETAILED DESCRIPTION
Pass in a comma separated list of URLs or a string array of URLs to obtain a collection of SPWebAppl
ication objects.

Copyright 2008 Gary Lapointe
> For more information on these PowerShell cmdlets:
> http://blog.falchionconsulting.com/
> Use of these cmdlets is at your own risk.
> Gary Lapointe assumes no liability.

PARAMETERS
-Url <String[]>
Specifies the URL of the web application(s) to retrieve. Wildcards are permitted. If you specify
multiple URLs, use commas to separate the URLs.

Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue, ByPropertyName)
Accept wildcard characters? false

-WhatIf

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-Confirm

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug,
-ErrorAction, -ErrorVariable, and -OutVariable. For more information,
type, "get-help about_commonparameters".

INPUT TYPE
String

RETURN TYPE
Collection of SPWebApplication objects.

NOTES

For more information, type "Get-Help Get-SPWebApplication -detailed". For technical information,
type "Get-Help Get-SPWebApplication -full".

-------------- EXAMPLE 1 --------------

C:\PS>$webapp = get-spwebapplication -url http://portal

This example returns back a single SPWebApplication object.

Copyright © 2007 – 2011 Falchion Consulting, LLC All rights reserved. Absolutely no portions of this websites content in text, images and or digital media format may be reproduced or re-transmitted in any form or media without the express written consent of Gary Lapointe.

SharePoint Automation Gary Lapointe – Founding Partner, Aptillon, Inc.

Exporting and Importing SharePoint 2010 Terms

Resetting SharePoint 2010 Themes – Part 2, the Reset-SPTheme cmdlet

Programmatically Setting SharePoint 2010 Calendar Overlays

Retrieving and Configuring the SharePoint 2010 Developer Dashboard using PowerShell

Creating PowerShell Help Files Dynamically

Announcing My SharePoint 2010 PowerShell Cmdlets & STSADM Commands Now Available for Download

Creating Custom SharePoint 2010 Cmdlets using Visual Studio 2010

SharePoint 2010: PSConfig and PowerShell

SharePoint 2010: STSADM and PowerShell

Getting an SPWebApplication object using PowerShell

Categories

Tags

Archives

Copyright © 2011