Adam the Automator

PowerShell モジュールを使用することは、PowerShell の自動化の重要な部分です。 PowerShell を学び始めると、最初のステップは通常、単一のコマンドを使用することです。 これは、スクリプトの構築につながり、次に関数の構築につながります。

関数を使用することにより、スクリプトをよりモジュール化することができます。 これにより、あちこちにコードをコピー＆ペーストすることなく、多くの場所で同じコードを使用できるようになります。 関数を使うことで、同じコードをあちこちで使うときに、同じ編集をする時間を短縮することができます。

関数を次のレベルに引き上げるには、これらの関数をモジュールにまとめることができます。 モジュール・マニフェストやコメントベースまたは外部ヘルプなど、オプションの追加も含まれることがあります。 これらについては後で説明します。

前提条件

この記事では、Windows PowerShell 5.1 を使用することにします。

モジュールとの対話

最初に PowerShell セッションを開くと、2 つのモジュールから開始します。 1 つは Microsoft.PowerShell.Utility で、すでに使用している多くの基本的な PowerShell 関数を含んでいます。 もう1つのモジュールはPSReadlineです。 これらの開始モジュールは、Get-Module コマンドを使用して確認できます。

つまり、これは利用できるすべてのモジュールの完全なリストというわけではありません。 PowerShell 3 以降、インストールされているモジュールは、必要に応じてインポートされます。 PowerShell の古いバージョンを実行している場合、コマンドを使用する前に、まず Import-Module コマンドを使用してモジュールをインポートすることが必要になります。 もし、すでにインストールされた後にモジュールをインポートしたかったら、次のように Import-Module を使用できます:

Get-Module はインポートされているモジュールをすべて表示しますが、まだインポートされていないモジュールは表示されません。

で一覧表示する

Not all Commands are Shown By Default

ExportedCommandsプロパティは、モジュールからエクスポートされる利用できるすべてのコマンドのリストが含まれています。 このリストとモジュール・ファイルにあるものの間に、いくつかの相違が見られるかもしれません。 エクスポートされたコマンドは、モジュール マニフェストに組み込まれた機能で、ライターが関数を非表示として残すことを可能にします。 モジュールの作成者は、Export-ModuleMember コマンドレットを使用することもできますが、この記事の範囲外です。

モジュールの作成者は、ユーザー向けではなく他の機能をサポートするために機能を非表示にしたい場合があります。 関数を非表示にするには、作成者はマニフェストの FunctionsToExport 配列から関数を除外します。

モジュールのインポート

モジュールを使い始めるには、さまざまな方法があります。 モジュールファイルへのパスを使用して、手動でモジュールをインポートすることができます。 これにより、多くの作業をすることなく、モジュールのテストと更新ができるようになります。 しかし、これでは、モジュールへの正確なパスを使用しなければならないので、あまり移植性がありません。 PowerShell はまた、$env:PSModulePath 変数にないモジュールを自動インポートしません。

コマンドの選択的インポート

Import-Module を使用して、モジュール全体ではなく、特定の機能のみをインポートすることが可能です。 これは、Office 365モジュールなど、リモートシステムからモジュールをインポートする際に時間を節約できます。

All User Modules

すべてのユーザーに対してインストールされたモジュールは、C:³ FilesWindowsPowerShell³³に配置されます。 このディレクトリには、デフォルトのスコープ AllUsers を使用して Install-Module でインストールされたモジュールを含む、多くの追加済みモジュールが含まれます。

Current User Modules

モジュールをインストールするが 1 人のユーザーだけに使用させる場合は、CurrentUser スコープがあります。 この場合、モジュールファイルはDocumentsフォルダのC:IssufficientUsers<username>に置かれます。 これは、Documents フォルダでフォルダリダイレクトを使用している環境で便利です。

この場合、同じドキュメントフォルダを共有することになるので、あるコンピューターにモジュールをインストールして、別のコンピューターで使用することができます。 技術的には、このパスに置かれたモジュールは他のパスのようにインポートされますが、これは Microsoft のシステム モジュール用に予約されているので、推奨されません。

Naming is Important

