Skip to content

Update README.md #1402

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sergei (vors) merged 1 commit into from
Jul 20, 2016
Merged

Update README.md #1402

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 26 additions & 36 deletions docs/cmdlet-example/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,15 @@
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 Open
PowerShell on Windows, Linux, and OS X with .NET Core (CoreCLR).
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 OS X with .NET Core (CoreCLR).

Setup
-----

We use the [.NET Command Line Interface][dotnet-cli] (`dotnet`) to build the
cmdlet library. Install the `dotnet` tool and ensure `dotnet --version` is at
least `1.0.0-rc2`.
We use the [.NET Command-Line Interface][dotnet-cli] (`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:

Expand All @@ -37,42 +35,37 @@ least `1.0.0-rc2`.
}
```

Note that no source files are specified. .NET CLI automatically will build all
`.cs` files in the project directory.
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).
- `"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 to `dotnet build`.
- `"version": "1.0.0-*"`: The wild-card can be replaced using the `--version-suffix` flag to `dotnet build`.

- [Microsoft.PowerShell.5.ReferenceAssemblies][powershell]: Contains the SDK
reference assemblies for PowerShell version 5. Targets the `net40` framework.
- [Microsoft.PowerShell.5.ReferenceAssemblies][powershell]: 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.
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
older `net40` framework, we `import` it here to tell `dotnet restore` that we
know we're loading a possibly-incompatible package.
- `"imports": [ "net4" ]`: Since the PowerShell reference assemblies target the older `net40` framework,
we `import` it here to tell `dotnet restore` that we know we're loading a possibly-incompatible package.

- [Microsoft.NETCore][netcore]: Provides a set of packages that can be used when
building portable libraries on .NETCore based platforms.
- [Microsoft.NETCore][netcore]: Provides a set of packages that can be used when building portable
libraries on .NETCore-based platforms.

- [Microsoft.NETCore.Portable.Compatibility][portable]: Enables compatibility
with portable libraries targeting previous .NET releases like .NET Framework
4.0. Required to build against the PowerShell reference assemblies package.
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][myget] for package availability, name, and version
information.
Other dependencies can be added as needed;
refer to the [.NET Core package gallery][myget] 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][myget]:
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][myget]:

```xml
<?xml version="1.0" encoding="utf-8"?>
Expand All @@ -95,16 +88,14 @@ this `NuGet.config` file to setup the [.NET Core MyGet feed][myget]:
Building
--------

.NET Core is a package-based platform, so the correct dependencies first need to
be resolved:
.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.
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:

Expand All @@ -114,8 +105,7 @@ 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 OS X.
This build/restore process should work anywhere .NET Core works, including Windows, Linux, and OS X.

Deployment
----------
Expand Down