One of the first PowerShell cmdlets I built, Get-SPSite, addresses some common issues found with working with SPSite objects. I struggled with how I could provide a means to quickly and easily get SPSite objects while at the same time helping administrators so they don’t have to worry (as much) about object disposal. For those that aren’t familiar with the SPSite object (Microsoft.SharePoint.SPSite), it’s the equivalent programmatic element for working with site collections.
What I eventually ended up creating (thanks to some good advice from Harley Green) was a simple wrapper object which encapsulates most of the key properties of the SPSite object thus allowing basic reporting and decision making processing without the need to worry about disposing of the object. Consider the following code snippet:
The above code results in a memory leak. If you don’t re-loop through each SPSite object in the collection and dispose of the object by calling the “Dispose()” method you will end up with unmanaged resources left in memory that could eventually cause issues if you do a lot of processing like this (eventually the GC will dispose of the objects but that could take quite some time).
Another option would be to use a different approach to get all the SPSite objects within a web application, an approach that can be used for more dynamic querying of objects and returns back an object that would not require disposal – an SPSiteInfo object. Here’s an example of how you could do something similar to the above using my Get-SPSite cmdlet:
The one obvious downside of this approach is that the wildcard means that I have to inspect every single site collection within the farm to figure out where there are matches so if you’re looking for performance this definitely isn’t the best approach. Typically though, we’re more concerned about flexibility and ease of use rather than performance when performing the simple administrative tasks that we’d be looking to perform using PowerShell.
What I like about the approach I put together is that I can now do filtered queries without having to worry about whether or not I disposed of the objects. Here’s an example of how to find all the site collections within the farm where the storage size is greater than 80% of the quota:
In the above I can simply call my Get-SPSite cmdlet, filter out all items where the current storage is less than 0.8 of the maximum level if set (StorageMaximumLevel is not 0), and then display the URL and the current size, in megabytes, of the the remaining site collections.
It’s important to remember that the SPSiteInfo object is meant to be read-only as most of the properties are just copies of the variables but there are some exceptions such as the SPRecycleBinItemCollection object returned by the RecycleBin property or the SPFeatureCollection object returned by the Features property. In general, if you have to call the Update() method of the SPSite object to save your changes then you have to use the actual SPSite object, otherwise you can work directly with the SPSiteInfo object and forego the need to instantiate and dispose of the SPSite object.
Okay, so working with properties is pretty easy and we can do some nice reports using them and even access the web application using the WebApplication property or the webs using the AllWebs collection property (all without having to dispose any of the returned objects – the AllWebs property returns a collection of SPWebInfo objects) but what about when you do need to access the actual SPSite object? There are two approaches for this: the first is to use the SPBase property which will create a new SPSite instance and store that instance as a private member variable for future access to the property thus avoiding the overhead of creating another instance on subsequent calls; the second is to use the GetSPObject() method which creates a new instance of the SPSite object but does not store a copy so it’s a nice easy way to get an entirely new instance of the actual SPSite object (useful for when you’ve made a change which requires a reload due to caching). In both cases you are responsible for disposing of the returned object.
The following code snippet shows the SPSiteInfo class:
The following is the code of the core Get-SPSite cmdlet:
The following is the full help for the cmdlet.
PS C:\> get-help get-spsite -full NAME Get-SPSite SYNOPSIS Gets one or more SPSiteInfo objects representing a SharePoint 2007 Site Collection. SYNTAX Get-SPSite [-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 SPSiteInfo objects. The se objects do not need to be disposed. The SPSiteInfo object that is returned contains almost all of the same properties of the SPSite object but does not require disposal and should be generally considered read-only. You can get to the actual SPSite object by using t he SPBase property or the GetSPObject() method. The SPBase property results in a copy of the SPSite object being p ersisted in the SPSiteInfo object for faster access on future calls. Always remember to dispose of the SPSite obje ct if used. Some collection properties may be directly updated without the need to access the SPSite object. Copyright 2008 Gary Lapointe > For more information on these PowerShell cmdlets: > http://stsadm.blogspot.com/ > Use of these cmdlets is at your own risk. > Gary Lapointe assumes no liability. PARAMETERS -Url <String> Specifies the URL of the site collection(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 SPSiteInfo objects. NOTES For more information, type "Get-Help Get-SPSite -detailed". For technical information, type "Get-Help Get-SP Site -full". -------------- Example 1 -------------- C:\PS>get-spsite -url http://portal This example returns back a single SPSiteInfo object. -------------- EXAMPLE 2 -------------- C:\PS>$sites = get-spsite -url http://mysites/* This example returns back all My Site site collections under the http://mysites web application. RELATED LINKS http://stsadm.blogspot.com
Note that if you receive an exception during the execution of this cmdlet simply pass in the “-debug” parameter in order to display the full stack trace which you can use to either debug yourself or report back to here to help me improve the code.
And finally – if you’ve used this cmdlet (or any others that I’ve provided) to do something cool please post your code here as a comment so that others may benefit and possibly give back some feedback that you yourself could use.