PowerShellでモジュールのバージョンを指定し、依存関係を確認する

Windows PowerShellで候補にある1.0.0と2.0.0、読み込んだ1.0.0、依存先の有無を順に確かめる図。

PowerShellで同じ名前のモジュールが複数見つかったら、まず検索先にある版と、いまの画面に読み込んだ版を確認します。モジュールは、関連する命令や処理をまとめた部品です。使う版が決まっていれば、Import-ModuleのRequiredVersionで指定できます。

Windows PowerShell 5.1で、一時フォルダーに自作のモジュールを用意します。同じ名前の二つの版を使って、指定した版を読み込めたか、別のモジュールが必要なときにその版が見つかるかを、画面の出力から判断します。

先に結論

  • Get-ModuleにListAvailableを付けると検索先にある版が分かり、省くと現在の画面に読み込んだモジュールを確認できます。
  • Import-ModuleのRequiredVersionは版番号の完全一致を指定します。読み込み後はGet-Moduleの版番号と、自作の処理が返す文字列を確認します。
  • 別のモジュールを必要とする関係を依存関係と呼びます。モジュールの設定ファイルに記した条件を満たす依存先が見つからないと、利用側の読み込みが失敗します。

Windows PowerShell 5.1と実行ポリシーを確認する

版を直接指定する操作と、別のモジュールを必要とする場合の確認に、練習画面を一つずつ使います。読み込んだモジュールの状態を持ち越さずに結果を比べられます。通常のユーザー権限で、一時フォルダーに書き込める環境を用意します。

掲載結果はWindows PowerShell 5.1.26100.9818で自作のスクリプトモジュールを使って取得しました。PowerShell 7、外部から入手したモジュール、コンパイル済みのファイルを使うバイナリモジュールでの動作は未確認です。

この例は、PowerShellの命令をまとめたpsm1ファイルを自分の画面で作り、読み込める環境が対象です。動かせるスクリプトを制限する設定を実行ポリシーと呼びます。準備コードを貼る前に、両方の画面で有効な設定を読みます。

  1. スタートメニューから「Windows PowerShell」を二つ開きます。
  2. 両方の画面で $PSVersionTable.PSVersion と入力し、Enterキーを押します。Majorが5、Minorが1なら、版番号の先頭が5.1です。 先頭が5.1以外なら、対象の画面を開き直してください。
  3. 最初の画面は版の指定に使い、もう一方は依存先の確認まで空けておきます。
  4. 下のGet-ExecutionPolicyを両方の画面で実行し、結果を確認します。この命令は現在の設定を表示します。

先に有効な実行ポリシーを読む

Get-ExecutionPolicy

実行結果

RemoteSigned

通常の検証環境では、検証の前後で有効な設定がRemoteSignedだと確認しました。この練習で端末上に新しく作るファイルは、結果を取得した環境では署名なしで読み込めました。署名は作成元を確認するための目印です。

Restrictedではpsm1を実行できず、AllSignedではローカルで作ったファイルにも信頼された署名が要ります。どちらかなら、この練習を中止します。実行ポリシーは元の設定で進め、管理されている端末では練習が許可される環境を管理者に確認してください。

練習フォルダーに同じ名前の二つの版を作る

最初の画面に下のコード欄を最終行の閉じ波かっこまで貼り付けます。貼り付けた内容がまだ実行前なら、最終行の末尾でEnterキーを押します。行末のバッククォートは命令を次の行へ続ける記号です。記号の後ろに空白を足さず、欄全体をまとめて使います。右端が隠れる場合は、コード欄の内側を横に動かせます。

縦線の | は、左の命令の結果を右へ渡す記号で、パイプと呼びます。ErrorAction Stopを付けた命令は、エラーでその処理を止めます。エラーがあれば後の欄へ進まず、作成場所と貼り付け範囲を確認します。

実行中のアプリが参照できる名前付きの設定値を環境変数と呼びます。PowerShellで $env: を名前の前に付けると、その値を参照できます。

コードは、モジュールを探すフォルダーの一覧であるPSModulePathを控えます。続いて、TEMPが示す一時フォルダーに固有の名前で練習フォルダーを作り、この画面の検索先に加えます。