新しいセッションでデフォルトで使用できるように、これらのパスのいずれかにモジュールを手動で配置できますが、モジュールに必要な命名に従っているかどうかを確認する必要があります。 モジュール ファイルが配置されるフォルダーは、psm1 モジュール ファイルおよび psd1 モジュール マニフェストがある場合はそれと同じ名前でなければなりません。

前述の Get-Module -ListAvailable を使用して、これらのパスを参照します。 $env:PSModulePath -Split ';' を使用すると、すべてのモジュールのパスが表示されます。 ここに表示されている以外のパスが表示されていることに気づくかもしれません。 多くのプログラムは、インストール時に独自のモジュール・パスを追加します。 この例の 1 つが SQL で、独自のモジュール パスに含まれています。

でモジュール パスを見る

また、異なるプロセスでインストールするようなモジュールもいくつか存在します。 その代表的なものが、ActiveDirectory モジュールです。 Windows 7 から Windows 10 1803 までは、リモート サーバー管理ツール (RSAT) インストーラーでこれをインストールします。

新しいバージョンの Windows 10 (1809+) では、これは Features On Demand を通してのみ利用可能です。 RSATをインストールすると、他のWindowsの役割を管理するために使用するActiveDirectoryモジュールや他の多くのモジュールがインストールされます。 Windows サーバー OS では、これらのモジュールはサーバーマネージャーを通じてインストールされます。

リモートモジュールのインポート (Implicit Remoting)

モジュールをローカルで実行させることが現実的ではないような場合もあります。 その代わりに、リモートデバイスに接続し、そこにインストールされているモジュールをインポートする方がよいでしょう。 これを行うとき、コマンドは実際にリモート・マシンで実行されます。 これは、MicrosoftのOffice 365モジュールで頻繁に使用されています。 その多くは、Office 365サーバーに接続し、そこからモジュールをインポートします。

リモート モジュールをインポートするもう 1 つの用途は、ローカルにモジュールがインストールされていない場合です。 これは、ActiveDirectory モジュールがインストールされていないのに、それをインポートしようとした場合に表示されます。

リモート モジュールをインポートするには、まず PSSession を作成する必要があります。 New-PSSession を使用してセッションを作成することができます。 次に、PSSession パラメーターに Import-Module を使用して、リモート デバイスで利用可能なモジュールをインポートします。

PS51> $AdminServer = New-PSSession -ComputerName $AdminServerName -Credential (Get-Credential)PS51> Import-Module -Name ActiveDirectory -PSSession $AdminServer -Prefix 'Rmt'

リモート モジュールのインポートにこの方法を使用すると、分散環境でコードを高速に実行することができます。 たとえば、自分のコンピューターで作業しているが、作業しているサーバーが米国内にある場合、サーバーに対してローカルに特定のコマンドを実行すると、かなり時間がかかることがあります。

モジュール接頭辞の追加

リモートマシンからインポートした関数に接頭辞を追加することも可能です。 このオプションはローカル モジュールをインポートする際に利用できますが、異なるバージョンのモジュールを並べてテストする以外ではほとんど使用されません。

上記の import コマンドを実行した場合、コマンドを見るとこのようになります:

この場合、ローカルモジュールでないことを表示するのに、プレフィックスを使用することができます。 これは、ローカルでも利用可能なモジュールをインポートしている場合に使用できます。

モジュールの削除

また、Remove-Module を使用せずに、現在のセッションからモジュールを削除することができます。 これは、モジュールファイルを削除することなく、ローカルセッションからモジュールを削除する。 リモートセッションでモジュールを使用していたような場合に使用するとよいでしょう。 Remove-Module を使用してセッションをクリーンアップしてから、リモート セッションを切断できます。

Remove-Module の別の使用法は、モジュールに変更を加えている場合に、新しい PowerShell セッションを起動しないようにしたいときです。 この場合、Remove-Module の後に Import-Module を使用して、セッションに再読み込みします。 または、ForceパラメータをImport-Moduleと一緒に使用することもできます。

PowerShell モジュールの構成

モジュールは 1 つまたは複数のファイルから構成されることがあります。 モジュールの最小要件を満たすには、モジュール ファイルを用意する必要があります。 これは、PSM1 ファイルまたはバイナリ モジュール ファイルのような他のモジュール ファイルであることができます。 その上に構築するために、psm1 には関数が定義されている必要があり、そうでなければ誰にもあまり役に立ちません。 通常、モジュール内のすべての関数は同じコンセプトで構築されることが望ましいです。

