about_Modules
適用対象: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0
トピック
about_Modules
簡単な説明
Windows PowerShell モジュールをインストール、インポート、使用する方法について説明します。
詳細な説明
モジュールは、コマンドレット、プロバイダー、関数、ワークフロー、変数、エイリアスといった Windows PowerShell コマンドが含まれるパッケージです。
コマンドの作成者は、モジュールを利用してコマンドを整理したり、他者と共有したりできます。モジュールを受け取ったら、モジュールのコマンドを Windows PowerShell セッションに追加し、組み込みコマンドのように使用できます。
このトピックでは Windows PowerShell モジュールの使用方法について説明します。Windows PowerShell モジュールを記述する方法については、MSDN (Microsoft Developer Network) ライブラリの「Writing a Windows PowerShell Module」 (Windows PowerShellモジュールの記述) (https://go.microsoft.com/fwlink/?LinkId=144916) を参照してください。
モジュールとは
モジュールとはコマンドのパッケージです。セッションのすべてのコマンドレットとプロバイダーはモジュールまたはスナップインにより追加されます。
モジュールの新機能: モジュールの自動読み込み
Windows PowerShell 3.0 より、Windows PowerShell はインストールしたモジュールのコマンドを初めて使用するとき、モジュールを自動的にインポートするようになりました。今後は設定やプロファイル構成なしでモジュールのコマンドを使用できます。そのため、コンピューターにモジュールをインストールした後はモジュールを管理する必要がありません。
また、モジュールのコマンドが見つけやすくなりました。Get-Command コマンドレットでインストールされているすべてのモジュールのすべてのコマンドが、たとえセッションで使用されていなくても取得されるようになりました。そのため、インポートしなくてもコマンドを見つけて起動できます。
次のコマンドはいずれもモジュールをセッションにインポートします。
#Run the command
Get-Mailbox –Identity Chris
#Get the command
Get-Command Get-Mailbox
#Get help for the command
Get-Help Get-Mailbox
ワイルドカード文字 (*) を含む Get-Command コマンドは、使用目的ではなく検出目的のコマンドとして見なされ、モジュールをインポートしません。
PSModulePath 環境変数により指定される場所に保存されるモジュールのみが自動的にインポートされます。他の場所のモジュールは Import-Module コマンドレットを起動してインポートする必要があります。
また、Windows PowerShell プロバイダーを使用するコマンドでモジュールが自動的にインポートされることはありません。たとえば Get PSSessionConfiguration コマンドレットなどの WSMan: ドライブを必要とするコマンドを使用する場合、Import-Module コマンドレットを実行して WSMan: ドライブを含む Microsoft.WSMan.Management モジュールをインポートしなければならない場合があります。
引き続き、Import-Module コマンドを実行してモジュールをインポートし、$PSModuleAutoloadingPreference 変数を使用してモジュールの自動インポートを有効化、無効化、構成できます。詳細については、about_Preference_Variables を参照してください。
モジュールの使用方法
モジュールを使用するには、次のタスクを実行してください。
1. モジュールをインストールします。(多くの場合、これは自動的に行われます。)
2. モジュールにより追加されたコマンドを見つけます。
3. モジュールにより追加されたコマンドを使用します。
このトピックではこれらのタスクの実行方法について説明します。モジュールの管理に関して役に立つその他の情報も含まれています。
モジュールのインストール方法
ファイルが入っているフォルダーとしてモジュールを受け取った場合、それを Windows PowerShell で使用する前に、コンピューターにインストールする必要があります。
ほとんどのモジュールは自動的にインストールされます。Windows PowerShell にはいくつかのモジュールがあらかじめインストールされており、それらは "コア" モジュールと呼ばれることがあります。Windows ベースのコンピューターで、オペレーティング システムに含まれている機能にコア モジュールを管理するコマンドレットがあれば、これらのモジュールはプレインストールされています。たとえばサーバー マネージャーの役割と機能の追加ウィザードや、コントロール パネルの Windows の機能の有効化または無効化ダイアログ ボックスを使用して Windows の機能をインストールすると、その機能の一部であるあらゆる Windows PowerShell モジュールがインストールされます。他にも多くのモジュールが、モジュールをインストールするインストーラーまたはセットアップ プログラムで提供されます。
モジュール フォルダーをインストールするには:
1. 現在のユーザーにモジュール ディレクトリがない場合、それを作成します。
モジュール ディレクトリを作成するには、次のように入力します。
New-Item -Type Directory -Path $home\Documents\WindowsPowerShell\Modules
2. モジュール フォルダー全体をモジュール ディレクトリにコピーします。
フォルダーはどのような方法でコピーしても構いません。エクスプローラーや Cmd.exe、Windows PowerShell などを利用できます。
Windows PowerShell では、Copy-Item コマンドレットを使用します。たとえば、C:\ps-test\MyModule から Modules ディレクトリに MyModule フォルダーをコピーするには、次のように入力します。
Copy-Item -Path c:\ps-test\MyModule -Destination $home\Documents\WindowsPowerShell\Modules
モジュールはどこにインストールしても構いませんが、モジュールの既定の場所にモジュールをインストールすれば、管理しやすくなります。モジュールの既定の場所に関する詳細については、「モジュールと DSC リソースの場所およびPSMODULEPATH」セクションを参照してください。
インストールしたモジュールを見つける方法
モジュールの既定の場所にインストールしていて、まだセッションにインポートしていないモジュールを見つけるには、次のように入力します。
Get-Module -ListAvailable
セッションに既にインポートしたモジュールを見つけるには、Windows PowerShell プロンプトで次のように入力します。
Get-Module
Get-Module コマンドレットに関する詳細については、Get-Module を参照してください。
モジュールのコマンドを見つける方法
利用できるすべてのコマンドを見つけるには Get-Command コマンドレットを使用します。Get-Command コマンドレットのパラメーターを使用し、モジュール別、名前別、名詞別などでコマンドを絞り込めます。
モジュールのすべてのコマンドを見つけるには、次のように入力します。
Get-Command -Module <module-name>
たとえば、BitsTransfer モジュールでコマンドを見るには、次のように入力します。
Get-Command -Module BitsTransfer
Get-Command コマンドレットに関する詳細については、Get-Command を参照してください。
モジュールのコマンドのヘルプを取得する方法
モジュールにそれがエクスポートするコマンドのヘルプ ファイルが含まれている場合、Get-Help コマンドレットでヘルプ トピックが表示されます。Windows PowerShell のコマンドのヘルプを取得する場合と同じ Get-Help コマンド形式を使用します。
Windows PowerShell 3.0 より、モジュールのヘルプ ファイルをダウンロードし、ヘルプ ファイルの更新内容をダウンロードできるようになりました。そのため、古いヘルプが表示されることはありません。
モジュールのコマンドのヘルプを取得するには、次のように入力します。
Get-Help <command-name>
モジュールのコマンドのヘルプをオンラインで取得するには、次のように入力します。
Get-Help <command-name> -Online
モジュールのコマンドのヘルプ ファイルをダウンロードおよびインストールするには、次のように入力します。
Update-Help –Module <module-name>
詳細については、Get-Help および Update-Help を参照してください。
モジュールのインポート方法
モジュールまたはモジュール ファイルのインポートが必要となることがあります。PSModulePath 環境変数 ($env:PSModulePath) によって指定される場所にモジュールをインストールしないとき、あるいは、フォルダーとして提供される一般的なモジュールではなく、.dll ファイルや .psm1 ファイルなど、ファイルでモジュールが構成されているとき、インポートが必要になります。
また、場合によっては、Prefix パラメーターや NoClobber パラメーターなど、Import-Module コマンドのパラメーターを使用できるようにモジュールのインポートを選択します。Prefix パラメーターは、インポートしたすべてのコマンドの名詞名に特徴のある接頭辞を追加します。NoClobber パラメーターは、セッションの既存のコマンドを非表示にしたり、置き換えたりするコマンドの追加をモジュールに禁止します。
モジュールをインポートするには、Import-Module コマンドレットを使用します。
場所 PSModulePath にあるモジュールを現在のセッションにインポートするには、次のコマンド形式を使用します。
Import-Module <module-name>
たとえば、次のコマンドでは、現在のセッションに BitsTransfer モジュールをインポートします。
Import-Module BitsTransfer
モジュールの既定の場所にないモジュールをインポートするには、コマンドにモジュール フォルダーの完全修飾パスを使用します。
たとえば、C:\ps-test ディレクトリの TestCmdlets モジュールをセッションに追加するには、次のように入力します。
Import-Module c:\ps-test\TestCmdlets
モジュール フォルダーに含まれていないモジュール ファイルをインポートするには、コマンドでモジュール ファイルの完全修飾パスを使用します。
たとえば、C:\ps-test ディレクトリの TestCmdlets.dll モジュールをセッションに追加するには、次のように入力します。
Import-Module c:\ps-test\TestCmdlets.dll
モジュールをセッションに追加する方法の詳細については、Import-Module を参照してください。
モジュールをすべてのセッションにインポートする方法
Import-Module コマンドは現在の Windows PowerShell セッションにモジュールをインポートします。このコマンドは現在のセッションのみに影響します。
起動するすべての Windows PowerShell セッションにモジュールをインポートするには、Import-Module コマンドを Windows PowerShell プロファイルに追加します。
プロファイルに関する詳細については、about_Profiles を参照してください。
モジュールの削除方法
モジュールを削除すると、モジュールが追加したコマンドがセッションから削除されます。
セッションからモジュールを削除するには、次のコマンドの形式を使用します。
Remove-Module <module-name>
たとえば、次のコマンドでは、現在のセッションから BitsTransfer モジュールを削除します。
Remove-Module BitsTransfer
モジュールの削除では、モジュールのインポートの反対の操作が行われます。モジュールを削除してもモジュールはアンインストールされません。Remove-Module コマンドレットに関する詳細については、Remove-Module を参照してください。
モジュールと DSC リソースの場所および PSMODULEPATH
Windows PowerShell モジュールの既定の場所は、以下のとおりです。Windows PowerShell 4.0 から、DSC の導入により、新しい既定モジュールと DSC リソース フォルダーが導入されました。DSC の詳細については、about_DesiredStateConfiguration を参照してください。
システム:
$pshome\Modules (%windir%\System32\WindowsPowerShell\v1.0\Modules) システム モジュールは Windows と Windows PowerShell の出荷時に導入されています。
Windows PowerShell 4.0 で Windows PowerShell Desired State Configuration (DSC) が導入されてから、Windows PowerShell に含まれる DSC リソースは、$pshome\Modules の $pshome\Modules\PSDesiredStateConfiguration\DSCResources フォルダーにも保存されます。
現在のユーザー:
$home\Documents\WindowsPowerShell\Modules (%UserProfile%\Documents\WindowsPowerShell\Modules)
- または -
$home\My Documents\WindowsPowerShell\Modules (%UserProfile%\My Documents\WindowsPowerShell\Modules) この場所に Windows PowerShell 4.0 以前のユーザー追加モジュールが保存されています。
Windows PowerShell 4.0 やそれ以降にリリースされた Windows PowerShell では、ユーザー追加モジュールや DSC リソースは C:\Program Files\WindowsPowerShell\Modules に保存されます。この場所のモジュールおよび DSC リソースは、コンピューターのすべてのユーザーがアクセスできます。DSC エンジンはローカル システムとして実行され、$home\Documents\WindowsPowerShell\Modules などのユーザー固有のパスにアクセスできないため、この変更が必要でした。
注記:
%Windir%\System32 ディレクトリ内のファイルを追加または変更するには、"管理者として実行" オプションを使用して Windows PowerShell を起動します。
システム モジュールの既定の場所を変更するには、PSModulePath 環境変数 ($Env:PSModulePath) を変更します。PSModulePath 環境変数は Path 環境変数に基づきモデル化されており、形式が同じです。
モジュールの既定の場所を表示するには、次のように入力します。
$env:psmodulepath
モジュールの既定の場所を追加するには、次のコマンド形式を使用します。
$env:psmodulepath = $env:psmodulepath + ";<path>"
コマンドのセミコロン (;) は、新しいパスと先行するパスを列挙する区切りとして用いられます。
たとえば、"C:\ps-test\Modules" ディレクトリを追加するには、次のように入力します。
$env:psmodulepath + ";c:\ps-test\Modules"
パスを PSModulePath に追加すると、Get-Module コマンドと Import-Module コマンドにそのパスのモジュールが含まれます。
設定した値は現在のセッションのみに影響します。変更を永続化するには、コマンドを Windows PowerShell プロファイルに追加するか、コントロール パネルのシステムを使用し、レジストリの PSModulePath 環境変数の値を変更します。
また、変更を永続化するために、System.Environment クラスの SetEnvironmentVariable メソッドを使用し、Path を PSModulePath 環境変数に追加できます。
PSModulePath 変数の詳細については、about_Environment_Variables を参照してください。
モジュールと名前の競合
名前の競合は、セッションの複数のコマンドの名前が同じときに発生します。モジュールのコマンドの名前がセッションのコマンドまたはアイテムの名前と同じとき、モジュールをインポートすると名前の競合が発生します。
名前が競合していると、コマンドが表示されなかったり、置き換えられたりします。
-- 非表示の場合。名前をキーボードから入力して実行できるコマンドと表示されているコマンドが異なる場合、一方が非表示になっていますが、別の方法でも実行できます。たとえば、コマンドの出所となったモジュールまたはスナップインの名前でコマンド名を修飾します。
-- 置き換えられている場合。コマンドが同じ名前のコマンドで上書きされていて実行できない場合、コマンドは置き換えられています。競合を引き起こしたモジュールを削除しても、セッションを再起動しなければ、置き換えられたコマンドは実行できません。
Import-Module では、現在のセッションのコマンドを隠したり置き換えたりするコマンドが追加される場合があります。また、セッションのコマンドはモジュールが追加したコマンドを隠すことがあります。
名前の競合を検出するには、Get-Command コマンドレットの All パラメーターを使用します。Windows PowerShell 3.0 より、Get-Command を実行すると、コマンド名をキーボード入力して実行されるコマンドのみが取得されます。All パラメーターにより、セッションの特定の名前のコマンドがすべて取得されます。
名前の競合を防ぐには、Import-Module コマンドレットの NoClobber パラメーター または Prefix パラメーターを使用します。Prefix パラメーターを使用すると、インポートされたコマンドの名前に接頭辞が追加され、セッションで一意となります。NoClobber パラメーターを使用すると、セッションの既存のコマンドを隠す、または置き換えるコマンドはインポートされません。
Import-Module の Alias、Cmdlet、Function、Variable パラメーターを使用し、インポートするコマンドだけを選択することもできます。セッションで名前の競合を引き起こすコマンドを除外できます。
モジュールの作成者は、モジュール マニフェストの DefaultCommandPrefix プロパティを使用し、既定の接頭辞をすべてのコマンド名に追加することで名前の競合を回避できます。Prefix パラメーターの値は DefaultCommandPrefix の値に優先します。
コマンドが非表示でも、そのコマンドの出所のモジュールまたはスナップインの名前でコマンド名を修飾すればコマンドを実行できます。
Windows PowerShell のコマンドの優先順位ルールにより、セッションに同じ名前のコマンドが含まれるときに実行されるコマンドが決まります。
たとえば、セッションに同じ名前の関数とコマンドレットが含まれる場合、Windows PowerShell は既定で関数を実行します。セッションに種類と名前が同じコマンドが含まれるとき、たとえば、2 つのコマンドレットの名前が同じ場合、既定では追加された日が新しいほうのコマンドが実行されます。
優先順位ルールの説明や隠れコマンドの実行方法など、詳しくは about_Command_Precedence を参照してください。
モジュールとスナップイン
モジュールとスナップインからセッションにコマンドを追加できます。モジュールはコマンドレット、プロバイダー、関数などのあらゆる種類のコマンドと、変数、エイリアス、Windows PowerShell ドライブなどのあらゆるアイテムを追加できます。スナップインはコマンドレットとプロバイダーのみを追加できます。
モジュールまたはスナップインをセッションから削除する前に、次のコマンドを利用し、削除するコマンドを決定します。
セッションでコマンドレットのソースを検索するには、次のコマンドの形式を使用します。
get-command <cmdlet-name> | format-list -property verb, noun, pssnapin, module
たとえば、Get-date コマンドレットのソースを検索するには、次のように入力します。
get-command get-date | format-list -property verb, noun, pssnapin, module
Windows PowerShell スナップインの詳細については、about_PSSnapins を参照してください。
モジュールに関連する警告およびエラー
モジュールがエクスポートするコマンドは、Windows PowerShell のコマンド命名規則に従う必要があります。インポートしたモジュールによって、承認されていない動詞が名前に含まれているコマンドレットまたは関数がエクスポートされた場合に、Import-Module コマンドレットによって次の警告メッセージが表示されます。
警告: インポートされたコマンド名の中には、承認されていない動詞を含むものがあり、このようなコマンドは検出される可能性が低くなる場合があります。詳細については Verbose パラメーターを使用するか、「Get-Verb」と入力して承認されている動詞の一覧を参照してください。
このメッセージは、単なる警告です。実際には、規則に準拠しないコマンドを含む、モジュール全体がインポートされます。モジュール ユーザーに警告メッセージが表示されますが、名前付けの問題はモジュール作成者が解決する必要があります。
警告メッセージを非表示にするには、Import-Module コマンドレットの DisableNameChecking パラメーターを使用します。
組み込み済みのモジュールとスナップイン
Windows PowerShell 2.0 と Windows PowerShell 3.0 以降の古いスタイルのホスト プログラムでは、Windows PowerShell にインストールされているコア コマンドがスナップインでパッケージ化され、すべての Windows PowerShell セッションに自動的に追加されます。
Windows PowerShell 3.0 より、InitialSessionState.CreateDefault2 初期セッション状態 API を実装する、新しいスタイルのホスト プログラムでは、コア コマンドはモジュールでパッケージ化されています。既定では、スナップインである、Microsoft.PowerShell.Core を使用します。
Microsoft.PowerShell.Core スナップインは、既定ですべてのセッションに追加されます。モジュールは初回利用時に自動的に読み込まれます。
注記: New-PSSession コマンドレットで開始されるセッションなどのリモート セッションは古いスタイルのセッションであり、内蔵コマンドはスナップインでパッケージ化されています。
次のモジュール (またはスナップイン) が Windows PowerShell でインストールされます。
Microsoft.PowerShell.Core
Microsoft.PowerShell.Diagnostics
Microsoft.PowerShell.Host
Microsoft.PowerShell.Management
Microsoft.PowerShell.ScheduledJob
Microsoft.PowerShell.Security
Microsoft.PowerShell.Utility
Microsoft.WSMan.Management
PSDesiredStateConfiguration
PSWorkflow
PSWorkflowUtility
ISE
モジュール イベントの記録
Windows PowerShell 3.0 より、Windows PowerShell のモジュールとスナップインにあるコマンドレットや関数の実行イベントを記録できます。その場合、モジュールまたはスナップインの LogPipelineExecutionDetails プロパティを $True に設定します。グループ ポリシー設定の "モジュール ログを有効にする" を使用して、Windows PowerShell のすべてのセッションでモジュール ログの記録を有効にすることもできます。詳細については、about_EventLogs (https://go.microsoft.com/fwlink/?LinkID=113224) とabout_Group_Policy_Settings (https://go.microsoft.com/fwlink/?LinkID=251696) を参照してください。
関連項目
about_Command_Precedence
about_DesiredStateConfiguration
about_EventLogs
about_Group_Policy_Settings
about_PSSnapins
Get-Command
Get-Help
Get-Module
Import-Module
Remove-Module