もっと詳しく

カスタムPowerShellスクリプトまたは関数を作成していて、ヘルプ情報を追加する必要がありますか？ このガイドでは、そのための手順を説明します。

このガイドの最初のセクションでは、PowerShellスクリプトまたは関数にヘルプを追加する2つの方法を学習します。 次に、2番目のセクションでは、いずれかの方法を使用してスクリプトにヘルプを追加する方法を学習します。

それだけでなく、スクリプトや関数にヘルプを追加することに関してよくある質問に答えるFAQセクションもあります。

PowerShellヘルプの概要

PowerShellコマンドレットの構文とパラメーターに関する情報が必要な場合は、Get-Helpコマンドを実行します。 たとえば、Get-ChildItemコマンドレットに関する情報が必要な場合は、以下のコマンドを実行します。

Get-Help Get-ChildItem

これがPowerShellのコマンドの結果です…

PowerShellスクリプトまたは関数にヘルプを追加する方法

スクリーンショットからわかるように、Get-Helpコマンドは、コマンドレットのNAMEとSYNOPSISを返します。 それに加えて、構文、説明、およびGet-ChildItemに関するその他の関連情報も返しました。

この記事の目的は、このヘルプ情報を独自のPowerShellスクリプトまたは関数に追加する方法を説明することです。

最初の例では、スクリプトをPowerShell関数に変換すると、一部の情報が自動的に追加されます。 ただし、このガイドの後半で説明するように、関数にヘルプ情報を追加して、情報の一部を追加する必要があります。

PowerShellスクリプトまたは関数にヘルプを追加する方法は2つあります。

  1. コメントベースのヘルプメソッドを使用する
  2. XMLヘルプファイルを作成する

このガイドでは、コメントベースのヘルプを追加する方法を説明します。 XMLファイルメソッドを使用してヘルプを追加する方法については、次のWebサイトをご覧ください。 コマンドレットヘルプファイルを作成する方法。

最近PowerShellFunctionExplainedを更新したとき、記事の例を使用して関数を作成しました。 関数を呼び出します、 Get-ItemsBetweenDates。

先ほど、関数を作成すると、PowerShellがGet-Helpが返す情報の一部を追加すると述べました。 自動的に追加される情報の1つは、関数のNAMEとSYNTAXです。

したがって、Get-ItemsBetweenDates関数に対してGet-Helpを実行すると、以下のスクリーンショットに示されている情報が得られます。

Get-Help Get-ItemsBetweenDates

上記のコマンドをPowerShellISEで実行しました。 コマンドがはっきりと見えるように、ISEのスクリプトペインを削除しました。

例を使用してPowerShellスクリプトまたは関数にコメントベースのヘルプを追加する方法

では、これらの他のビットをどのように追加しますか？ よろしくお願いします！

答えは、関数のparamブロックの直前に<＃＃>を追加するのと同じくらい簡単です。 正直言って、<＃＃>を追加するだけではありません。

しかし、真剣に、それは本当に簡単です。 PowerShellでは、<＃＃>を使用してコメントブロックを追加します。 これが、PowerShellスクリプトまたは関数にヘルプを追加するこの方法がコメントベースのヘルプと呼ばれる理由です。

これはプロセスを順を追って説明する実践的なガイドなので、まず、Get-ItemsBetweenDates関数にコメントブロックを追加することから始めましょう。

