Nano Server 用の PowerShell コマンドレットを開発するDeveloping PowerShell Cmdlets for Nano Server

適用先:Windows Server 2016Applies To: Windows Server 2016

重要

Windows Server バージョン 1709 以降では、Nano Server はコンテナーの基本 OS イメージとしてのみ提供されます。Starting in Windows Server, version 1709, Nano Server will be available only as a container base OS image. その意味については、Nano Server に加えられる変更に関する記事をご覧ください。Check out Changes to Nano Server to learn what this means.

概要Overview

すべての Nano Server インストールには PowerShell Core が既定で含まれます。Nano Server includes PowerShell Core by default in all Nano Server installations. PowerShell Core は、.NET Core に基づいて作成された PowerShell のフットプリントが小さいエディションであり、Windows のフットプリントが小さいエディション (Nano Server、Windows IoT Core など) で動作します。PowerShell Core is a reduced-footprint edition of PowerShell that is built on .NET Core and runs on reduced-footprint editions of Windows, such as Nano Server and Windows IoT Core. PowerShell Core は、PowerShell の他のエディション (Windows Server 2016 で実行される Windows PowerShell など) と同じように動作します。PowerShell Core functions in the same way as other editions of PowerShell, such as Windows PowerShell running on Windows Server 2016. ただし、Nano Server のフットプリントが小さいため、Nano Server 上の PowerShell Core では、Windows Server 2016 の PowerShell 機能のうち、使用できない機能があります。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.

このトピックでは、Nano Server 上で実行したい既存の PowerShell コマンドレットがある場合や、Nano Server 上で実行する新しい PowerShell コマンドレットを開発する場合に役立つヒントと推奨事項を紹介します。If you have existing PowerShell cmdlets that you'd like to run on Nano Server, or are developing new ones for that purpose, this topic includes tips and suggestions that should help make that easier.

PowerShell のエディションPowerShell editions

PowerShell は、バージョン 5.1 以降、機能セットとプラットフォーム互換性が異なるさまざまなエディションが提供されるようになりました。Starting with version 5.1, PowerShell is available in different editions which denote varying feature sets and platform compatibility.

  • Desktop Edition: .NET Framework 上に構築され、Windows の完全フットプリント エディション (Server Core、Windows Desktop など) で実行される PowerShell のバージョンをターゲットとするスクリプトおよびモジュールと互換性があります。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: .NET Core 上に構築され、Windows のフットプリントが小さいエディション (Nano Server、Windows IoT など) で実行される PowerShell のバージョンをターゲットとするスクリプトおよびモジュールと互換性があります。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.

PowerShell の実行中のエディションは、$PSVersionTable の PSEdition プロパティに表示されます。The running edition of PowerShell is shown in the PSEdition property of $PSVersionTable.

$PSVersionTable

Name                           Value
----                           -----
PSVersion                      5.1.14300.1000
PSEdition                      Desktop
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0...}
CLRVersion                     4.0.30319.42000
BuildVersion                   10.0.14300.1000
WSManStackVersion              3.0
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1

モジュールの作成者は、CompatiblePSEditions モジュール マニフェスト キーを使用して、モジュールが 1 つまたは複数の PowerShell エディションと互換性があることを宣言できます。Module authors can declare their modules to be compatible with one or more PowerShell editions using the CompatiblePSEditions module manifest key. このキーは、PowerShell 5.1 以降でのみサポートされます。This key is only supported on PowerShell 5.1 or later.

New-ModuleManifest -Path .\TestModuleWithEdition.psd1 -CompatiblePSEditions Desktop,Core -PowerShellVersion 5.1
$moduleInfo = Test-ModuleManifest -Path \TestModuleWithEdition.psd1
$moduleInfo.CompatiblePSEditions
Desktop
Core

$moduleInfo | Get-Member CompatiblePSEditions

   TypeName: System.Management.Automation.PSModuleInfo

Name                 MemberType Definition
----                 ---------- ----------
CompatiblePSEditions Property   System.Collections.Generic.IEnumerable[string] CompatiblePSEditions {get;}

