As we've seen in the Creating a custom PowerShell command (CmdLet) recipe, the creation of PowerShell CmdLet is a process of defining the functionality you want to expose to the user, and sealing it as a .NET assembly. In this recipe, we'll take a look at how you install your custom CmdLet which directly involves the creation of a PowerShell Snap-In.
We have already used the PowerShell Snap-In when we referenced a set of SharePoint Set earlier in this chapter. In this case, we called the following command:
Add-PSSnapin "Microsoft.SharePoint.Powershell"
In this example, we'll use similar approach to call our custom Snap-In.
As trivial as it sounds, to create a Snap-In, you will need to create another class in the Visual Studio solution you created earlier to define your CmdLet. Your Snap-In solution doesn't need to contain both a Snap-In and a CmdLet. In fact, you can have them created in two separate solutions as long as your Snap-In references the CmdLet. In this example we'll add a Snap-In class to the existing CmdLet solution, which is very common when creating PowerShell CmdLet libraries.
We'll take a look at how you can create your own PowerShell Snap-In.
- Switch to the Visual Studio 2010 solution you used to create a CmdLet earlier.
- From the Solution Explorer, right-click the project name, PowerShellCmdlet1 and select Add | Class ….
- In the Solution Explorer, pick the Class1.cs and rename the file to PowerShell Cmdlet1.cs
- Rename the newly created class to PowerShellCmdlet SnapIn1.cs.
- Open the class file created and replace the contents of the PowerShellCmdlet SnapIn1.cs with the following code:
using System.Collections.ObjectModel; using System.ComponentModel; using System.Management.Automation; using System.Management.Automation.Runspaces; namespace PowerShellCmdlet1 { [RunInstaller(true)] public class PowerShellCmdlet_SnapIn1 : CustomPSSnapIn { private Collection<CmdletConfigurationEntry> _cmdlets; /// <summary> /// The description of powershell snap-in. /// </summary> public override string Description { get { return "A Description of MyCmdlet"; } } /// <summary> /// The name of power shell snap-in /// </summary> public override string Name { get { return "MyCmdlet"; } } /// <summary> /// The name of the vendor /// </summary> public override string Vendor { get { return ""; } } public override Collection<CmdletConfigurationEntry> Cmdlets { get PowerShell Snap-Increating, steps{ if (null == _cmdlets) { _cmdlets = new Collection<Cmdlet ConfigurationEntry>(); _cmdlets.Add(new CmdletConfigurationEntry ("Set-WebTitle", typeof(PowerShell_Cmdlet1), "Set-WebTitle.dll-Help.xml")); } return _cmdlets; } } } } - Right-click the project name PowerShellCmdlet1 and select Build.
- Right-click the project name PowerShellCmdlet1 and select Open Folder in Windows Explorer.
- In the folder opened, open the
binDebugfolder and locate thePowerShellCmdlet1.dll. - Click Start | Run on your development environment and open the Global Assembly Cache by typing
c:windowsassembly. - Drag-and-drop the
PowerShellCmdlet1.dllto theassemblyfolder. - Open a PowerShell command line from Start | All Programs | Accessories | Windows PowerShell | Windows PowerShell.
- Type in the following command to install our newly added Snap-In assembly. Ensure the path to your assembly is correct. In this example, our path is
C:UsersAdministratorDocumentsvisual studio 2010projectsPowerShellCmdlet1PowerShellCmdlet1inDebug:PS> set-alias installutil $env:windirMicrosoft.NETFrameworkv2.0.50727installutil PS> cd "C:UsersAdministratorDocumentsvisual studio 2010projectsPowerShellCmdlet1PowerShellCmdlet1inDebug" S> installutil PowerShellCmdlet1.dll
- Now that our Snap-In has been installed, let's open our SharePoint test intranet site, http://intranet.contoso.com. Take note of the current site title.
- Switch back to the PowerShell command-line window and register the new Snap-In:
PS> Add-PSSnapin "MyCmdlet" - Let's change the title of the site by executing our custom CmdLet:
PS> Set-WebTitle -siteUrl "http://intranet.contoso.com" -newTitle "Test Title" - Switch back to http://intranet.contoso.com and take note of the changed title.
Since we have already created the actual CmdLet, we reused the same Visual Studio solution to add a Snap-In class. The Snap-In class will perform the role of installer. As you can see, the contents of the class declare the name and description on the CmdLet as well as a reference to CmdLet class. This information will further be used to identify your custom CmdLet.
Once the solution has been built and the solution library has been generated, we copied the library to GAC. We used InstallUtil to install and uninstall server resources by executing the installer components in our CmdLet library. By executing the InstallUtil command we will actually make the Snap-In available in the PowerShell command line.
Once installed, we can add the Snap-In and execute our custom CmdLet.
As you will notice, due to the fact that our custom Snap-In library will be placed into the GAC, the custom code executed will have access to most of the server resources. Because of the level of access, when downloading custom Snap-Ins ensure they come from a trusted source.
Let's take a look at how you can uninstall your Snap-In from the system as well as how Visual Studio templates can help you with Snap-In authoring.
Previously, we looked at how you can install the Snap-In so it's available to be called from the command line. You can also uninstall the Snap-In by using the uninstall key of the InstallUtil command. Here is a sample uninstall syntax for our Snap-In:
PS> installutil /u PowerShellCmdlet1.dll
It's quite common to need to uninstall the Snap-In. One common scenario includes the CmdLet authoring process. As you author your CmdLet and discover problems with it or would like to add more functionality, to have the new version available you would need to re-install the Snap-in on the environment.
In this example, we looked at how you can install a custom PowerShell Snap-In by adding code to a Visual Studio solution. Since this is a fairly common task, there are a few templates available online which you're welcome to use to create core CmdLet and Snap-In code automatically. The core functionality will be your starting point which you can add your customizations to.
One of the templates you can try is available at CodePlex. The project is called PowerShell Visual Studio 2008 templates and recently was hosted at this URL: http://psvs2008.codeplex.com.
Although the version of this package is specifically designed for Visual Studio 2008, it is also compatible with Visual Studio 2010.
Once you download the package, open it on the development environment where you have Visual Studio installed, and install all of the suggested components, as seen in the following screenshot:
Once installed, to add a new instance of a template for CmdLet and Snap-In, simply right-click on the project name in Solution Explorer, and select Add | New Item.
From here, you need to pick the appropriate Snap-In or CmdLet template and click Add to create an initial version of the file, as seen in the following screenshot:.
Whether you will be using components from the preceding template, or creating your own CmdLet classes, search MSDN with the keyword Cmdlet Development Guidelines for some handy tips and details on authoring your CmdLets.