Creating a custom PowerShell command (CmdLet)
In this chapter, previous recipes have tackled accessing custom functions in other SharePoint libraries, and using those functions to perform various operations in our script. It's now time for us to see how we can create our own custom function executing some custom logic. Once the command has been created, it will be accessible from within PowerShell for users to call.
This is particularly handy when you're creating a collection of functions which perform frequent administrative tasks on your server.
Another example where you might want to create your own CmdLet is when you're planning to package those as custom offering for your customers to download and use on their environments.
Getting ready
To create a custom CmdLet, we will be using Visual Studio 2010 Professional. If you're using the virtualized environment we downloaded in the recipe, Setting up your Virtual Machine and running a test script, Visual Studio 2010 Professional will already be installed on your system. Otherwise, ensure you at least have the Professional version installed to continue with this recipe.
How to do it...
Let's take a look at how you can create your own CmdLet using the following steps:
- From within your Visio Studio 2010, click File | New | Project ....
- From Installed Templates select Visual C# | Class Library.
- Leave the default name for the project as ClassLibrary1 and click OK.
- In the Solution Explorer, right-click References | Add Reference to add the following references:
System.Management.Automation, which can be found in a list of assemblies in the .NET
- Also add a reference to Microsoft.SharePoint. The reference can be found in the SharePoint tab as seen here:
- In the Solution Explorer, pick the Class1.cs and rename the file to PowerShell Cmdlet1.cs.
- Replace the contents of the PowerShell Cmdlet1.cs with the following code:
using System.Management.Automation; using Microsoft.SharePoint; namespace PowerShellCmdlet1 { [Cmdlet(VerbsCommon.Set, "WebTitle")] public class PowerShell_Cmdlet1 : Cmdlet { [Parameter()] public string siteUrl; [Parameter()] public string newTitle; protected override void ProcessRecord() { base.ProcessRecord(); using (SPSite site = new SPSite(siteUrl)) { using (SPWeb web = site.OpenWeb()) { web.Title = newTitle; web.Update(); WriteObject("New Title: " + web.Title); } } } } } - Right-click the project name ClassLibrary1 and select Properties.
- From the Properties page, pick the Signing tab and check the check mark titled Sign the assembly.
- From the drop-down entitled Choose a strong name key file, pick New and provide key filename of your choice, which usually is safe to call key.snk.
- Uncheck Protect my file with a password and click OK.
- Your project will now have an assigned key as shown in the following screenshot:
- At this point, your Visual Studio Solution Explorer tree will look as in the following screenshot:
How it works...
At this stage, we have created a new class representing our CmdLet with Visual Studio solution. Visual Studio will produce an assembly file as an output of the solution once built.
Our solution has only one CmdLet functionality which is defined in PowerShell_Cmdlet1. You will notice the [Cmdlet(VerbsCommon.Set, "WebTitle")] part of the code defines the type of the command and the name of it.
Note
If you noticed, all of the PowerShell commands we have called so far have a naming convention of a [Verb]-[Action]. The verb in this case is either Get or Set. In fact, for the full list of available verbs, in your command let code, place the cursor over VerbsCommon.Set and press F12. Visual Studio will display all of the available verbs allowing you to find the one appropriate to the CmdLet you're creating.
The second part of the CmdLet declaration is the action of your function, which can be titled according to your preference.
Tip
The best practice here is to name the command something descriptive to the action executed by it.
The actual functionality of the CmdLet is defined right below the CmdLet declaration, in our case, in the PowerShell_Cmdlet1 class.
We started with a parameter declaration, which is an optional piece but often used. Since most PowerShell commands contain a reusable set of instructions to be performed on the object, it's very common when authoring a new script to accept parameters specifying an object. For PowerShell scripts interacting with SharePoint, this will be a URL of the site or list name, and so on. In our case, we'll capture the URL and the new title of the SharePoint site. The following function will use the parameters we supplied to connect to the URL we have identified, and rename the site title to the one defined.
The logic defined in ProcessRecord of our code handles all of the functionality our CmdLet will execute, and this is where you can code the functionality of your own CmdLet.
Finally, once the logic of our CmdLet has been created, we're prepared to make the functionality available in the PowerShell command line. Details of the CmdLet installation process are described in the Creating a custom PowerShell Snap-In recipe.
Due to the nature of CmdLet, before installing it on the system, we need to make sure the output DLL is signed with a strong name.
The purpose of signing the assembly with the strong name is to ensure the assembly can be dropped into the Global Assembly Cache (GAC), where it can be consumed by the installation process.
See also
Creating a custom PowerShell Snap-In recipe in this chapter.