SharePoint Calculator Service Part 7 – Custom Admin Setting PowerShell

In Part 6 of this series, we created a custom setting for our Calculator service application and a web page to manage the setting from the SharePoint Central Administration web site.

In this article, we’ll create the accompanying PowerShell cmdlet so the setting can be scripted.

The proposed syntax of the new cmdlet is:

Set-CalculatorServiceApplication [-Identity] <SPServiceApplicationPipeBind> -Precision <Int32>

Create the Cmdlet

First, we’ll subclass SPCmdlet:

1. [Cmdlet(VerbsCommon.Set, "CalculatorServiceApplication", SupportsShouldProcess = true)]
2. [SPCmdlet(RequireLocalFarmExist = true, RequireUserFarmAdmin = true)]
3. internal sealed class SetCalculatorServiceApplication : SPCmdlet
4. {
5.     [Parameter(Mandatory = true, Position = 0, ValueFromPipeline = true)]
6.     [ValidateNotNull]
7.     public SPServiceApplicationPipeBind Identity
8.     {
9.         get;
10.         set;
11.     }
12.  
13.     [Parameter(Mandatory = true)]
14.     [ValidateRange(1, 20)]
15.     public int Precision
16.     {
17.         get;
18.         set;
19.     }
20.  
21.     protected override void InternalProcessRecord()
22.     {
23.         // Read the service application identity from the pipebind parameter
24.         CalculatorServiceApplication serviceApplication = this.Identity.Read() as CalculatorServiceApplication;
25.  
26.         // Check for a valid service application
27.         if (null == serviceApplication)
28.         {
29.             // Write an error
30.             WriteError(
31.                 new InvalidOperationException("Calculator service application not found."),
32.                 ErrorCategory.InvalidArgument,
33.                 this.Identity);
34.  
35.             // Skip this record
36.             SkipProcessCurrentRecord();
37.         }
38.  
39.         if (ShouldProcess(serviceApplication.Name))
40.         {
41.             // Modify service application settings
42.             serviceApplication.Precision = this.Precision;
43.  
44.             // Persiste the service application object
45.             serviceApplication.Update();
46.  
47.             // Write the object to the pipeline
48.             WriteObject(serviceApplication);
49.         }
50.     }
51. }

This is very similar to the New-CalculatorServiceApplication cmdlet we created in Part 5 of this series, so feel free to review that article.

The interesting code here is the Identity property of type SPServiceApplicationPipeBind (lines 5-11), which allows a instance of our Calculator service application to be passed to our cmdlet. The parameter can either be a Guid identifier (as a string on the command line), a PowerShell variable that references an SPServiceApplication object, or an SPServiceApplication object on the pipeline.

For example, given the following:

PS C:\> Get-SPServiceApplication

DisplayName          TypeName             Id
-----------          --------             --
Security Token Se... Security Token Se... 7d88501a-a3e0-4289-aa96-62048803b1fb
Application Disco... Application Disco... e79b6d9d-f7a0-4ac9-bdda-a9df8dc5e138
WSS_UsageApplication Usage and Health ... 7f75ee92-3930-4496-b1e2-743829f74cf4
My Calculator Ser... Sample.Calculator... 2b07ed87-e9af-40a2-8a59-8d6b746bb19b

We can then update the Precision setting of the above Calculator service application using any of the following commands:

PS C:\> Set-CalculatorServiceApplication 2b07ed87-e9af-40a2-8a59-8d6b746bb19b -Precision 3

PS C:\> Get-SPServiceApplication 2b07ed87-e9af-40a2-8a59-8d6b746bb19b | Set-CalculatorServiceApplication -Precision 3

PS C:\> $app = Get-SPServiceApplication 2b07ed87-e9af-40a2-8a59-8d6b746bb19b
PS C:\> Set-CalculatorServiceApplication $app -Precision 3

Register the Cmdlet

Don’t forget to register the cmdlet (see Part 5 for details on the registration process):

1. <ps:Cmdlet>
2.   <ps:VerbName>Set-CalculatorServiceApplication</ps:VerbName>
3.   <ps:ClassName>Sample.Calculator.Service.PowerShell.SetCalculatorServiceApplication</ps:ClassName>
4.   <ps:HelpFile>Sample.Calculator.Service.PowerShell.dll-help.xml</ps:HelpFile>
5. </ps:Cmdlet>

That’s it!

Administrators can now use our handy Set-CalculatorServiceApplication cmdlet to script the Precision setting.