モジュールは同種の関数を含む

例えば、ActiveDirectory モジュールは、何らかの方法で Active Directory と相互作用する関数だけを含んでいます。 通常、関数名には接頭辞も含まれます。 ActiveDirectory モジュールを例にとると、関数名のすべての名詞は AD で始まります。

このガイドラインを使用すると、関数を見つけやすくなります。 この新しいモジュールをインポートして、関数をタブで確認することを想像してみてください。 すべての関数が似たような名前の構造を持っていれば、これははるかに簡単です。 PS で始まるモジュールをよく見かけますが、この接頭辞は Microsoft のモジュールにのみ公式に予約されています。

これらのガイドラインを使用すると、レジストリとの対話に関連する関数の束がある場合、次のようなものになります:

function Get-ATARegistryKey {...}function Set-ATARegistryKey {...}

Module Manifests

テキスト モジュール ファイルをベースにするために、モジュール マニフェストを含めることも可能です。 これらのファイルには PSD1 拡張子があり、モジュールに関するメタデータが含まれています。 ここには、作者、モジュールの説明、他の必須モジュール、および他の多くの属性に関する情報を含めることになります。 リポジトリに公開するには、Author および Description フィールドが入力されている必要があります。

レジストリ モジュール用に用意されているマニフェストの例を次に示します。 含まれるコマンドは New-ModuleManifest です。

PS51> New-ModuleManifest -Path .\Scripts\TestModule.psd1 -Author 'Tyler Muir' -CompanyName 'Adam the Automator' -RootModule 'TestModule.psm1' -FunctionsToExport @('Get-RegistryKey','Set-RegistryKey') -Description 'This is a test module.'

External Help Files

また、いくつかのモジュールで外部ヘルプ ファイルを目にすることがあります。 これらは、ファイル名の最後に <ModuleName>-Help.xml があることで識別できます。 これらの外部ヘルプ ファイルには、関数定義にあるコマンドベースのヘルプに通常含まれるのと同じ情報が含まれています。

この場合、モジュールをインポートした後に Get-Help コマンドを使用して正しく動作させるために、関数に # .ExternalHelp <ModulePath>-Help.xml を追加することも必要です。 通常、外部ヘルプファイルを見るのは非常に大きなモジュールでのみ一般的で、そのため、この範囲外となっています。 他の依存関係があるため、テキスト・モジュールに加えてバイナリ・ファイルを目にすることもあります。

非標準のモジュール ファイルを適切に発行するには、モジュール マニフェストの FileList パラメータに他のファイルをインクルードしなければなりません。 これらを使用して、モジュールを使用するための他の要件を定義することができます。 たとえば、モジュールが動作する PowerShell のバージョンを定義することができます。 サポートされていないバージョンの PowerShell でモジュールをインポートしようとすると、次のように表示されます。

PSRepositories

モジュール用のキー配布方法の 1 つに PSRepositories というものがあります。 PSRepository は、複数の人または複数のデバイスがモジュール ファイルにアクセスできるローカルな場所と見なせます。 これらは、ファイルを公開できる Web サーバーであることが多いです。

リポジトリにディレクトリを使用することもできますが、これはリポジトリの機能に制限を与えます。 PSRepository を自分でホストすることもできますし、PowerShell Gallery のようなインターネット上で利用できる多くのオプションの 1 つを利用することもできます。

デフォルトでは、PowerShell Gallery のエントリーが 1つだけあります。 このとき、「信頼されていない」と表示されていることに気づくかもしれません。 これは、PowerShell ギャラリーを使用することにより、Microsoft によって書かれておらず承認されていないコードを使用する可能性があることを PowerShell が認識するためです。

PSRepositories の追加

また、独自のリポジトリを追加することも可能です。 PowerShell Gallery を信頼するには、Get-PSRepository -Name PSGallery | Set-PSRepository -InstallationPolicy Trusted を実行するか、PowerShell Gallery からモジュールを最初にインストールするときに警告を受け入れることができます。

これらの PSRepositories と対話するために使用するすべてのコマンドは、PowerShellGet モジュールで見つけることができます。 ここでは、その関数を見ることができます。

