解譯說明檔內容,並在 PowerShell 中更新本機說明內容
當您找到工作所需的命令時,可以使用其說明檔來瞭解如何使用該命令。 其中一種瞭解方式便是檢閱範例,並嘗試瞭解其使用方式。 不過,範例通常不會涵蓋該命令使用方式的所有可能變化。 瞭解如何解譯說明檔語法可協助您識別指定命令的所有功能。
Get-EventLog 說明
使用 Get-EventLog 的說明作為範例。 如果您在控制台中輸入命令 Get-Help Get-EventLog ,然後按 Enter 鍵,說明會傳回下列語法:
Get-EventLog [-LogName] <String> [[-InstanceId] <Int64[]>] [-After <DateTime>] [-AsBaseObject] [-Before <DateTime>] [-ComputerName <String[]>] [-EntryType {Error | Information | FailureAudit | SuccessAudit | Warning}] [-Index <Int32[]>] [-Message <String>] [-Newest <Int32>] [-Source <String[]>] [-UserName <String[]>] [<CommonParameters>]
Get-EventLog [-AsString] [-ComputerName <String[]>] [-List] [<CommonParameters>]
這兩個文字區塊是 參數集,每個區塊都代表您可以執行命令的方式。 請注意,每個參數集都有許多參數,而且兩者都有數個通用參數。 您無法在集合之間混合和比對參數。 也就是說,如果您決定使用 –List 參數,您也無法使用 –LogName,因為這些參數不會一起出現在相同的參數集中。
–LogName 參數名稱會以方括弧括住,這表示它是位置參數。 您無法在沒有記錄名稱的情況下執行命令。 不過,您不需要輸入 –LogName 參數名稱。 您必須將記錄檔名稱字串當做第一個參數傳遞,因為這是 –LogName 參數出現之說明檔中的位置。 因此,下列兩個命令會提供相同的結果:
Get-EventLog –LogName Application
Get-EventLog Application
正在取得參數名稱
省略參數名稱時請小心,基於幾個原因。 您無法省略每個參數。 例如, -ComputerName 參數不能省略參數名稱。 此外,您可能會很快就無法追蹤項目的位置。 當您提供參數名稱時,參數可以依任何順序顯示,如下列命令所述:
Get-EventLog –ComputerName LON-DC1 –LogName Application –Newest 10
不過,當您省略參數名稱時,必須確定以正確的順序輸入參數。 例如,下列命令無法運作,因為記錄名稱值不會出現在正確的位置:
Get-EventLog –ComputerName LON-DC1 Application
指定多個值
某些參數接受多個值。 在 [語法] 區段中,參數實值型別中的雙方括弧標記法會指定這些參數。 例如:
-ComputerName <string[]>
上述語法表示 –ComputerName 參數可以接受一或多個字符串值。 指定多個值的其中一種方式是使用逗號分隔清單。 除非您的值本身包含逗號或空白字元,例如空格或定位字元,否則您不需要以引號括住值。 例如,使用下列命令來指定多部電腦名稱:
Get-EventLog –LogName Application –ComputerName LON-CL1,LON-DC1
注意
您可以檢閱命令的完整說明,以找到每個參數的詳細資訊。 例如,執行 Get-Help Get-EventLog –Full 以檢閱 Get-EventLog 的完整說明,並注意顯示的其他資訊。 例如,您可以確認 –LogName 參數是必要參數,並出現在第一個位置。
最佳做法: 如果您剛開始使用 Windows PowerShell,請嘗試提供完整的參數名稱,而不是依位置傳遞參數值。 完整的參數名稱可讓命令更容易檢閱和進行疑難排解,而且當您輸入的命令不正確時,可以更容易注意到錯誤。
更新說明
Windows PowerShell 3.0 和更新版本不會隨附說明檔。 相反地,說明檔會以線上服務的形式提供。 Microsoft 撰寫的命令在其擁有的網頁伺服器上裝載其說明檔。 只要作者或廠商正確建置模組,並提供說明檔的線上位置,非 Microsoft 命令有時也會於線上提供。 藉由使用線上模型,撰寫命令的作者 (包括 Microsoft 作者) 可以在一段時間後對其說明檔案進行更正和改善,然後傳遞這些檔案,而不需要建立整個產品更新。
執行 Update-Help 以掃描您的電腦是否有所有已安裝的模組、擷取每個模組的在線說明位置,並嘗試下載其各自的說明檔。 您必須以本機 Administrators 群組的成員身分執行此命令,因為 Windows PowerShell 核心命令說明會儲存在 %systemdir% 資料夾中。 如果無法下載說明,就會顯示錯誤訊息。 在這種情況下,Windows PowerShell 仍會建立命令的預設說明顯示。
Windows PowerShell 預設會下載系統設定語言的說明檔。 如果未提供該語言的說明,Windows PowerShell 預設為 en-US (美式英文) 語言。 您可以使用 Update-Help 的參數來指定要擷取說明的 UICulture,以覆寫此行為。
根據預設,Update-Help 會每 24 小時檢查一次說明檔案,即使您連續多次執行命令也是如此。 若要覆寫此行為,請包含 –Force 參數。
Update-Help 的隨附是 Save-Help。 該項目會下載說明內容,並將內容儲存到您指定的位置。 此功能可讓您將該內容複寫到未連線到網際網路的電腦。 Update-Help 提供參數來指定替代來源位置。 此功能可讓您在未連線到網際網路的電腦上更新說明。
在 Windows PowerShell 4.0 之前,Update-Help 和 Save-Help 只會下載安裝在本機電腦 (您執行命令的位置) 上的 Cmdlet 說明。 在 Windows PowerShell 4.0 和更新版本中,您可以針對安裝在遠端電腦上的模組使用 Save-Help 。