利用可能なモジュールの一覧を取得するとき、PowerShell のエディションで一覧にフィルターを適用できます。When getting a list of available modules, you can filter the list by PowerShell edition.

Get-Module -ListAvailable | ? CompatiblePSEditions -Contains Desktop

    Directory: C:\Program Files\WindowsPowerShell\Modules


ModuleType Version    Name                                ExportedCommands
---------- -------    ----                                ----------------
Manifest   1.0        ModuleWithPSEditions

Get-Module -ListAvailable | ? CompatiblePSEditions -Contains Core | % CompatiblePSEditions
Desktop
Core

スクリプトの作成者は、#requires ステートメントに PSEdition パラメーターを使用することで、PowerShell の互換性のあるエディション以外でスクリプトが実行されるのを防止できます。Script authors can prevent a script from executing unless it is run on a compatible edition of PowerShell using the PSEdition parameter on a #requires statement.

Set-Content C:\script.ps1 -Value #requires -PSEdition Core
Get-Process -Name PowerShell
Get-Content C:\script.ps1
#requires -PSEdition Core
Get-Process -Name PowerShell

C:\script.ps1
C:\script.ps1 : The script 'script.ps1' cannot be run because it contained a #requires statement for PowerShell editions 'Core'. The edition of PowerShell that is required by the script does not match the currently running PowerShell Desktop edition.
At line:1 char:1
+ C:\script.ps1
+ ~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (script.ps1:String) [], RuntimeException
    + FullyQualifiedErrorId : ScriptRequiresUnmatchedPSEdition

Nano Server のインストールInstalling Nano Server

仮想マシンまたは物理マシンに Nano Server をインストールするためのクイックスタートおよび詳細な手順については、このトピックの親トピックである「Nano Server のインストール」を参照してください。Quick-start and detailed steps for installing Nano Server on virtual or physical machines are provided in Install Nano Server, which is the parent topic for this one.

注意

Nano Server 上で開発を行うには、New-NanoServerImage の -Development パラメーターを使用して Nano Server をインストールすると便利です。For development work on Nano Server, you might find it useful to install Nano Server by using the -Development parameter of New-NanoServerImage. これにより、署名されていないドライバーのインストール、デバッガー バイナリのコピー、デバッグ用にポートを開く操作、テスト署名、開発者用ライセンスなしでの AppX パッケージのインストールを行うことができるようになります。This will enable installation of unsigned drivers, copy debugger binaries, open a port for debugging, enable test signing and enable installation of AppX packages without a developer license. たとえば、次のように入力します。For example:

New-NanoServerImage -DeploymentType Guest -Edition Standard -MediaPath \\Path\To\Media\en_us -BasePath .\Base -TargetPath .\NanoServer.wim -Development

コマンドレットの実装の種類の決定Determining the type of cmdlet implementation