特定のリポジトリとやり取りする前に、PowerShellGet モジュールを更新する必要がある場合があります。 これは、Find-Moduleコマンドを使用して実現します。 探しているものを具体的に見つけるためにフィルタリングする方法は複数ありますが、今のところ、次のように VMware モジュールを検索できます：

VMware で始まるすべてのモジュールが表示されます。 これらのほとんどは VMware からのものですが、誰がモジュールを公開したかを確認するには、作成者属性を見る必要があります。

PowerShell Gallery には誰でもアップロードできるため、何千ものモジュールが利用できます。 つまり、自分のユースケースで適切に動作しないモジュールが見つかる可能性があります。

モジュールのインストール

Install-Module コマンドを使用するには、モジュールをホストしている信頼できる PSRepository を用意する必要があります。 これは、PowerShell ギャラリー、他のインターネット PSRepository、またはセルフホスティングサイトになります。

MinimumVersion, MaximumVersion, または RequiredVersion パラメータを使ってモジュールのバージョンを定義することもできます。

Install-Moduleを使ってインストールしたすべてのモジュールを確認するには、Get-InstalledModule が利用できます。 これは、AllUsers スコープまたは CurrentUser スコープにインストールされたすべてのモジュールを一覧表示します。

モジュールのアンインストール

モジュールをインストールできるのと同様に、モジュールをアンインストールすることも可能です。

ここで見られるように、私たちは ActiveDirectory モジュールをアンインストールしようとしています。 このモジュールは Install-Module でインストールされていないため、Uninstall-Module を使用しようとするとエラーが発生します。

モジュールのアンインストールの成功を確認するには、以前にインストールした VMware.PowerCLI モジュールをアンインストールすることができます。

VMware.PowerCLI をアンインストールしても、多くの依存関係がインストールされていることが確認できます。 すべてのモジュールをアンインストールする場合は、Get-InstalledModule VMware.* | Uninstall-Module -Force を使用できます。

このモジュールを完全にアンインストールすることが困難な理由は、このモジュールには非常に多くの依存関係があるためです。

モジュールの更新

モジュールをインストールおよびアンインストールする方法がわかったので、インストールしたモジュールをどのように更新するのか気になることでしょう。 Update-Module を使用して、モジュールを最新リリースまたはより新しい特定のバージョンに更新できます。

また、AllowPreRelease へのスイッチがあり、正式にリリースされていないバージョンに更新することが可能です。

でモジュールを更新

モジュールの検査/保存

あまり使われていないコマンドのひとつですが、使用前にモジュールを検査する際に非常に便利なのが、Save-Module です。

そして、ファイルを検査し、もしモジュールがバイナリモジュールでないなら、 モジュールを構成するコードを開いて見ることができます。

によるモジュールのダウンロード

この例では、VMware.PowerCLI モジュールだけでなく、すべての依存ファイルもダウンロードされます。 以下は、VMware.PowerCLI フォルダーに表示される内容です。

これは、エンドユーザー ライセンス契約などの標準ではないモジュール ファイルが含まれている場合があることを示す良い例です。

独自のモジュールを作成

これまで、他の誰かのモジュールとやり取りする方法を見てきました。

テンプレートファイルの作成

最初に、すべてのモジュールファイルのためのフォルダーを作成する必要があります。 コンテナを作成したら、モジュールファイルを作成する必要があります。 さもないと、モジュールを公開しようとしたときに、PowerShell はモジュールを正しく検出できません。

PS51> New-Item -Path .\Scripts -Name ATARegistry -ItemType DirectoryPS51> New-Item -Path .\Scripts\ATARegistry -Name ATARegistry.psm1

ここで、マニフェストも使用したいので、コンテナーおよびモジュール ファイルと同じ名前を付ける必要があります。 このモジュールを PSRepository に公開し、好きな場所にインストールを開始することができます。 しかし、モジュール ファイルが空であるため、おそらくあまり役に立ちません。

PSRepository の登録

モジュールを公開する前に、セッションに別の PSRepository を追加する必要があります。

通常、ディレクトリを使用して PSRepository を設定する場合、複数のコンピューターがアクセスできるようにしたいものです。 このようにローカルリポジトリを作成します。