これが完全な関数コードです。 よく見ると、{を開いた後、関数のパラメーターを定義したことがわかります。 

Function Get-ItemsBetweenDates  {

  [CmdletBinding(DefaultParameterSetName="Path")]
  param( 
    [Parameter(ParameterSetName="Path", Mandatory=$true, Position=0)]
    [Parameter(ParameterSetName="File", Mandatory=$true, Position=0)]
    [Parameter(ParameterSetName="Directory", Mandatory=$true, Position=0)]
    [string[]]$Path,
    [Parameter(ParameterSetName="Path", Mandatory=$true, Position=1)]
    [Parameter(ParameterSetName="File", Mandatory=$true, Position=1)]
    [Parameter(ParameterSetName="Directory", Mandatory=$true, Position=1)]
    [int]$NumOfDaysFrom,
    [Parameter(ParameterSetName="Path", Mandatory=$true, Position=2)]
    [Parameter(ParameterSetName="File", Mandatory=$true, Position=2)]
    [Parameter(ParameterSetName="Directory", Mandatory=$true, Position=2)]
    [int]$NumOfDaysTo,
    [Parameter(ParameterSetName="File", Mandatory=$false, Position=3)]
    [switch]$File,
    [Parameter(ParameterSetName="Directory", Mandatory=$false, Position=3)]
    [switch]$Directory
)
BEGIN {
$DateFrom = (Get-Date).AddDays(-$NumOfDaysFrom)
$DateTo = (Get-Date).AddDays(-$NumOfDaysTo)
}
PROCESS {
   IF ($File) {
        $report = Get-ChildItem $Path -File | Where-Object {($_.LastWriteTime -LE $DateTo) -AND ($_.LastWriteTime -GE $DateFrom)} 
    } ELSEIF ($Directory) {
        $report = Get-ChildItem $Path -Directory | Where-Object {($_.LastWriteTime -LE $DateTo) -AND ($_.LastWriteTime -GE $DateFrom) }
} ELSE{
        $report = Get-ChildItem $Path | Where-Object {($_.LastWriteTime -LE $DateTo) -AND ($_.LastWriteTime -GE $DateFrom)}
}
}
END {
   
    $report | Select-Object -property `
   @{Label=”File/Folder Name”;Expression={$_.Name}}, 
   @{Label=”Modified Date”;Expression={$_.LastWriteTime}}


}
}

ヘルプ情報を追加するための最初のステップは、開始{の直後にコメントブロックを追加することです。 更新された関数は次のようになります（コメントブロックを展開して、スクリプトでの形式に合わせました）。 

Function Get-ItemsBetweenDates  {
<# 

#>
  [CmdletBinding(DefaultParameterSetName="Path")]
  param( 
    [Parameter(ParameterSetName="Path", Mandatory=$true, Position=0)]
    [Parameter(ParameterSetName="File", Mandatory=$true, Position=0)]
    [Parameter(ParameterSetName="Directory", Mandatory=$true, Position=0)]
    [string[]]$Path,
    [Parameter(ParameterSetName="Path", Mandatory=$true, Position=1)]
    [Parameter(ParameterSetName="File", Mandatory=$true, Position=1)]
    [Parameter(ParameterSetName="Directory", Mandatory=$true, Position=1)]
    [int]$NumOfDaysFrom,
    [Parameter(ParameterSetName="Path", Mandatory=$true, Position=2)]
    [Parameter(ParameterSetName="File", Mandatory=$true, Position=2)]
    [Parameter(ParameterSetName="Directory", Mandatory=$true, Position=2)]
    [int]$NumOfDaysTo,
    [Parameter(ParameterSetName="File", Mandatory=$false, Position=3)]
    [switch]$File,
    [Parameter(ParameterSetName="Directory", Mandatory=$false, Position=3)]
    [switch]$Directory
)
BEGIN {
$DateFrom = (Get-Date).AddDays(-$NumOfDaysFrom)
$DateTo = (Get-Date).AddDays(-$NumOfDaysTo)
}
PROCESS {
   IF ($File) {
        $report = Get-ChildItem $Path -File | Where-Object {($_.LastWriteTime -LE $DateTo) -AND ($_.LastWriteTime -GE $DateFrom)} 
    } ELSEIF ($Directory) {
        $report = Get-ChildItem $Path -Directory | Where-Object {($_.LastWriteTime -LE $DateTo) -AND ($_.LastWriteTime -GE $DateFrom) }
} ELSE{
        $report = Get-ChildItem $Path | Where-Object {($_.LastWriteTime -LE $DateTo) -AND ($_.LastWriteTime -GE $DateFrom)}
}
}
END {
    $report | Select-Object -property `
   @{Label=”File/Folder Name”;Expression={$_.Name}}, 
   @{Label=”Modified Date”;Expression={$_.LastWriteTime}}
}
}

コメントブロックを追加したので、次のステップは、概要、説明、およびその他の関連するヘルプ情報を追加することです。 これらの項目はヘルプキーワードと呼ばれます。

これらのヘルプ情報を追加する方法を説明する前に、以下の最初のサブセクションを使用して、さまざまなヘルプキーワードについて説明します。 次に、2番目のサブセクションでは、それらを関数に追加する方法を学習します。

PowerShell関数のヘルプキーワード

以下の表に、一般的なヘルプキーワードとその意味を示します。 一般的な方法は、すべて大文字でキーワードを追加することです。

ただし、小文字で追加することはできます。 重要なのは、ピリオド（。）の横にタグ名を追加することです。

PowerShell関数のヘルプキーワード ヘルプキーワードの意味
.SYNOPSIS これを使用して、機能を簡単に説明します。 ここで追加した情報は、Get-Help結果のSYNOPSISフィールドに表示されます
..説明 ここで、関数の詳細な説明を提供します。 Get-Helpコマンドは、ここで追加した情報を「説明」セクションに表示します
.PARAMETER これを使用して、関数で定義した各パラメーターの説明を追加します。 関数にあるパラメーターと同じ数の.PARAMETERタグを含めることができます
。例 このタグを使用して、関数の実行方法を示します。 必要な数の例を追加できます。 Get-Helpを実行すると、.EXAMPLEタグの情報が例1、例2などとして返されます。
.INPUTS .INPUTSタグを使用して、関数が入力として受け入れるオブジェクトの.NETFrameworkクラスを一覧表示します。 .INPUTSはいくつでも追加できます。 ここでの情報は、Get-Help結果のINPUTSセクションに表示されます
.OUTPUTS .INPUTSと似ていますが、今回はこれを使用して、コマンドの実行時に関数が出力として受け入れるオブジェクトの.NETFrameworkクラスを一覧表示します。
。ノート 上記のキーワードのいずれにも当てはまらないその他の関連情報を追加する必要があると思われる場合は、.NOTESタグを使用してください。 ここで追加された情報は、Get-Help結果のNOTESセクションに表示されます
.LINKS このタグを使用して、ユーザーがあなたの機能に関するオンライン情報を見つけることができる関連リンクを追加します。 Get-Helpの結果では、この情報が[関連リンク]セクションに表示されます。

PowerShellスクリプトまたは関数にヘルプキーワードを追加する方法

最後のサブセクションでは、一般的なPowerShell関数のヘルプキーワードについて説明しました。 また、各タグの使用方法についても説明しました。

このセクションでは、ヘルプキーワードを追加する方法を説明します。

PowerShell関数のhelpキーワードの構文から始めましょう。 

<#
.< help keyword>
< help content>
#>

<＃＃>がコメントブロックであることはすでにご存知でしょう。 「。<ヘルプキーワード>」は、前のサブセクションで説明したキーワードのいずれかを表します。

さらに、「<ヘルプコンテンツ>」はあなたが提供する情報です。

それでは、まず、Get-ItemsBetweenDates関数にSYNOPSISを追加します。 これがそれ自体の概要です…

.SYNOPSIS
    Get-ItemsBetweenDates returns files and/or folders with modified dates betwwen two dates in a specified path

そして、ここでそれは関数にあります。 

Function Get-ItemsBetweenDates  {
<# 
.SYNOPSIS
    Get-ItemsBetweenDates returns files and/or folders with modified dates betwwen two dates in a specified path
#>
  [CmdletBinding(DefaultParameterSetName="Path")]
  param( 
    [Parameter(ParameterSetName="Path", Mandatory=$true, Position=0)]
    [Parameter(ParameterSetName="File", Mandatory=$true, Position=0)]
    [Parameter(ParameterSetName="Directory", Mandatory=$true, Position=0)]
    [string[]]$Path,
    [Parameter(ParameterSetName="Path", Mandatory=$true, Position=1)]
    [Parameter(ParameterSetName="File", Mandatory=$true, Position=1)]
    [Parameter(ParameterSetName="Directory", Mandatory=$true, Position=1)]
    [int]$NumOfDaysFrom,
    [Parameter(ParameterSetName="Path", Mandatory=$true, Position=2)]
    [Parameter(ParameterSetName="File", Mandatory=$true, Position=2)]
    [Parameter(ParameterSetName="Directory", Mandatory=$true, Position=2)]
    [int]$NumOfDaysTo,
    [Parameter(ParameterSetName="File", Mandatory=$false, Position=3)]
    [switch]$File,
    [Parameter(ParameterSetName="Directory", Mandatory=$false, Position=3)]
    [switch]$Directory
)
BEGIN {
$DateFrom = (Get-Date).AddDays(-$NumOfDaysFrom)
$DateTo = (Get-Date).AddDays(-$NumOfDaysTo)
}
PROCESS {
   IF ($File) {
        $report = Get-ChildItem $Path -File | Where-Object {($_.LastWriteTime -LE $DateTo) -AND ($_.LastWriteTime -GE $DateFrom)} 
    } ELSEIF ($Directory) {
        $report = Get-ChildItem $Path -Directory | Where-Object {($_.LastWriteTime -LE $DateTo) -AND ($_.LastWriteTime -GE $DateFrom) }
} ELSE{
        $report = Get-ChildItem $Path | Where-Object {($_.LastWriteTime -LE $DateTo) -AND ($_.LastWriteTime -GE $DateFrom)}
}
}
END {
   
    $report | Select-Object -property `
   @{Label=”File/Folder Name”;Expression={$_.Name}}, 
   @{Label=”Modified Date”;Expression={$_.LastWriteTime}}


}
}

「Get-HelpGet-ItemsBetweenDates」を実行すると、概要が含まれます。

PowerShellスクリプトまたは関数にヘルプキーワードを追加する方法

以下の最後のスクリプトでは、関連するすべてのヘルプキーワードを追加しました。 

Function Get-ItemsBetweenDates  {

<#
.SYNOPSIS
    Get-ItemsBetweenDates returns files and/or folders with modified dates betwwen two dates in a specified path

.DESCRIPTION
    The Get-ItemsBetweenDates allows you to return files or folders that was modified between two dates. 
    When you run the command without specifying the -File or Directory parameters, Get-ItemsBetweenDates
    returns all files and folders that meet the modifed date range criteria. 
.PARAMETER Path
    Specifies the path to the folder you want Get-ItemsBetweenDates to return items from. 
    This parameter accepts wildcards. See examples for details.
.PARAMETER NumOfDaysFrom
    This will be the earliest number of days from today that you want to return files with modified dates.
    Specifiy this in numbers, NOT dates. 
.PARAMETER NumOfDaysTo
    This will be the latest number of days from today that you want to return files with modified dates.
    Like the NumOfDaysFrom parameter, specify a number. Note that NumOfDaysTo MUST be smaller than
    NumOfDaysFrom
.PARAMETER File
    This is a Switch parameter type. By default, Get-ItemBetweenDates returns both files and folders. 
    However, if a user wants this function to return only files, the user will include the File parameter
.PARAMETER Directory
    Like the File parameter, this is also a Switch parameter type. 
    If a user wants this function to return only folders, the user will include Directory.
    Note that you cannot specify File and Directory parameters in the same command.
    You can either specify File or Directory in one command. 
.EXAMPLE
   If you want to return the files and folders that were modified between 5 days ago
   and 30 days ago, run the command below:
   
   Get-ItemsBetweenDates -Path D:PS-Tutorial* -NumOfDaysFrom 30 -NumOfDaysTo 5

   The command displays a result similar to the one below:

   File/Folder Name    Modified Date      
    ----------------    -------------      
    about_Operators.txt 14/06/2022 14:55:33

.EXAMPLE 
    To display files last updated between two dates, run the commmand below:

    Get-ItemsBetweenDates -Path D:PS-Tutorial -NumOfDaysFrom 30 -NumOfDaysTo 0 -File. 
    The command will display just files. Here is the result of my command:

    File/Folder Name    Modified Date      
    ----------------    -------------      
    about_Operators.txt 14/06/2022 14:55:33
    NE-Null.txt         18/06/2022 15:55:23

.EXAMPLE 
    To display folders last updated between two dates, run the commmand below:

    Get-ItemsBetweenDates -Path D:PS-Tutorial -NumOfDaysFrom 30 -NumOfDaysTo 0 -Directory. 
    The command will display just folders. Here is the result of my command:

    File/Folder Name Modified Date      
    ---------------- -------------      
    Stanley          18/06/2022 14:31:46

.LINK
    
PowerShell Function (Advanced) Explained With Examples

    https://www.itechguides.com/powershell-find-files-modified-between-dates
#>

  [CmdletBinding(DefaultParameterSetName="Path")]
  param( 
    [Parameter(ParameterSetName="Path", Mandatory=$true, Position=0)]
    [Parameter(ParameterSetName="File", Mandatory=$true, Position=0)]
    [Parameter(ParameterSetName="Directory", Mandatory=$true, Position=0)]
    [string[]]$Path,
    [Parameter(ParameterSetName="Path", Mandatory=$true, Position=1)]
    [Parameter(ParameterSetName="File", Mandatory=$true, Position=1)]
    [Parameter(ParameterSetName="Directory", Mandatory=$true, Position=1)]
    [int]$NumOfDaysFrom,
    [Parameter(ParameterSetName="Path", Mandatory=$true, Position=2)]
    [Parameter(ParameterSetName="File", Mandatory=$true, Position=2)]
    [Parameter(ParameterSetName="Directory", Mandatory=$true, Position=2)]
    [int]$NumOfDaysTo,
    [Parameter(ParameterSetName="File", Mandatory=$false, Position=3)]
    [switch]$File,
    [Parameter(ParameterSetName="Directory", Mandatory=$false, Position=3)]
    [switch]$Directory
)
BEGIN {
$DateFrom = (Get-Date).AddDays(-$NumOfDaysFrom)
$DateTo = (Get-Date).AddDays(-$NumOfDaysTo)
}
PROCESS {
   IF ($File) {
        $report = Get-ChildItem $Path -File | Where-Object {($_.LastWriteTime -LE $DateTo) -AND ($_.LastWriteTime -GE $DateFrom)} 
    } ELSEIF ($Directory) {
        $report = Get-ChildItem $Path -Directory | Where-Object {($_.LastWriteTime -LE $DateTo) -AND ($_.LastWriteTime -GE $DateFrom) }
} ELSE{
        $report = Get-ChildItem $Path | Where-Object {($_.LastWriteTime -LE $DateTo) -AND ($_.LastWriteTime -GE $DateFrom)}
}
}
END {
   
    $report | Select-Object -property `
   @{Label=”File/Folder Name”;Expression={$_.Name}}, 
   @{Label=”Modified Date”;Expression={$_.LastWriteTime}}


}
}

PowerShellスクリプトまたは関数へのヘルプの追加に関するよくある質問

PowerShellスクリプトまたは関数へのヘルプの追加に関するよくある質問
1. PowerShellでヘルプコマンドを取得するにはどうすればよいですか？

PowerShellコマンドレットを使用してコマンドを実行するための情報を取得するには、Get-Helpコマンドを実行します。 次に、コマンドレットを指定します。

たとえば、Get-Contentコマンドに関するヘルプ情報を取得するには、次のコマンドを実行します。

Get-Help Get-Content

2. PowerShellスクリプトにヘルプを追加するにはどうすればよいですか？

PowerShellスクリプトにヘルプを追加するには、コメントブロック– <＃＃>を入力します。 次に、コメントブロック内に、さまざまなヘルプキーワードを追加します。

たとえば、以下のPowerShellステートメントは、概要、説明、およびパラメーターのヘルプ情報を追加します。

<＃
.SYNOPSIS
<ここに概要ヘルプを追加>
<ここに説明ヘルプを追加>
.PARAMETERパス
<ここにPathパラメータに関する情報を追加>
＃>

3. Get-HelpをPowerShellの最新のヘルプファイルに更新するにはどうすればよいですか？

Get-Helpを更新してPowerShellの最新のヘルプ情報を返すには、Update-Helpコマンドを実行します。

ヘルプファイルを手動でダウンロードして提供する場合を除き、Update-Helpコマンドを正常に実行するには、コンピューターがインターネットに接続されている必要があります。

3. PowerShellでパラメーターをどのように宣言しますか？

PowerShellでパラメーターを宣言するには、paramブロックから始めます。 paramブロックの基本的な構文は次のとおりです。

param（

）。

次に、paramブロック内で、パラメーターを宣言します

param（
$道
）。
これは、paramブロックの非常に基本的な構文です。 PowerShellパラメーターの詳細については、私の記事「PowerShellパラメーター：構文、型、属性、引数、および例」を参照してください。

4. PowerShellスクリプトのコードをどのようにコメントアウトしますか？

PowerShellスクリプトでコードをコメントアウトする方法は2つあります。 1行のコードの前に＃を追加できます。

ただし、コードのブロックをコメントアウトする場合は、コメントブロックを使用することをお勧めします。 たとえば、以下のコメントブロック<＃＃>内のすべての情報は、スクリプトでコメント化されます。

<＃
このブロックのすべての情報が賞賛されます
＃>

5. PowerShellでフィルター処理するにはどうすればよいですか？

PowerShellには、オブジェクトのフィルター処理に使用できる複数のコマンドレットがあります。 フィルタリングに使用できる最も一般的なコマンドレットは、Where-ObjectとSelect-Objectです。

ただし、フィルタリングする対象に応じて、一部のコマンドレットには フィルター パラメータも。 を含むすべてのコマンドレットを一覧表示するには フィルター パラメータ、以下のコマンドを実行します。

Get-Command -ParameterName フィルター

PowerShellスクリプトまたは関数にヘルプを追加することについての私の最終的な考え

PowerShellスクリプトまたは関数にヘルプを追加すると、ユーザーはGet-Help情報を使用してヘルプ情報を表示できます。 コメントベースの方法を使用してヘルプを追加できます。

または、XMLヘルプファイルを作成して、スクリプトまたは関数にヘルプを追加することもできます。

このガイドでは、コメントベースの方法を使用してPowerShellスクリプトまたは関数にヘルプを追加する方法を説明します。

PowerShellスクリプトまたは関数にヘルプを追加するのに役立つことを願っていますか？ また、このガイドがわかりやすく、例が明確であることを願っていますか？

このガイドが役に立ち、理解しやすいと感じた場合は、投票してください はい 「この投稿は役に立ちましたか？」 以下の質問。

Alternativekyでは、PowerShellスクリプトにヘルプを追加して、追加した経験を共有できます。 このページの最後にある「LEAVEAREPLY」フォームを使用できます。

最後に、Windows PowerShellハウツーガイドページに移動して、PowerShellスクリプトの旅を続けます。

参考文献とさらなる読み物

  1. Windows PowerShellパラメーターのヘルプ情報を追加するにはどうすればよいですか？
  2. コマンドレットヘルプファイルを作成する方法
  3. PowerShell関数（高度）を例で説明
  4. コメントベースのヘルプの構文
  5. PowerShellパラメーター：構文、タイプ、属性、引数、および例

The post PowerShellスクリプトまたは関数にヘルプを追加する方法 appeared first on Gamingsym Japan.