【Get-Verb】PowerShellで使える動詞は何?モジュール読込時に警告が出る原因

こんにちは。チェシャ男です。(-皿-)

今回は、

【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

を実行する。

ただし、警告のままでも実行することはできる。

コメントを残す

メールアドレスが公開されることはありません。