PS51> New-Item -Path C:\ -Name Repo -ItemType DirectoryPS51> Register-PSRepository -Name 'LocalRepo' -SourceLocation 'C:\Repo' -PublishLocation 'C:\Repo' -InstallationPolicy Trusted

もし PSRepository からダウンロードするだけで、公開しないのであれば、PublishLocation パラメータを除外できます。

Publishing your Module

すでにインストールポリシーを trusted にしているので、リポジトリからモジュールをインストールすることを許可するかどうか確認されないと思われます。 新しい PSRepository が利用可能になったので、Publish-Module -Name .\Scripts\ATARegistry -Repository LocalRepo を使用してモジュールを公開できます。

モジュールを公開した後、上記のコマンドを使用してモジュールを検索し、インストールすることができます。 マニフェストの FunctionsToExport 配列に関数を追加しなかったので、ExportedCommands プロパティは空です。

モジュールへの追加

ここで、モジュールを公開およびインストールできることを確認し、それに機能を追加することが開始できます。 レジストリ キーを返す関数を追加して、次のようになります。 1 つ目は、「モジュールのバージョンはすでにリポジトリに存在する」というエラーを受け取ることです。

モジュール関数のエクスポート

もうひとつの問題は、モジュールをインポートした後、新しい関数をマニフェストに追加していないため、ExportedCommands プロパティに関数が表示されないということです。

これらの 2 つの問題を解決するには、次のようにモジュール ファイルを更新します。

ModuleVersion = '1.1'FunctionsToExport = 'Get-RegistryKey'

モジュールに機能を追加し、これらの変更を反映するためにマニフェストを更新したので、以前と同じコマンドを使用してモジュールの新しいバージョンを公開することができます。 Update-Module ATARegistry を使用して、先ほどリポジトリに公開した更新をダウンロードします。

これで、新しいバージョンのモジュールとマニフェストに定義した関数があることが確認できます。 おそらく、ある時点で関数に Get-Help を使用したことがあるはずです。 この情報は、主に 2 つの方法で追加できます。

1つ目は、コメント ベースのヘルプを関数定義に追加する方法です。 これは通常、多くのモジュール作成者が実装している方法です。 もう 1 つの方法は、外部ヘルプ ファイルを使用することです。

でのヘルプ検索

見てわかるように、本当に多くの情報はなく、得られた小さな情報は、おそらく誰にも役に立ちません。 Get-Help about_Comment_Based_Help を使用して、コメントベースのヘルプのすべてのオプションについて読むことができます。

今のところ、関数を以下のように更新することができます。 これは最も一般的に使用されるヘルプパラメーターのリストですが、これらはすべてまだオプションであり、代わりに追加できるものもあります。

これで、関数は次のようになります。 このオプションは、受信したすべてのヘルプ要求を別のコマンドに転送します。

ヘルプを追加したので、モジュール マニフェストのバージョンを更新し、新しいバージョンを公開し、以前に行ったようにセッションのインストール済みバージョンを更新することができます。

で完全なヘルプ コンテンツを取得する

外部ヘルプ ファイルの場合、追加される情報は同じですが、情報が別のファイルに置かれ関数内にリンクされています。

モジュールパスを見ると、モジュールのバージョンと、今までインストールしてきたモジュールファイルがすべて表示されます。

先に作成したPSRepositoryパスC:³”Demo “に戻るとNUPKGファイルがたくさん表示されるはずです。 公開したバージョンごとに1つずつあるはずです。 これらは、Publish-Module.

Summary

PowerShellコンソール、言語としてのPowerShell、スクリプトの書き方を理解したら、最後のステップとして独自のモジュールをビルドします。 モジュールを使用すると、PowerShell で便利なツールの開発を始めることができます。 一つの目的のためにモジュールを作って正しく設計・構築すれば、必然的に時間の経過とともに書くコードが少なくなっていきます。 より多くのコードでモジュール関数を参照し、そこから構築するようになります。

モジュール関数を使用すると、スクリプトで繰り返しているコードを抽象化することができます。 それらは、車輪の再発明や、以前に目標を達成した方法を理解しようとするのではなく、いつでも呼び出すことができるコードで後で参照するための「ラベル」を表します。 モジュールは、PowerShell コードの最終的な「パッケージング」であり、すでに解決した問題で時間を無駄にしないように、同種のコードをグループ化するものです。