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:
![[Microsoft.SharePoint.Administration.SPWebService]::ContentService.DeveloperDashboardSettings](/images/2011/04/image.png)
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:
1$dds = [Microsoft.SharePoint.Administration.SPWebService]::ContentService.DeveloperDashboardSettings
2$dds.DisplayLevel = "On"
3$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:
1<?xml version="1.0" encoding="utf-8"?>
2<Types>
3 <Type>
4 <Name>Microsoft.SharePoint.Administration.SPFarm</Name>
5 <Members>
6 <ScriptProperty>
7 <Name>DeveloperDashboard</Name>
8 <GetScriptBlock>[Microsoft.SharePoint.Administration.SPWebService]::ContentService.DeveloperDashboardSettings</GetScriptBlock>
9 </ScriptProperty>
10 </Members>
11 </Type>
12</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:
1$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.
Copyright 2010 Falchion Consulting, LLC
> For more information on this cmdlet and others:
> http://www.falchionconsulting.com/
> Use of this cmdlet is at your own risk.
> Gary Lapointe assumes no liability.
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.
RELATED LINKS
Set-SPDeveloperDashboard
So obviously the cmdlet is pretty simple as there aren’t any parameters beyond the standard parameters (remember, the -AssignmentCollection parameter is included as part of the cmdlet base class but as the SPDeveloperDashboardSettings object is not disposable there is no reason to use it.
The code for this cmdlet is actually shorter than the help for it:
1using System.Collections.Generic;
2using System.Management.Automation;
3using Lapointe.PowerShell.MamlGenerator.Attributes;
4using Microsoft.SharePoint.PowerShell;
5using Microsoft.SharePoint.Administration;
6
7namespace Lapointe.SharePoint2010.Automation.Cmdlets.Farm
8{
9 [Cmdlet(VerbsCommon.Get, "SPDeveloperDashboard", SupportsShouldProcess = false), SPCmdlet(RequireLocalFarmExist = true, RequireUserFarmAdmin = false)]
10 [CmdletDescription("Retrieves the Developer Dashboard Settings object.")]
11 [RelatedCmdlets(typeof(SPCmdletSetDeveloperDashboard))]
12 [Example(Code = "PS C:\\> $dash = Get-SPDeveloperDashboard", Remarks = "This example returns back the developer dashboard settings object.")]
13 public class SPCmdletGetDeveloperDashboard : SPGetCmdletBaseCustom<SPDeveloperDashboardSettings>
14 {
15 protected override IEnumerable<SPDeveloperDashboardSettings> RetrieveDataObjects()
16 {
17 WriteObject(SPWebService.ContentService.DeveloperDashboardSettings);
18
19 return null;
20 }
21 }
22}
The following figure shows how you can call the cmdlet:
Note that I’ve also added a new view for the SPDeveloperDashboardSettings object type (as shown in the first example – to see all the properties use the Select-Object cmdlet as shown in the second example). The custom views are added just like the custom type extensions – for views, however, you create another XML file which you can see in my source code under the {Project Root}\PowerShell\Format folder. The following XML snippet illustrates the relevant portion of that file:
1<?xml version="1.0" encoding="utf-8"?>
2<Configuration>
3 <ViewDefinitions>
4 <View>
5 <Name>SPDeveloperDashboardSettings</Name>
6 <ViewSelectedBy>
7 <TypeName>Microsoft.SharePoint.Administration.SPDeveloperDashboardSettings</TypeName>
8 </ViewSelectedBy>
9 <TableControl>
10 <TableHeaders>
11 <TableColumnHeader>
12 <Label>Display Level</Label>
13 <Width>14</Width>
14 <Alignment>left</Alignment>
15 </TableColumnHeader>
16 <TableColumnHeader>
17 <Label>Trace Enabled</Label>
18 <Width>14</Width>
19 <Alignment>left</Alignment>
20 </TableColumnHeader>
21 <TableColumnHeader>
22 <Label>Required Permissions</Label>
23 <Alignment>left</Alignment>
24 </TableColumnHeader>
25 </TableHeaders>
26 <TableRowEntries>
27 <TableRowEntry>
28 <TableColumnItems>
29 <TableColumnItem>
30 <PropertyName>DisplayLevel</PropertyName>
31 </TableColumnItem>
32 <TableColumnItem>
33 <PropertyName>TraceEnabled</PropertyName>
34 </TableColumnItem>
35 <TableColumnItem>
36 <PropertyName>RequiredPermissions</PropertyName>
37 </TableColumnItem>
38 </TableColumnItems>
39 </TableRowEntry>
40 </TableRowEntries>
41 </TableControl>
42 </View>
43 </ViewDefinitions>
44</Configuration>
Okay, so we’ve made it easier to retrieve the developer dashboard, now I want to change the values in one step (because retrieving the object, changing the value, and calling Update() is just too much work). To do this I created the Set-SPDeveloperDashboard cmdlet. This cmdlet is a bit more complex in that I’ve exposed all the relevant properties of the SPDeveloperDashboardSettings object with an equivalent parameter. Here’s the full help for the cmdlet:
PS C:\> help Set-SPDeveloperDashboard -Full
NAME
Set-SPDeveloperDashboard
SYNOPSIS
Sets the Developer Dashboard Settings.
SYNTAX
Set-SPDeveloperDashboard [-AutoLaunchEnabled <Boolean>] [-DisplayLevel <Off | OnDemand | On>] [-MaximumCriticalEventsToTrack <Int32>]
[-MaximumSQLQueriesToTrack <Int32>] [-RequiredPermissions <EmptyMask | ViewListItems | AddListItems | EditListItems | DeleteListItems |
ApproveItems | OpenItems | ViewVersions | DeleteVersions | CancelCheckout | ManagePersonalViews | ManageLists | ViewFormPages | Open |
ViewPages | AddAndCustomizePages | ApplyThemeAndBorder | ApplyStyleSheets | ViewUsageData | CreateSSCSite | ManageSubwebs | CreateGroups
| ManagePermissions | BrowseDirectories | BrowseUserInfo | AddDelPrivateWebParts | UpdatePersonalWebParts | ManageWeb |
UseClientIntegration | UseRemoteAPIs | ManageAlerts | CreateAlerts | EditMyUserInfo | EnumeratePermissions | FullMask>]
[-TraceEnabled <Boolean>] [-AdditionalEventsToTrack <String[]>] [-AssignmentCollection <SPAssignmentCollection>] [<CommonParameters>]
DESCRIPTION
Sets the Developer Dashboard Settings.
Copyright 2010 Falchion Consulting, LLC
> For more information on this cmdlet and others:
> http://www.falchionconsulting.com/
> Use of this cmdlet is at your own risk.
> Gary Lapointe assumes no liability.
PARAMETERS
-AutoLaunchEnabled [<Boolean>]
Indicates whether the developer dashboard can be auto launched.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-DisplayLevel [<SPDeveloperDashboardLevel>]
Indicates whether the developer dashboard is set to Off, On, or On Demand.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-MaximumCriticalEventsToTrack [<Int32>]
The maximum number of critical events and asserts that will be recorded in a single transaction (i.e. one request or timer job).
If a single transaction has more than this number of asserts the remainder will be ignored. This can be set to 0 to disable
assert tracking.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-MaximumSQLQueriesToTrack [<Int32>]
The maximum number of SQL queries that will be recorded in a single transaction (i.e. one request or timer job). If a single
transaction executes more than this number of requests the query will be counted but the query call stack and text will not be kept.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-RequiredPermissions [<SPBasePermissions>]
A permission mask defining the permissions required to see the developer dashboard. This defaults to SPBasePermissions.AddAndCustomizePages.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-TraceEnabled [<Boolean>]
Whether a link to display full verbose trace will be available at the bottom of the page when the developer dashboard is launched or not.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-AdditionalEventsToTrack [<String[]>]
A list of URL tags to track in addition to events with severity above High.
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 Set-SPDeveloperDashboard -detailed". For technical information,
type "Get-Help Set-SPDeveloperDashboard -full".
------------------EXAMPLE 1-----------------------
PS C:\> Set-SPDeveloperDashboard -RequiredPermissions "ManageWeb,ManageSubwebs"
This example sets the required permissions to view the developer dashboard.
------------------EXAMPLE 2-----------------------
PS C:\> Set-SPDeveloperDashboard -DisplayLevel OnDemand -TraceEnabled $true
This example enables the developer dashboard.
RELATED LINKS
Get-SPDeveloperDashboard
The code for this cmdlet is obviously going to be slightly longer than the Get-SPDeveloperDashboard cmdlet, but again, it’s very simple as most of the code is just for defining the parameters:
1using System.Collections.Generic;
2using System.Management.Automation;
3using Lapointe.PowerShell.MamlGenerator.Attributes;
4using Microsoft.SharePoint;
5using Microsoft.SharePoint.PowerShell;
6using Microsoft.SharePoint.Administration;
7
8namespace Lapointe.SharePoint2010.Automation.Cmdlets.Farm
9{
10 [Cmdlet(VerbsCommon.Set, "SPDeveloperDashboard", SupportsShouldProcess = false),
11 SPCmdlet(RequireLocalFarmExist = true, RequireUserFarmAdmin = false)]
12 [CmdletDescription("Sets the Developer Dashboard Settings.")]
13 [RelatedCmdlets(typeof(SPCmdletGetDeveloperDashboard))]
14 [Example(Code = "PS C:\\> Set-SPDeveloperDashboard -DisplayLevel OnDemand -TraceEnabled $true",
15 Remarks = "This example enables the developer dashboard.")]
16 [Example(Code = "PS C:\\> Set-SPDeveloperDashboard -RequiredPermissions \"ManageWeb,ManageSubwebs\"",
17 Remarks = "This example sets the required permissions to view the developer dashboard.")]
18 public class SPCmdletSetDeveloperDashboard : SPSetCmdletBaseCustom<SPDeveloperDashboardSettings>
19 {
20 public SPCmdletSetDeveloperDashboard()
21 {
22 SPDeveloperDashboardSettings dash = SPWebService.ContentService.DeveloperDashboardSettings;
23 AutoLaunchEnabled = dash.AutoLaunchEnabled;
24 DisplayLevel = dash.DisplayLevel;
25 MaximumCriticalEventsToTrack = dash.MaximumCriticalEventsToTrack;
26 MaximumSQLQueriesToTrack = dash.MaximumSQLQueriesToTrack;
27 RequiredPermissions = dash.RequiredPermissions;
28 TraceEnabled = dash.TraceEnabled;
29 AdditionalEventsToTrack = ((List<string>) dash.AdditionalEventsToTrack).ToArray();
30 }
31
32 [Parameter(HelpMessage = "Indicates whether the developer dashboard can be auto launched.")]
33 public bool AutoLaunchEnabled { get; set; }
34
35 [Parameter(HelpMessage = "Indicates whether the developer dashboard is set to Off, On, or On Demand.")]
36 public SPDeveloperDashboardLevel DisplayLevel { get; set; }
37
38 [Parameter(HelpMessage = "The maximum number of critical events and asserts that will be recorded in a single transaction (i.e. one request or timer job). If a single transaction has more than this number of asserts the remainder will be ignored. This can be set to 0 to disable assert tracking.")]
39 public int MaximumCriticalEventsToTrack { get; set; }
40
41 [Parameter(HelpMessage = "The maximum number of SQL queries that will be recorded in a single transaction (i.e. one request or timer job). If a single transaction executes more than this number of requests the query will be counted but the query call stack and text will not be kept. ")]
42 public int MaximumSQLQueriesToTrack { get; set; }
43
44 [Parameter(HelpMessage = "A permission mask defining the permissions required to see the developer dashboard. This defaults to SPBasePermissions.AddAndCustomizePages.")]
45 public SPBasePermissions RequiredPermissions { get; set; }
46
47 [Parameter(HelpMessage = "Whether a link to display full verbose trace will be available at the bottom of the page when the developer dashboard is launched or not.")]
48 public bool TraceEnabled { get; set; }
49
50 [Parameter(HelpMessage = "A list of URL tags to track in addition to events with severity above High. ")]
51 public string[] AdditionalEventsToTrack { get; set; }
52
53 protected override void UpdateDataObject()
54 {
55 SPDeveloperDashboardSettings dash = SPWebService.ContentService.DeveloperDashboardSettings;
56
57 dash.AutoLaunchEnabled = AutoLaunchEnabled;
58 dash.DisplayLevel = DisplayLevel;
59 dash.MaximumCriticalEventsToTrack = MaximumCriticalEventsToTrack;
60 dash.MaximumSQLQueriesToTrack = MaximumSQLQueriesToTrack;
61 dash.RequiredPermissions = RequiredPermissions;
62 dash.TraceEnabled = TraceEnabled;
63 dash.AdditionalEventsToTrack.Clear();
64 ((List<string>)dash.AdditionalEventsToTrack).AddRange(AdditionalEventsToTrack);
65
66 dash.Update();
67 }
68 }
69}
The following figure shows how you can call the cmdlet:
So that wraps up my first (very long overdue) post for my 2010 cmdlets – look for more posts coming soon as well as an update to my index page listing all the available cmdlets.
-Gary