Write-LabModuleは、名前で呼び出せる処理をまとめた自作関数です。処理を記したpsm1ファイルと、版や必要な部品を記したpsd1ファイルを版ごとのフォルダーに作ります。後者がマニフェストです。RootModuleで実行するファイルを、FunctionsToExportで外から呼び出せる関数を指定します。

設定名と値をひとまとめにした変数が $manifest です。New-ModuleManifestの後に @manifest と書くと、一覧の値が対応するオプションへ渡り、Pathに指定した場所へpsd1ファイルが作られます。

空の @() は空の一覧です。コマンドレットというPowerShellの命令の種類や、変数、別名を外から使える項目の一覧に追加しません。

練習フォルダーに3種類のモジュールを作る

$savedModulePath = $env:PSModulePath
$lab = Join-Path $env:TEMP ('module-lab-' + [guid]::NewGuid())
New-Item -ItemType Directory -Path $lab -ErrorAction Stop |
    Out-Null
$env:PSModulePath = $lab +
    [IO.Path]::PathSeparator + $savedModulePath

function Write-LabModule {
    param($Name, $Version, $Run, $Dependency, $Export)
    $directory = Join-Path $lab "$Name\$Version"
    New-Item -ItemType Directory -Path $directory -ErrorAction Stop |
        Out-Null
    Set-Content -LiteralPath (Join-Path $directory "$Name.psm1") `
        -Value $Run -Encoding UTF8 -ErrorAction Stop
    $manifest = @{
        Path              = Join-Path $directory "$Name.psd1"
        RootModule        = "$Name.psm1"
        ModuleVersion     = $Version
        FunctionsToExport = $Export
        CmdletsToExport   = @()
        VariablesToExport = @()
        AliasesToExport   = @()
    }
    if ($Dependency) { $manifest.RequiredModules = $Dependency }
    New-ModuleManifest @manifest -ErrorAction Stop
}

Write-LabModule -Name DogLabSampleRules -Version '1.0.0' `
    -Run "function Get-LabSampleRule { 'rule 1' }" `
    -Export 'Get-LabSampleRule'
Write-LabModule -Name DogLabSampleRules -Version '2.0.0' `
    -Run "function Get-LabSampleRule { 'rule 2' }" `
    -Export 'Get-LabSampleRule'
Write-LabModule -Name DogLabSampleReport -Version '1.0.0' `
    -Run 'function Get-LabSampleReport { Get-LabSampleRule }' `
    -Export 'Get-LabSampleReport' -Dependency @{
        ModuleName      = 'DogLabSampleRules'
        RequiredVersion = '1.0.0'
    }
Write-LabModule -Name DogLabSampleStrict -Version '1.0.0' `
    -Run '# 公開する関数なし' -Export @() -Dependency @{
        ModuleName      = 'DogLabSampleRules'
        RequiredVersion = '9.9.0'
    }

途中の行を追加入力する表示が続くときは、閉じる記号と貼り付け範囲を確認します。やり直す場合はCtrl+Cで入力を取り消します。

準備が一部でも実行された可能性がある場合は、同じ画面に貼り直さないでください。今の画面で $lab と入力し、Enterキーで作成先が表示されたら控えます。最後の片付け手順に沿って、今回作ったと確認できるフォルダーだけを片付け、画面を閉じます。場所が確認できないときは、フォルダーには触れず画面だけを閉じます。準備は新しく開いた練習画面でやり直します。

エラーが出ず、通常の入力待ちに戻ったら候補の確認へ進みます。DogLabSampleRulesの1.0.0は「rule 1」、2.0.0は「rule 2」を返します。このモジュールの特定の版を必要とする利用側として、DogLabSampleReportとDogLabSampleStrictも作ります。

同名候補の保存場所と読み込み状態を調べる

検索先に二つの版があり、読み込み済みの件数は0です。

同じ画面で下の欄を最後の行まで実行します。最初に、練習用の3種類の名前を $names に入れます。ListAvailable付きのGet-Moduleで検索先の候補を、ListAvailableを付けないGet-Moduleで現在の画面で読み込んだ部品を調べます。@(…) は結果を一覧として扱う記法で、Countは件数です。

Pathは保存場所です。StartsWithで各候補の場所が練習フォルダー名と区切り記号で始まるかを調べます。Where-Objectの中の $_ は、候補の一覧を順に調べるときの現在の1件です。練習フォルダー外の候補を拾い、該当すれば名前、版、保存場所を並べて表示します。throwはこのコード欄の処理を中止する命令です。

保存場所と読み込みの状態を調べる

$names = 'DogLabSampleRules',
    'DogLabSampleReport', 'DogLabSampleStrict'
$candidates = @(Get-Module -ListAvailable -Name $names)
$loaded = @(Get-Module -Name $names)
$prefix = $lab + [IO.Path]::DirectorySeparatorChar
$outside = @($candidates | Where-Object {
    -not $_.Path.StartsWith(
        $prefix, [StringComparison]::OrdinalIgnoreCase)
})
"outside=$($outside.Count)"
"loaded=$($loaded.Count)"
if ($outside.Count -gt 0 -or $loaded.Count -gt 0) {
    $outside + $loaded | Select-Object Name, Version, Path
    throw '同名候補または読み込み済みの部品を確認してください。'
}
$candidates | Where-Object { $_.Name -eq 'DogLabSampleRules' } |
    Sort-Object Version |
    ForEach-Object { "available=$($_.Version)" }

実行結果

outside=0
loaded=0
available=1.0.0
available=2.0.0

outside=0、loaded=0、available=1.0.0、available=2.0.0の4行が出たときだけ次へ進みます。outsideは練習フォルダー外にある同名候補の数、loadedはこの画面で既に読み込んだ同名モジュールの数です。二つのavailable行は見つかった規則の版を表します。

outsideまたはloadedが0以外なら、表示した名前・版・場所を確認し、この実習を中止します。既存の部品の削除や版の切り替えは行いません。候補の版が違う場合も進まず、準備の欄から見直します。

1.0.0を指定して読み込んだ版を確認する

同じ画面で下の欄を最後の関数呼び出しまで実行します。Import-Moduleは、この画面でモジュールを使えるようにする命令です。RequiredVersionには完全に一致させる版番号を指定します。MinimumVersionを使う場合は、指定した版が下限になります。

読み込み直後にGet-Moduleで版番号を表示し、最後にGet-LabSampleRuleを呼び出します。表示された版番号と、実際に呼び出した関数の結果を順に確認できます。

1.0.0を明示して読み込む

Import-Module -Name DogLabSampleRules -RequiredVersion '1.0.0' -ErrorAction Stop
Get-Module -Name DogLabSampleRules |
    ForEach-Object { "loaded=$($_.Version)" }
Get-LabSampleRule

実行結果

loaded=1.0.0
rule 1

loaded=1.0.0に続いて「rule 1」が出れば、指定した版の読み込みを確認できました。この欄のloadedは版番号を表します。結果が違う場合は、最後の節の手順で片付け、新しい練習画面で準備と候補確認からやり直します。

読み込み時に実行制限や署名に関するエラーが出たら、この手順で止めます。制限を付けた検証用の画面ではPSSecurityExceptionとUnauthorizedAccessが出ました。候補の版が見つかっていても起こり得るため、冒頭のGet-ExecutionPolicyの結果とエラーの内容を確認してください。

依存先の1.0.0を利用側から呼び出す

別のモジュールを必要とする関係を依存関係と呼びます。もう一方の練習画面に準備のコード欄を最終行まで貼り付け、同じ画面で候補確認の欄を実行します。outsideとloadedが両方0で、候補が1.0.0と2.0.0のとき、下の欄へ進みます。

DogLabSampleReportのマニフェストでは、必要なモジュールをRequiredModulesに記します。ModuleNameには依存先の名前、RequiredVersionには必要な版番号を書きます。下の欄で利用側を読み込み、依存先の関数を呼ぶGet-LabSampleReportを実行します。

利用側から依存先の関数を呼ぶ

Import-Module -Name DogLabSampleReport -ErrorAction Stop
Get-LabSampleReport

実行結果

rule 1

「rule 1」が出れば、利用側の関数から依存先の1.0.0を呼び出せています。この準備では、同じ名前の2.0.0も検索先に置いた状態で確認しています。

必要な9.9.0が見つからないときの結果を読む

依存先を確認している画面で、下の欄を件数の表示まで実行します。DogLabSampleStrictはDogLabSampleRulesの9.9.0を要求します。先に確認した候補は1.0.0と2.0.0で、練習フォルダー外の同名候補は0件です。この状態では9.9.0が候補に見つかりません。

tryは処理を試す範囲、catchはエラーを受け取って処理する範囲です。この例では、読み込みにErrorAction Stopを指定することで、失敗したときにcatchへ進みます。

必要な版が見つからないときの結果

try {
    Import-Module -Name DogLabSampleStrict -ErrorAction Stop
    'unexpected success'
} catch {
    'import failed'
    $errorName = ($_.FullyQualifiedErrorId -split ',')[0]
    "error=$errorName"
    if ($_.Exception.Message -like '*DogLabSampleRules*') {
        'module=DogLabSampleRules'
    }
}
"loaded=$(@(Get-Module -Name DogLabSampleStrict).Count)"

実行結果

import failed
error=Modules_InvalidManifest
module=DogLabSampleRules
loaded=0

「import failed」は、catchに入ったときに例が表示する文字列です。error=の行はPowerShellが返したエラーIDの先頭部分で、IDはエラーの種類を調べる手掛かりです。module=の行は、エラー文にDogLabSampleRulesの名前が含まれたときにだけ出ます。

この例のModules_InvalidManifestはマニフェストを読んだときの失敗を示します。IDだけで原因は決まりません。依存先名がDogLabSampleRulesで、StrictのRequiredVersionが9.9.0であり、保存場所を確認した候補にその版がないことを順に照合して、必要な版の不足と判断します。

最後のloaded=0は利用側のDogLabSampleStrictの件数で、読み込みが成立しなかったことを示します。実務ではエラーに出た依存先名と利用側の設定を照らし、わからなければその記録を管理者に共有します。

マニフェストのどこにある版番号かを確認する

マニフェストを読むときは、版番号の指定がRequiredModulesの内側にあるかを確認します。マニフェスト本体のModuleVersionは、そのファイルが説明するモジュール自身の版です。RequiredModulesの内側では、版番号は依存先に求める条件になります。

上の例では1.0.0との完全一致を指定しました。依存先に許容範囲を設ける場合は、下限と上限の指定を組み合わせられます。

  • ModuleVersionは、依存先に許容する下限です。
  • MaximumVersionは、依存先に許容する上限です。
  • RequiredVersionは完全一致を指定します。ほかの版条件との組み合わせを避け、単独で使います。

比較表で次に調べる場所を選ぶ

表は、検索先の候補、読み込んだ版、依存先が不足した場合の結果を並べています。候補が足りなければ検索先と版ごとの配置を確認します。読み込み済みの版が意図と違えばImport-Moduleの指定を、利用側が失敗すれば、エラーの依存先名、RequiredModulesの必要版、検索先にある版の順に照合します。

PowerShellGetは、モジュールを入手・管理するための命令をまとめた部品です。その中のInstall-Moduleは、モジュールを保存先へ導入します。そのAllowClobberは、同じ名前の命令がすでにある場合の警告に関わります。実務で必要な版が見つからないときは、導入操作の前に、必要な版と検索先をプロジェクトの資料や管理者に確認します。

署名やセキュリティのエラーがあるときは、先に有効な実行ポリシーを確認し、この練習を中止します。依存先が足りないかを判断するのは、エラーに依存先名が出て、必要版と検索候補を照合できる場合です。

調べたいこと この例で読む結果
検索先にある版 outside=0、loaded=0、候補は1.0.0と2.0.0
読み込み直後の版 loaded=1.0.0、関数は rule 1
依存先の版が見つからない エラーID・依存先名を読み、利用側は loaded=0
読み込みが制限された 実行ポリシーと署名・セキュリティのエラーを確認

二つの練習画面を片付ける

準備を実行した練習画面ごとに、下のコード欄を最後の行まで実行します。最初の行で、この画面のモジュール検索先を控えておいた値へ戻します。最後の行は、その画面で作った練習フォルダーの場所を表示します。

検索先を元に戻して練習フォルダーを表示する

$env:PSModulePath = $savedModulePath
$lab

練習フォルダーの場所を控えたら画面を閉じます。エクスプローラーのアドレス欄に控えた場所を貼り付けて開きます。フォルダー名を確認して一つ上の階層へ移り、今回作ったmodule-lab-で始まる同じ名前のフォルダーだけを選んで削除します。途中で止めた場合も、画面を閉じればその画面での検索先の変更は消えます。削除は作成場所を特定できたフォルダーだけに行います。