PowerShellモジュールの作成方法

.NETバイナリモジュール

.NETのバイナリモジュールを作成する場合は、クラスライブラリを作成し、それをCmdletより継承する。尚、PowerShellのRunspaceを使用する必要がある場合は、PSCmdletから継承する。PSCmdletを使用するとPowerShellのランタイムに依存するため、これが好ましくない場合はCmdletを使用する。ただし、この場合、Runspaceに依存するいくつかの機能が使用できなくなる。

モジュールを構成する場合の注意

モジュールを構成後、モジュールをモジュールパス($Env:PSModulePath)のサブディレクトリに配置することにより、読み込めるようになるが、この場合いくつか注意する必要がある。

PSD1ファイルの作成

モジュールはサブディレクトリと同じ名前のPSD1ファイルを持つ必要がある。これがなくともImport-Module Cmdletを使用して、読み込むことはできるけど不便。このファイルがあることにより、Cmdletが実行された際に動的に自動読み込みを行うことができる。尚、PowerShell Galleryなどに公開する場合は、PSD1ファイルはメタデータ提供手段として必須。

以下はMyNumberPSにおける例。このファイル自体はNew-ModuleManifest Cmdletを使用して動的に生成することができる。 FunctionsToExportに指定している関数はCmdletとして使用できるようになる。こちらはワイルドカード'*'も使用できるらしいが、うまく動作しない。

@{
    RootModule = 'MyNumberPS.dll'
    ModuleVersion = '1.2.0.0'
    FunctionsToExport = @(
            'Get-MyNumber'
            'Test-MyNumber'
            'Get-MyNumberRange'
        )
    CmdletsToExport   = '*'
    VariablesToExport = '*'
    AliasesToExport   = '*'
    GUID = 'de6fc708-4172-4685-abf4-2cd5930e6ba9'
    Author = 'Hideki Saito'
    Description = 'MyNumber Module for PowerShell'
    PowerShellVersion = '6.0'
    CompatiblePSEditions = 'Core'
    Copyright = '(c) 2018 Hideki Saito. All rights reserved.'
    PrivateData = @{
        PSData = @{
            ProjectUri = 'https://github.com/hsaito/MyNumberPS/'
            LicenseUri = 'https://github.com/hsaito/MyNumberPS/blob/master/LICENSE'
            ReleaseNotes = ''
        }
    }
}

この後、Get-Module -ListAvailableでモジュールが表示されていればモジュールのインストールは成功している。

Binary     1.2.0.0    MyNumberPS                          Core      {Get-MyNumber, Test-MyNumber, Get-MyNumberRange}

バイナリモジュールの代わりにスクリプトモジュールを使用する場合は、.ps1を指定する。

ヘルプファイル

PowerShellのヘルプファイルは書くのが面倒くさいので、platyPSを使用してマークダウン書式で書くのが一番楽。 platyPSはDeskエディション(つまりCoreではなく、Windows PowerShell)のモジュールなので、WindowsCompatibibilityモジュールのインストールが必要になる。

モジュールを読み込んだあとに、New-MarkdownHelp Cmdletを使用すると、モジュールに基づいたファイルが生成されるので、それを編集する。編集後、New-ExternalHelp Cmdletを使用すると、XMLファイルが生成されるので、それをモジュールが入っているディレクトリにコピーする。これで、モジュールの読み込み時にヘルプも読み込まれるようになる。

尚、モジュールに変更が加わった場合はUpdate-MarkdownHelpModule Cmdletを使用すると、マークダウンファイルが更新される。