54fa658e31
- FullCLR build is disabled in this change. - FullCLR build related functionalities in `build.psm1` and `AppVeyor.psm1` are disabled. They are not cleaned up from `build.psm1` and `AppVeyor.psm1` yet. We need to adopt .NET Core 2.0 to verify the portable module concept, and if that works well, we will remove the Windows PowerShell source code and clean up our scripts. - `dnxcore50` and `portable-net5+win8` target framework monikers are removed. - Dependency on `Microsoft.NETCore.Portable.Compatibility` is removed. It's not necessary, but it may come back when we work on supporting the `portable module`. Its necessity can be reviewed at that time. - I didn't spend the time to try building powershell in Visual Studio 2017. We should have a separate issue for that. It's tracked by #3400 The `TypeCatalogParser` project is replaced by a MSBuild target to gather the dependency information. Due to .NET Core SDK issue [#1021](https://github.com/dotnet/sdk/issues/1021), our meta-package project `Microsoft.PowerShell.SDK` starts to generate an empty assembly during the build and that results in an empty assembly `Microsoft.PowerShell.SDK.dll` appear in `publish` folder and in `.deps.json` file. We cannot simply remove the assembly because it's now part of the TPA, and removing it will cause powershell to crash at startup. We have to live with this empty assembly until that .NET Core SDK issue is fixed. It's tracked by #3401. |
||
---|---|---|
.. | ||
README.md |
Building a C# Cmdlet
This example project demonstrates how to build your own C# cmdlet for PowerShell. When built in the following manner, the resulting DLL can be imported everywhere: Windows PowerShell with Desktop .NET (FullCLR) and PowerShell on Windows, Linux, and macOS with .NET Core (CoreCLR).
Setup
We use the .NET Command-Line Interface (dotnet
) to build the cmdlet library.
Install the dotnet
tool and ensure dotnet --version
is at least 1.0.0-rc2
.
.NET CLI uses a project.json
file for build specifications:
{
"name": "SendGreeting",
"description": "Example C# Cmdlet project",
"version": "1.0.0-*",
"dependencies": {
"Microsoft.PowerShell.5.ReferenceAssemblies": "1.0.0-*"
},
"frameworks": {
"netstandard1.3": {
"imports": [ "net40" ],
"dependencies": {
"Microsoft.NETCore": "5.0.1-*",
"Microsoft.NETCore.Portable.Compatibility": "1.0.1-*"
}
}
}
}
Note that no source files are specified.
.NET CLI automatically will build all .cs
files in the project directory.
Going through this step-by-step:
-
"name": "SendGreeting"
: Name of the assembly to output (otherwise it defaults to the name of the containing folder). -
"version": "1.0.0-*"
: The wild-card can be replaced using the--version-suffix
flag todotnet build
. -
Microsoft.PowerShell.5.ReferenceAssemblies: Contains the SDK reference assemblies for PowerShell version 5. Targets the
net40
framework. -
netstandard1.3: The target framework for .NET Core portable libraries. This is an abstract framework that will work anywhere its dependencies work. Specifically, the 1.3 version allows this assembly to work even on Windows PowerShell with Desktop .NET.
-
"imports": [ "net4" ]
: Since the PowerShell reference assemblies target the oldernet40
framework, weimport
it here to telldotnet restore
that we know we're loading a possibly-incompatible package. -
Microsoft.NETCore: Provides a set of packages that can be used when building portable libraries on .NETCore-based platforms.
-
Microsoft.NETCore.Portable.Compatibility: Enables compatibility with portable libraries targeting previous .NET releases like .NET Framework 4.0. Required to build against the PowerShell reference assemblies package.
Other dependencies can be added as needed; refer to the .NET Core package gallery for package availability, name, and version information.
Because the .NET Core packages are not yet released to NuGet.org,
you also need this NuGet.config
file to setup the .NET Core MyGet feed:
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<packageSources>
<clear />
<add key="CI Builds (dotnet-core)" value="https://www.myget.org/F/dotnet-core/api/v3/index.json" />
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
</packageSources>
</configuration>
Building
.NET Core is a package-based platform, so the correct dependencies first need to be resolved:
dotnet restore
This reads the project.json
and NuGet.config
files and uses NuGet to restore the necessary packages.
The generated project.lock.json
lockfile contains the resolved dependency graph.
Once packages are restored, building is simple:
dotnet build
This will produce the assembly ./bin/Debug/netstandard1.3/SendGreeting.dll
.
This build/restore process should work anywhere .NET Core works, including Windows, Linux, and macOS.
Deployment
In PowerShell, check $env:PSModulePath
and install the new cmdlet in its own
module folder, such as, on Linux,
~/.powershell/Modules/SendGreeting/SendGreeting.dll
.
Then import and use the module:
> Import-Module SendGreeting # Module names are case-sensitive on Linux
> Send-Greeting -Name World
Hello World!
You can also import by the path:
> Import-Module ./bin/Debug/netstandard1.3/SendGreeting.dll