Using the PowerShell Standard Library

This is the first a set of posts which will help you take advantage of a new Nuget package PowerShellStandard Library 5.1.0. This package allows developers to create modules and applications which host the PowerShell engine which are portable between Windows PowerShell version 5.1 and PowerShell Core 6.0. This means that you can create PowerShell modules and applications which run on Windows, Linux, and Mac with a single binary!

In this post, I’ll walk through the steps for creating a simple binary module which has a single, (very) simple cmdlet. I will also be using the dotnet cli tools for creating everything I need.

First, we need create a project for our new module and create a project template:

PS> New-Item -Type Directory myModule

Directory: C:\Users\James\src\pwsh
Mode LastWriteTime Length Name
---- ------------- ------ ----
d----- 3/26/2018 2:41 PM myModule

PS> Set-Location myModule
PS> dotnet new library
The template "Class library" was created successfully.

Processing post-creation actions...
Running 'dotnet restore' on C:\Users\James\src\pwsh\myModule\myModule.csproj...
 Restoring packages for C:\Users\James\src\pwsh\myModule\myModule.csproj...
 Generating MSBuild file C:\Users\James\src\pwsh\myModule\obj\myModule.csproj.nuget.g.props.
 Generating MSBuild file C:\Users\James\src\pwsh\myModule\obj\myModule.csproj.nuget.g.targets.
 Restore completed in 222.92 ms for C:\Users\James\src\pwsh\myModule\myModule.csproj.

Restore succeeded.

You can see that the dotnet cli has created a source file and .csproj file for my project. Right now they’re quite generic, but we can add a reference to the PowerShellStandard Library very easily:

PS> dotnet add package PowerShellStandard.Library --version 5.1.0-preview-02
 Writing C:\Users\James\AppData\Local\Temp\tmp2C8D.tmp
info : Adding PackageReference for package 'PowerShellStandard.Library' into project 'C:\Users\James\src\pwsh\myModule\myModule.csproj'.
log : Restoring packages for C:\Users\James\src\pwsh\myModule\myModule.csproj...
info : Package 'PowerShellStandard.Library' is compatible with all the specified frameworks in project 'C:\Users\James\src\pwsh\myModule\myModule.csproj'.
info : PackageReference for package 'PowerShellStandard.Library' version '5.1.0-preview-02' added to file 'C:\Users\James\src\pwsh\myModule\myModule.csproj'.
PS> get-childitem

Directory: C:\Users\James\src\pwsh\myModule
Mode LastWriteTime Length Name
---- ------------- ------ ----
d----- 3/26/2018 2:42 PM obj
-a---- 3/26/2018 2:42 PM 85 Class1.cs
-a---- 3/26/2018 2:42 PM 259 myModule.csproj

if we inspect the .csproj file, we can see the reference

PS> Get-Content .\myModule.csproj
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
 <TargetFramework>netstandard2.0</TargetFramework>
 </PropertyGroup>
<ItemGroup>
 <PackageReference Include="PowerShellStandard.Library" Version="5.1.0-preview-02" />
 </ItemGroup>
</Project>

We can now implement our cmdlet in the Class1.cs file

PS> get-content Class1.cs
using System;
using System.Management.Automation;

namespace myModule {
  [Cmdlet("Get","Thing")]
  public class GetThingCommand : PSCmdlet {
    protected override void ProcessRecord() {
      WriteObject("GetThing");
    }
  }
}

We can now build, import the dll (as a module) and run our new cmdlet

PS> dotnet build
Microsoft (R) Build Engine version 15.5.180.51428 for .NET Core
Copyright (C) Microsoft Corporation. All rights reserved.

Restoring packages for C:\Users\James\src\pwsh\myModule\myModule.csproj...
 Restore completed in 164.19 ms for C:\Users\James\src\pwsh\myModule\myModule.csproj.
 myModule -> C:\Users\James\src\pwsh\myModule\bin\Debug\netstandard2.0\myModule.dll

Build succeeded.
 0 Warning(s)
 0 Error(s)

Time Elapsed 00:00:03.16
PS> import-module .\bin\Debug\netstandard2.0\myModule.dll
PS> get-thing
GetThing

This is a completely portable module, I can load this from PowerShell 5.1 and run it without problem. Of course, we’ve barely scratched the surface, but you can see how this can get you started!