こんにちは。チェシャ男です。(-皿-)
今回は、
【PowerShell の自作関数で使える動詞の種類】
についてご紹介します。
PowerShell で作成した自作モジュールを、いざインポートしてみると「～名前に承認されていない動詞を含むものがあり～」と警告が表示されることがあります。
「この警告って大丈夫なの？」「モジュールの作り方間違えた？」というあなたの疑問にお答えします。
もくじ
モジュールをインポートすると警告が表示された！
あなたも PowerShell に慣れてきたら自作の関数やコマンドレットを記述したモジュールを作成することになるかもしれません。
苦労してモジュールを作成し「いざ！インポート！」した時に、こんな警告が表示されるかもしれません。
警告: モジュール ‘○○○○’
からインポートされたコマンドの中には、名前に承認されていない動詞を含むものがあり、このようなコマンドは検出される可能性
が低くなる場合があります。承認されていない動詞を含むコマンドを見つけるには、Verbose パラメーターを使用してもう一度
Import-Module コマンドを実行してください。承認されている動詞の一覧を表示するには、「Get-Verb」と入力してください。
いきなりこんな文量の警告が表示されたら誰だって焦ります。では上の警告の正体は一体何なんでしょうか。
名前に承認されていない動詞が含まれている
警告を見てみると”承認されていない動詞を含むものがあり“とあります。この承認された動詞というのがカギなんです。
PowerShell は実用性を高めるため、基本的に「コマンドレット」や「関数名」は”動詞-名詞”の形式をしています。さらに、母国語が英語ではなく普段は英語を話さないユーザにでも予測しやすいように使える動詞に一定のルールを制定しています。
この一定のルールに含まれる動詞が”承認された動詞”の事なんです。
確かに PowerShell のコマンドは
- Get-Host
- Get-Item
- Set-Date
- Set-Location
- Test-Connection
- Test-Path
のように同じような体形で連想しやすい動詞が使われていると思いませんか？
※一部の例外はあります。
警告の正体は、「あなたが自作する関数やコマンドレットの名前にも”承認された動詞”を使ってくださいね」というものだったんですね。
※ちなみにこの警告は処理自体に影響があるわけではなく無視しても一応大丈夫です。
承認された動詞を取得する
承認されている動詞の一覧を表示するコマンドレットに
Get-Verb
というものがあります。
[blogcard url=”https://cheshire-wara.com/powershell/ps-help/get-verb-help/”]【コマンドレット】
Get-Verb
【オプション】
-Verb <承認された動詞>
【入力】
なし
【出力】
Selected.Microsoft.PowerShell.Commands.MemberDefinition
【エイリアス】
なし
承認された動詞は何があるの？
承認された動詞を使えと言われても何を使えばいいんだろう。
その疑問にお答えするのが ”Get-Verb” コマンドレットです。
実際に実行してみると…
PS C:\work> Get-Verb Verb Group ---- ----- Add Common Clear Common Close Common Copy Common Enter Common Exit Common Find Common Format Common Get Common Hide Common Join Common Lock Common Move Common New Common Open Common Optimize Common Pop Common Push Common Redo Common Remove Common Rename Common Reset Common Resize Common Search Common Select Common Set Common Show Common Skip Common Split Common Step Common Switch Common Undo Common Unlock Common Watch Common Backup Data Checkpoint Data Compare Data Compress Data Convert Data ConvertFrom Data ConvertTo Data Dismount Data Edit Data Expand Data Export Data Group Data Import Data Initialize Data Limit Data Merge Data Mount Data Out Data Publish Data Restore Data Save Data Sync Data Unpublish Data Update Data Approve Lifecycle Assert Lifecycle Complete Lifecycle Confirm Lifecycle Deny Lifecycle Disable Lifecycle Enable Lifecycle Install Lifecycle Invoke Lifecycle Register Lifecycle Request Lifecycle Restart Lifecycle Resume Lifecycle Start Lifecycle Stop Lifecycle Submit Lifecycle Suspend Lifecycle Uninstall Lifecycle Unregister Lifecycle Wait Lifecycle Debug Diagnostic Measure Diagnostic Ping Diagnostic Repair Diagnostic Resolve Diagnostic Test Diagnostic Trace Diagnostic Connect Communications Disconnect Communications Read Communications Receive Communications Send Communications Write Communications Block Security Grant Security Protect Security Revoke Security Unblock Security Unprotect Security Use Other
かなりずらーっと列挙されましたが、左の Verb 列が承認された動詞の一覧のようです。
あなたが関数やコマンドレットを自作する場合は、この一覧にある動詞から選びましょう。
右側に表示された Group とは？
承認済みの動詞は検索や比較をしやすくするために一定の条件でグルーピングされて割り当てられています。
「それぞれの動詞がどんな意味でどんな場面で使われるべきか」についてがグループで定義されているんですね。
それぞれのグループについては下表をご覧ください。
| グループ | 動詞の種類 |
| Common(共通) | 「Add」など、ほぼすべてのコマンドレットに適用できる汎用アクションを定義します。 |
| Communications(通信) | 「Connect」などの通信に適用されるアクションを定義します。 |
| Data(データ) | 「Backup」などのデータ処理に適用されるアクションを定義します。 |
| Diagnostic(診断) | 「Debug」などの診断に適用されるアクションを定義します。 |
| Lifecycle(ライフサイクル) | 「Complete」のようなライフサイクルに適用されるアクションを定義します。 |
| Security(セキュリティ) | 「Revoke」のようなセキュリティに適用されるアクションを定義します。 |
| Other(その他) | その他のタイプのアクションを定義します。 |
コマンド名を決めるときもいろいろと考えないといけないんですね～。
では実際に自作モジュールを作り、「承認された動詞」と「承認されていない動詞」の違いを見てみましょう。
承認されていない動詞を使って名前付け
まずは承認されていない動詞の場合です。自作したモジュールはこちらです。
function Hoge-Message
{
[CmdletBinding()]
param(
[Parameter(Mandatory = $True) ][System.String] $Message
)
Process
{
Write-Host -Object "入力メッセージは $Message"
}
}
Export-ModuleMember -Function *
Hoge ってそもそも動詞ですらないですね 笑
Import-Module で実際にインポートしてみると
PS C:\work> Import-Module .\HogeMod.psm1 警告: モジュール 'HogeMod' からインポートされたコマンドの中には、名前に承認されていない動詞を含むものがあり、このようなコマンドは検出される 可能性が低くなる場合があります。承認されていない動詞を含むコマンドを見つけるには、Verbose パラメーターを使用して もう一度Import-Module コマンドを実行してください。承認されている動詞の一覧を表示するには、「Get-Verb」と入力してください。
とこのように警告が表示されましたね。”Verbose” パラメータを使用すると承認されていない動詞が使われている場所を教えてくれるみたいです。
PS C:\work> Import-Module .\HogeMod.psm1 -Verbose 警告: モジュール 'HogeMod' からインポートされたコマンドの中には、名前に承認されていない動詞を含むものがあり、このようなコマンドは検出される 可能性が低くなる場合があります。承認されていない動詞を含むコマンドを見つけるには、Verbose パラメーターを使用して もう一度Import-Module コマンドを実行してください。承認されている動詞の一覧を表示するには、「Get-Verb」と入力してください。 詳細: 'HogeMod' モジュールの 'Hoge-Message' コマンドがインポートされましたが、承認されている動詞がコマンド名に含まれていないため、見つけにくい場合があります。 承認されている動詞の一覧については、「Get-Verb」を入力してください。 詳細: 関数 'Hoge-Message' をインポートしています。
確かに ‘Hoge-Message‘ 関数が悪いと教えてくれました。非常に親切です。
ちなみに、あくまで警告ですのでこの状態でも作成した関数使用することができます。
PS C:\work> #関数が読み込まれていることを確認 PS C:\work> Get-Command -Name Hoge-Message CommandType Name Version Source ----------- ---- ------- ------ Function Hoge-Message 0.0 HogeMod PS C:\work> #関数を使ってみる PS C:\work> Hoge-Message -Message "HogeFuga" 入力メッセージは HogeFuga
承認された動詞を使って名前付け
次に承認された動詞の場合です。自作したモジュールはこちらです。
function Write-Message
{
[CmdletBinding()]
param(
[Parameter(Mandatory = $True) ][System.String] $Message
)
Process
{
Write-Host -Object "入力メッセージは $Message"
}
}
Export-ModuleMember -Function *
ご覧のように、今回は”Write”を使用しました。
PS C:\work> Get-Verb -verb Write Verb Group ---- ----- Write Communications
Communications グループに属している承認された動詞ですね。
この状態でモジュールをインポートしてみましょう。
PS C:\work> #インポートする PS C:\work> Import-Module .\HogeMod.psm1 -Verbose 詳細: 関数 'Write-Message' をインポートしています。 PS C:\work> #関数の読み込みを確認 PS C:\work> Get-Command -Name Write-Message CommandType Name Version Source ----------- ---- ------- ------ Function Write-Message 0.0 HogeMod PS C:\work> #関数を使ってみる PS C:\work> Write-Message "HogeFyga" 入力メッセージは HogeFyga
結果のように、問題なくインポートすることができています。読み込ませた関数も問題なく実行できていますね。
このように、インポート時の警告を回避するためには自作関数・コマンドレットに対し”承認された動詞”を使って名前付けする必要があります。
まとめ
自作関数や自作コマンドレットを作成する場合、
承認された動詞
を使って名前付けをする。
承認された動詞を確認するには
Get-Verb
を実行する。
ただし、警告のままでも実行することはできる。