Developing PowerShell Cmdlets for Nano Server using the PowerShell Core SDK

Looking to develop PowerShell cmdlets for Nano Server? Try out our new PowerShell SDK for Nano on the PowerShell Gallery. Or, if you already have Windows 10 or Windows Management Framework 5.0 installed, simply run:

Install-Module Microsoft.PowerShell.NanoServer.SDK

If you’ve been watching the Server & Cloud Blog, you’ll know that we recently announced the availability of Technical Preview 5 of Windows Server 2016. And if you’ve also been following the Windows Server Blog, you will have noticed that last week marked the latest installment of the “10 Reasons You’ll Love Windows Server” series. Not surprisingly, in Jeffrey’s Top Ten for Windows Server 2016 are PowerShell & DSC and Nano Server.

As customers and partners have gotten a chance to try out the technical previews of Nano Server, we’ve had a number of people ask us how they can write cmdlets for PowerShell on Nano Server. The reason is that PowerShell on Nano Server is a little bit different than PowerShell on Windows 10 or Windows Server 2016 with Desktop Experience.

Starting with version 5.1 (the version included with Windows Server 2016), PowerShell is available in different editions which denote varying feature sets and platform compatibility.

  • Desktop Edition: Built on .NET Framework and provides compatibility with scripts and modules targeting versions of PowerShell running on full footprint editions of Windows such as Server Core and Windows Desktop.
  • Core Edition: Built on .NET Core and provides compatibility with scripts and modules targeting versions of PowerShell running on reduced footprint editions of Windows such as Nano Server and Windows IoT.

Nano Server includes the PowerShell Core edition by default in all Nano Server installations. PowerShell Core functions in the same way as other editions of PowerShell, such as the Desktop edition of Windows PowerShell running on Windows 10 and Windows Server 2016 with Desktop Experience. However, the reduced footprint of Nano Server means that not all PowerShell features from Windows Server 2016 are available in PowerShell Core on Nano Server. The reduced footprint of .NET Core also means that not all existing cmdlets written in C# will run on PowerShell Core.

If you have existing PowerShell cmdlets that you’d like to run on Nano Server, or are developing new ones for that purpose, we’ve published the PowerShell Core SDK module to the PowerShell Gallery as well as a set of useful topics on TechNet to assist with developing cmdlets for Nano Server. You can install the SDK module using PowerShellGet:

Find-Module Microsoft.PowerShell.NanoServer.SDK -Repository PSGallery | Install-Module -Scope CurrentUser

The PowerShell Core SDK module exposes cmdlets to set up the correct .NET Core CLR and PowerShell Core reference assemblies, create a C# project in Visual Studio 2015 targeting those reference assemblies, and set up the remote debugger on a Nano Server machine so that you can debug .NET cmdlets running on Nano Server remotely in Visual Studio 2015.

The PowerShell Core SDK module requires Visual Studio 2015 Update 2. If you don’t have Visual Studio 2015 installed, you can install Visual Studio Community 2015. If you already have Visual Studio 2015, just make sure you have Update 2 or later installed. Also, the SDK module depends on the following feature to be installed in Visual Studio 2015:

Windows and Web Development -> Universal Windows App Development Tools -> Tools (1.3.1) and Windows 10 SDK

We suggest you review your Visual Studio installation before using the SDK module to ensure these prerequisites are satisfied. Make sure you select to install the above feature during the Visual Studio installation, or modify your existing Visual Studio 2015 installation to install it.

After you install the PowerShell Core SDK module, run Get-Command to take a look at the included cmdlets:

  • New-NanoCSharpProject: Creates a new Visual Studio C# project targeting CoreCLR and PowerShell Core included in the Windows Server 2016 Technical Preview 5 release of Nano Server.
  • Install-RemoteDebugger: Installs and configures the Visual Studio remote debugger on a Nano Server machine.
  • Start-RemoteDebugger: Starts the remote debugger on a remote machine running Nano Server.
  • Stop-RemoteDebugger: Stops the remote debugger on a remote machine running Nano Server.
  • Show-SdkSetupReadMe: Opens the SDK root folder in File Explorer and opens the README.txt file for manual setup.

If you are writing new cmdlets, you should start with New-NanoCSharpProject – make sure to run this from the Package Management Console in Visual Studio. If you have existing cmdlets or like to set things up manually on your own, you can skip to the Show-SdkSetupReadMe cmdlet which describes how to set things up yourself.

If you get stuck or need more info, we also have some new topics published to TechNet to give you more details:

Developing PowerShell Cmdlets for Nano Server (START HERE)

PowerShell on Nano Server (including a list of what doesn’t work in TP5)

Getting Started with Nano Server

PowerShell Core SDK for Nano Server

As always, we welcome your feedback on our UserVoice site. Happy coding!

Dan Harman
PM, PowerShell

Update 8/2/2016: Updated the links to the PowerShell Core SDK to point to the latest version