PowerShell では、コマンドレットに対していくつかの実装の種類をサポートしています。どの種類の実装を使用しているかによって、Nano Server で実行するコマンドレットの作成操作および移植操作に必要なプロセスとツールが異なります。PowerShell supports a number of implementation types for cmdlets, and the one you've used determines the process and tools involved in creating or porting it to work on Nano Server. サポートされている実装の種類は次のとおりです。Supported implementation types are:

  • CIM - CIM (WMIv2) プロバイダーの上に階層的に配置された CDXML ファイルで構成されます。CIM - consists of CDXML files layered over CIM (WMIv2) providers
  • .NET - .NET アセンブリで構成され、管理されたコマンドレット インターフェイス (通常は C# で記述します) を実装します。.NET - consists of .NET assemblies implementing managed cmdlet interfaces, typically written in C#
  • PowerShell スクリプト - PowerShell 言語で記述されたスクリプト モジュール (.psm1) またはスクリプト (.ps1) で構成されます。PowerShell Script - consists of script modules (.psm1) or scripts (.ps1) written in the PowerShell language

移植する既存のコマンドレットに使用されている実装の種類がわからない場合は、製品または機能をインストールし、次のいずれかの場所にある PowerShell モジュール フォルダーを探します。If you're not sure which implementation you've used for existing cmdlets you want to port, install your product or feature and then look for the PowerShell module folder in one of the following locations:

  • %windir%\system32\WindowsPowerShell\v1.0\Modules%windir%\system32\WindowsPowerShell\v1.0\Modules

  • %ProgramFiles%\WindowsPowerShell\Modules%ProgramFiles%\WindowsPowerShell\Modules

  • %UserProfile%\Documents\WindowsPowerShell\Modules%UserProfile%\Documents\WindowsPowerShell\Modules

  • <your product installation location>

    次のことを理解したうえでこれらの場所を確認します。Check in these locations for these details:

    • CIM コマンドレットは、拡張子が .cdxml ファイルです。CIM cmdlets have .cdxml file extensions.
    • .NET コマンドレットは、拡張子が .dll ファイル拡張子です。または、アセンブリが、.psd1 ファイルの RootModule、ModuleToProcess、または NestedModules フィールドの下に記載されている GAC にインストールされています。.NET cmdlets have .dll file extensions, or have assemblies installed to the GAC listed in the .psd1 file under the RootModule, ModuleToProcess, or NestedModules fields.
  • PowerShell スクリプトのコマンドレットは、拡張子が .psm1 または .ps1 のファイル拡張子です。PowerShell script cmdlets have .psm1 or .ps1 file extensions.

CIM コマンドレットの移植Porting CIM cmdlets

通常、これらのコマンドレットは、変換せずに Nano Server で動作します。Generally, these cmdlets should work in Nano Server without any conversion necessary. ただし、基になる WMI v2 プロバイダーを Nano Server で動作するように移植していない場合は、移植する必要があります。However, you must port the underlying WMI v2 provider to run on Nano Server if that has not already been done.

Nano Server 向けの C++ のビルドBuilding C++ for Nano Server

C++ の DLL を Nano Server で実行するには、特定のエディションではなく Nano Server を対象にコンパイルします。To get C++ DLLs working on Nano Server, compile them for Nano Server rather than for a specific edition.

Nano Server 上の C++ の開発に関する前提条件とチュートリアルについては、「Developing Native Apps on Nano Server (Nano Server でのネイティブ アプリの開発)」を参照してください。For prerequisites and a walkthrough of developing C++ on Nano Server, see Developing Native Apps on Nano Server.

.NET コマンドレットの移植Porting .NET cmdlets

ほとんどの C# コードは Nano Server でサポートされます。Most C# code is supported on Nano Server. ApiPort を使用すると、互換性のない API を検出できます。You can use ApiPort to scan for incompatible APIs.

PowerShell Core SDKPowershell Core SDK

PowerShell ギャラリーから入手できる Microsoft.PowerShell.NanoServer.SDK モジュールを使用すると、Nano Server で使用可能な CoreCLR および PowerShell Core のバージョンをターゲットとする .NET コマンドレットを Visual Studio 2015 Update 2 で簡単に開発できるようになります。The module Microsoft.PowerShell.NanoServer.SDK is available in the PowerShell Gallery to facilitate developing .NET cmdlets using Visual Studio 2015 Update 2 that target the versions of CoreCLR and PowerShell Core available in Nano Server. このモジュールは、PowerShellGet と次のコマンドを使用してインストールすることができます。You can install the module using PowerShellGet with this command:

Find-Module Microsoft.PowerShell.NanoServer.SDK -Repository PSGallery | Install-Module -Scope <scope>

PowerShell Core SDK モジュールは、適切な CoreCLR および PowerShell Core 参照アセンブリをセットアップするためのコマンドレット、これらの参照アセンブリをターゲットとする C# プロジェクトを Visual Studio 2015 で作成するためのコマンドレット、および Nano Server コンピューター上にリモート デバッガーをセットアップするためのコマンドレットを公開します。そのため、開発者は、Visual Studio 2015 を使って、Nano Server 上で実行される .NET コマンドレットをリモートでデバッグできます。The PowerShell Core SDK module exposes cmdlets to set up the correct CoreCLR 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 developers can debug their .NET cmdlets running on Nano Server remotely in Visual Studio 2015.

PowerShell Core SDK モジュールを使用するには、Visual Studio 2015 Update 2 が必要です。The PowerShell Core SDK module requires Visual Studio 2015 Update 2. Visual Studio 2015 がインストールされていない場合は、Visual Studio Community 2015 をインストールできます。If you do not have Visual Studio 2015 installed, you can install Visual Studio Community 2015.

この SDK モジュールは、Visual Studio 2015 でインストールする次の機能にも依存します。The SDK module also depends on the following feature to be installed in Visual Studio 2015:

  • [Windows 開発と Web 開発]、[ユニバーサル Windows アプリ開発ツール]、[ツール (1.3.1) と Windows 10 SDK] の順にクリックWindows and Web Development -> Universal Windows App Development Tools -> Tools (1.3.1) and Windows 10 SDK

SDK モジュールを使用する前に Visual Studio のインストールを確認して、これらの前提条件が満たされていることを確認します。Review your Visual Studio installation before using the SDK module to ensure these prerequisites are satisfied. 必ず Visual Studio のインストール時に上記の機能をインストールするよう選択するか、または既存の Visual Studio 2015 インストールを変更して上記の機能をインストールしてください。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.

PowerShell Core SDK モジュールには、次のコマンドレットが含まれています。The PowerShell Core SDK module includes the following cmdlets:

  • New-NanoCSharpProject: Nano Server の Windows Server 2016 リリースに含まれている CoreCLR と PowerShell Core をターゲットとする新しい Visual Studio C# プロジェクトを作成します。New-NanoCSharpProject: Creates a new Visual Studio C# project targeting CoreCLR and PowerShell Core included in the Windows Server 2016 release of Nano Server.
  • Show-SdkSetupReadMe: エクスプローラーで SDK のルート フォルダーを開き、手動セットアップ用の README.txt ファイルを開きます。Show-SdkSetupReadMe: Opens the SDK root folder in File Explorer and opens the README.txt file for manual setup.
  • Install-RemoteDebugger: Nano Server コンピューターに Visual Studio リモート デバッガーをインストールし、構成します。Install-RemoteDebugger: Installs and configures the Visual Studio remote debugger on a Nano Server machine.
  • Start-RemoteDebugger: Nano Server が実行されているリモート コンピューターでリモート デバッガーを起動します。Start-RemoteDebugger: Starts the remote debugger on a remote machine running Nano Server.
  • Stop-RemoteDebugger: Nano Server が実行されているリモート コンピューターでリモート デバッガーを停止します。Stop-RemoteDebugger: Stops the remote debugger on a remote machine running Nano Server.

これらのコマンドレットの使い方の詳細については、モジュールをインストールしてインポートした後、次のように各コマンドレットに対して Get-Help を実行します。For detailed information about how to use those cmdlets, run Get-Help on each cmdlet after installing and importing the module as follows:

Get-Command -Module Microsoft.PowerShell.NanoServer.SDK | Get-Help -Full

互換性のある API の検索Searching for compatible APIs

API カタログ内で .NET Core を検索したり、Core CLR 参照アセンブリを逆アセンブルしたりできます。You can search in the API catalog for .NET Core or disassemble Core CLR reference assemblies. .NET API のプラットフォームの移植性の詳細については、「Platform Portability (プラットフォームの移植性)」を参照してください。For more information about platform portability of .NET APIs, see Platform Portability

PInvokePInvoke

Nano Server で使用される Core CLR では、kernel32.dll、advapi32.dll などのいくつかの基本的な DLL が多数の API セットに分割されました。そのため、PInvoke が正しい API を参照していることを確認する必要があります。In the Core CLR that Nano Server uses, some fundamental DLLs such as kernel32.dll and advapi32.dll were split into numerous API sets, so you'll need to ensure that your PInvokes reference the correct API. 互換性がない場合は、実行時エラーが発生します。Any incompatibility will manifest as a runtime error.

Nano Server でサポートされているネイティブ API の一覧については、「Nano Server APIs (Nano Server の API)」を参照してください。For a list of native APIs supported on Nano Server, see Nano Server APIs.

Nano Server 向けの C# のビルドBuilding C# for Nano Server

Visual Studio 2015 で New-NanoCSharpProject を使用して作成した C# プロジェクトをビルドするには、 [ビルド] メニューをクリックし、 [プロジェクトのビルド] または [ソリューションのビルド] を選択します。Once a C# project is created in Visual Studio 2015 by using New-NanoCSharpProject, you can simply build it in Visual Studio by clicking the Build menu and selecting Build Project or Build Solution. アセンブリは、Nano Server に付属する正しい CoreCLR および PowerShell Core をターゲットとして生成されます。そのため、Nano Server を実行しているコンピューターにコピーするだけでこのアセンブリを使用できます。The generated assemblies will be targeting the correct CoreCLR and PowerShell Core shipped in Nano Server, and you can just copy the assemblies to a computer running Nano Server and use them.

Nano Server 向けのマネージド C++ (CPP/CLI) のビルドBuilding managed C++ (CPP/CLI) for Nano Server

マネージド C++ は CoreCLR ではサポートされていません。Managed C++ is not supported for CoreCLR. CoreCLR に移植するには、C++ マネージド コードを C# で書き直し、すべてのネイティブ呼び出しを PInvoke 経由で行います。When porting to CoreCLR, rewrite managed C++ code in C# and make all native calls through PInvoke.

PowerShell スクリプト コマンドレットの移植Porting PowerShell script cmdlets

PowerShell Core は、PowerShell 言語に関して、Windows Server 2016 および Windows 10 で実行されているエディションを含む他の PowerShell エディションと完全に同等です。PowerShell Core has full PowerShell language parity with other editions of PowerShell, including the edition running on Windows Server 2016 and Windows 10. ただし、PowerShell スクリプト コマンドレットを Nano Server に移植する場合は、次の点に注意してください。However, when porting PowerShell script cmdlets to Nano Server, keep these factors in mind:

  • 他のコマンドレットに対する依存関係がありますか。Are there dependencies on other cmdlets? 依存関係がある場合、それらのコマンドレットは Nano Server で使用できますか。If so, are those cmdlets available on Nano Server. 使用できないコマンドレットについては、「Nano Server の PowerShell」を参照してください。See PowerShell on Nano Server for information about what is not available.
  • 実行時に読み込まれるアセンブリに対する依存関係がある場合、それらは引き続き動作しますか。If you have dependencies on assemblies that are loaded at runtime, will they still work?
  • スクリプトをどのようにリモートでデバッグしますか。How can you debug the script remotely?
  • WMI .Net をどのように MI .Net に移植しますか。How can you migrate from WMI .Net to MI .Net?

組み込みのコマンドレットに対する依存関係Dependency on built-in cmdlets

Nano Server では、Windows Server 2016 のコマンドレットを一部使用できません (「Nano Server の PowerShell」を参照してください)。Not all cmdlets in Windows Server 2016 are available on Nano Server (see PowerShell on Nano Server). 最も良い方法は、Nano Server 仮想マシンをセットアップし、必要なコマンドレットを使用できるかどうか確認することです。The best approach is to set up a Nano Server virtual machine and discover whether the cmdlets you need are available. そのためには、Enter-PSSession を実行してターゲットの Nano Server に接続し、Get-Command -CommandType Cmdlet, Function を実行して使用可能なコマンドレットの一覧を取得します。To do this, run Enter-PSSession to connect to the target Nano Server and then run Get-Command -CommandType Cmdlet, Function to get the list of available cmdlets.

PowerShell クラスの使用の検討Consider using PowerShell classes

Nano Server では、インライン C# コードをコンパイルするための Add-Type がサポートされています。Add-Type is supported on Nano Server for compiling inline C# code. 新しいコードを記述する場合や既存のコードを移植する場合は、PowerShell クラスを使ってカスタムの型を定義することを検討してください。If you're writing new code or porting existing code, you might also consider using PowerShell classes to define custom types. PowerShell クラスは、列挙型に加えてプロパティ バッグ シナリオにも使用できます。You can use PowerShell classes for property bag scenarios as well as for Enums. PInvoke を実行する必要がある場合は、Add-Type を使った C# 経由または事前にコンパイルしたアセンブリ内で実行します。If you need to do a PInvoke, do this via C# using Add-Type or in a pre-compiled assembly. 次の例に Add-Type の使い方を示します。Here's a sample showing the use of Add-Type:

Add-Type -ReferencedAssemblies ([Microsoft.Management.Infrastructure.Ciminstance].Assembly.Location) -TypeDefinition @'
public class TestNetConnectionResult
{
   // The compute name
   public string ComputerName = null;
   // The Remote IP address used for connectivity
   public System.Net.IPAddress RemoteAddress = null;
}
'@
# Create object and set properties
$result = New-Object TestNetConnectionResult
$result.ComputerName = Foo
$result.RemoteAddress = 1.1.1.1

この例は、Nano Server での PowerShell クラスの使い方を示しています。This sample shows using PowerShell classes on Nano Server:

class TestNetConnectionResult
{
   # The compute name
  [string] $ComputerName

  #The Remote IP address used for connectivity
  [System.Net.IPAddress] $RemoteAddress
}
# Create object and set properties
$result = [TestNetConnectionResult]::new()
$result.ComputerName = Foo
$result.RemoteAddress = 1.1.1.1

スクリプトのリモートでのデバッグRemotely debugging scripts

スクリプトをリモートでデバッグするには、PowerShell ISE から Enter-PSsession を使用してリモート コンピューターに接続します。To remotely debug a script, connect to the remote computer using Enter-PSsession from the PowerShell ISE. 開いたセッションで psedit <file_path> を実行して、ファイルのコピーをローカルの PowerShell ISE で開きます。Once inside the session, you can run psedit <file_path> and a copy of the file will be open in your local PowerShell ISE. 次に、ブレークポイントを設定して、スクリプトをローカルで実行しているかのようにデバッグできます。Then, you can debug the script as if it were running locally by setting breakpoints. また、このファイルに加えた変更は、すべてリモートのバージョンに保存されます。Also, any changes you make to this file will be saved in the remote version.

WMI .NET から MI .NET への移行Migrating from WMI .NET to MI .NET

WMI .NET はサポートされないため、古い API を使用しているすべてコマンドレットを、サポートされている WMI API:MI.NET) に移行する必要があります。WMI .NET is not supported, so all cmdlets using the old API must migrate to the supported WMI API: MI. NET. MI .NET には、C# から直接、または CimCmdlets モジュールのコマンドレットを通じてアクセスできます。You can access MI .NET directly through C# or through the cmdlets in the CimCmdlets module.

CimCmdlets モジュールCimCmdlets module

Nano Server では、WMI v1 コマンドレット (たとえば、Get-WmiObject) はサポートされていません。The WMI v1 cmdlets (e.g., Get-WmiObject) are not supported on Nano Server. ただし、CimCmdlets モジュールの CIM コマンドレット (たとえば、Get-CimInstance) はサポートされています。However, the CIM cmdlets (e.g., Get-CimInstance) in the CimCmdlets module are supported. CIM コマンドレットと WMI v1 コマンドレットはほとんど対応しています。The CIM cmdlets map pretty closely to the WMI v1 cmdlets. たとえば、Get-WmiObject は Get-CimInstance に対応し、よく似たパラメーターが使用されています。For example, Get-WmiObject correlates with Get-CimInstance using very similar parameters. メソッドの呼び出し構文は少し異なりますが、Invoke-CimMethod で明確に文書化されています。Method invocation syntax is slightly different, but is well documented via Invoke-CimMethod. パラメーターの型指定については注意が必要です。Be careful regarding parameter typing. MI .NET には、メソッド パラメーターの型に関してより厳密な要件があります。MI .NET has stricter requirements regarding method parameter types.

C# APIC# API

WMI .NET は WMIv1 インターフェイスをラップします。これに対し、MI .NET は WMIv2 (CIM) インターフェイスをラップします。WMI .NET wraps the WMIv1 interface, while MI .NET wraps the WMIv2 (CIM) interface. 公開されるクラスは異なる場合がありますが、基になる操作はよく似ています。The classes exposed might be different, but the underlying operations are very similar. オブジェクトのインスタンスを列挙または取得し、それに対する操作を呼び出してタスクを実行します。You enumerate or get instances of objects and invoke operations on them to accomplish tasks.