共用方式為

PowerShellGallery 發佈指導方針和最佳做法

  • 發行項

本文說明Microsoft小組使用的建議步驟，以確保發佈至PowerShell資源庫的套件將受到廣泛採用，並根據PowerShell資源庫如何處理指令清單數據和大量PowerShell資源庫使用者的意見反應，為使用者提供高價值。 遵循這些指導方針發佈的套件可能會安裝、信任及吸引更多使用者。

以下包含哪些專案是適合 PowerShell 資源庫套件的指導方針、哪些選擇性指令清單設定最重要的專案、使用初始檢閱者的意見反應改善程式碼，以及 Powershell 腳本分析器、版本設定模組、檔、測試和範例，以瞭解如何使用您共用的專案。 本檔大部分都遵循發佈 高品質 DSC 資源模組的指導方針。

如需將套件發行至 PowerShell 資源庫的機制，請參閱 建立和發佈套件。

歡迎對這些指導方針的意見反應。 如果您有意見反應，請在我們的 GitHub 檔存放庫中提出問題。

發佈套件的最佳做法

下列最佳做法是 PowerShell 資源庫項目的使用者所說的重要，且會以名義優先順序列出。 遵循這些指導方針的套件更有可能被其他人下載並採用。

  • 使用 PSScriptAnalyzer
  • 包含檔和範例
  • 回應意見反應
  • 提供模組，而不是腳本
  • 提供專案網站的連結
  • 使用相容的 PSEdition（s） 和平台標記您的套件
  • 在模組中包含測試
  • 包含和/或授權條款的連結
  • 簽署您的程序代碼
  • 遵循版本設定的 SemVer 指導方針
  • 使用通用標籤，如 Common PowerShell 資源庫標籤中所述
  • 使用本機存放庫測試發佈
  • 使用 PowerShellGet 發佈

下列各節會簡短討論上述各項。

使用 PSScriptAnalyzer

PSScriptAnalyzer 是可在 PowerShell 程式代碼上運作的免費靜態程式代碼分析工具。 PSScriptAnalyzer 會識別 PowerShell 程式代碼中最常見的問題，而且通常建議如何修正問題。 此工具很容易使用，並將問題分類為錯誤（必須解決嚴重、必須解決）、警告（需要檢閱並應加以解決），以及資訊（值得查看以取得最佳做法）。 所有發佈至 PowerShell 資源庫的套件都會使用 PSScriptAnalyzer掃描，而且任何錯誤都會回報給擁有者，而且必須加以解決。

最佳做法是使用 -Recurse 和 -Severity Warning 來執行 Invoke-ScriptAnalyzer。

檢閱結果，並確定：

  • 您的檔案中會更正或解決所有錯誤。
  • 會檢閱所有警告，並在適用時加以解決。

強烈建議從 PowerShell 資源庫下載套件的使用者執行 PSScriptAnalyzer 並評估所有錯誤和警告。 如果使用者看到 PSScriptAnalyzer所回報的錯誤，使用者很可能會連絡套件擁有者。 如果您的套件保留標示為錯誤的程式代碼有令人信服的理由，請將該資訊新增至您的檔，以避免多次回答相同的問題。

包含檔和範例

檔和範例是確保使用者可以利用任何共享程序代碼的最佳方式。

檔是發佈至 PowerShell 資源庫之套件中最有説明的事情。 使用者通常會略過沒有檔的套件，因為替代方式是閱讀程式代碼以瞭解套件是什麼，以及如何使用它。 有數篇文章說明如何提供 PowerShell 套件的檔，包括：

  • 提供說明的指導方針 如何撰寫 Cmdlet 說明。
  • 建立 Cmdlet 說明，這是任何 PowerShell 腳本、函式或 Cmdlet 的最佳方法。 如需如何建立 Cmdlet 說明的資訊，請從 如何撰寫 Cmdlet 說明開始。 若要在文稿中新增說明，請參閱 關於批注型說明。
  • 許多模組也包含文字格式的檔，例如 MarkDown 檔案。 當 GitHub 中有項目網站時，Markdown 是大量使用的格式時，這特別有用。 最佳做法是使用 GitHub 類別的 Markdown。

範例顯示使用者如何使用套件。 許多開發人員會說，他們會在檔之前查看範例，以瞭解如何使用某些專案。 最佳範例類型會顯示基本用法，加上仿真的實際使用案例，而且程式代碼會經過妥善批注。 發佈至 PowerShell 資源庫之模組的範例應位於模組根目錄下的 Examples 資料夾中。

您可以在 Examples\RegistryResource 資料夾下的 PSDscResource 模組 中找到範例的良好模式。 每個檔案頂端都有四個範例使用案例，其中簡短描述會記錄所示範的內容。

管理相依性

請務必在模組指令清單中指定模組所相依的模組。 這可讓使用者不必擔心安裝您相依性的適當模組版本。 若要指定相依模組，您應該在模組指令清單中使用必要的模組欄位。 這將會先將任何列出的模組載入全域環境，再匯入您的模組，除非它們已經載入。 例如，某些模組可能已經由不同的模組載入。 您也可以使用 RequiredVersion 欄位來指定要載入的特定版本，而不是 ModuleVersion 欄位。 使用 ModuleVersion時，它會載入具有指定版本下限的最新版本。 不使用 [RequiredVersion] 字段時，若要指定特定版本，請務必監視所需模組的版本更新。 請務必注意任何可能影響模組用戶體驗的重大變更。

Example: RequiredModules = @(@{ModuleName="myDependentModule"; ModuleVersion="2.0"; Guid="cfc45206-1e49-459d-a8ad-5b571ef94857"})

Example: RequiredModules = @(@{ModuleName="myDependentModule"; RequiredVersion="1.5"; Guid="cfc45206-1e49-459d-a8ad-5b571ef94857"})

回應意見反應

對意見反應做出適當回應的套件擁有者受到社群的高度評價。 提供建設性意見反應的使用者對於回應很重要，因為他們對套件感興趣，以嘗試改善它。

PowerShell 資源庫中有一個可用的意見反應方法：

  • 聯繫人擁有者：這可讓使用者傳送電子郵件給套件擁有者。 身為套件擁有者，請務必監視與 PowerShell 資源庫套件搭配使用的電子郵件位址，並回應所引發的問題。 此方法的缺點是只有用戶和擁有者才會看到通訊，因此擁有者可能需要多次回答相同的問題。

社群讚賞以建設性方式回應意見反應的業主。 使用報表中的商機來要求更多資訊。 如有需要，請提供因應措施，或識別更新是否修正問題。

如果上述任一通道觀察到不當行為，請使用PowerShell資源庫的「報告濫用」功能來連絡資源庫管理員。

模組與腳本

與其他用戶共用腳本非常出色，並提供其他人如何解決他們可能遇到的問題範例。 問題是 PowerShell 資源庫中的腳本是單一檔案，沒有個別的檔、範例和測試。

PowerShell 模組具有資料夾結構，可讓封裝包含多個資料夾和檔案。 模組結構可讓您包含我們列為最佳做法的其他套件：Cmdlet 說明、檔、範例和測試。 最大的缺點是模組內的腳本必須公開並當做函式使用。 如需如何建立模組的資訊，請參閱 撰寫 Windows PowerShell 模組。

在某些情況下，腳本會為使用者提供更好的體驗，特別是 DSC 設定。 DSC 設定的最佳做法是將設定發佈為包含檔、範例和測試的隨附模組的腳本。 腳本會使用 RequiredModules = @(Name of the Module)列出隨附的模組。 此方法可與任何腳本搭配使用。

遵循其他最佳做法的獨立腳本可為其他使用者提供真正的價值。 將腳本發佈至 PowerShell 資源庫時，強烈建議您提供以批註為基礎的檔和專案網站的連結。

Project 網站是發行者可以直接與其 PowerShell 資源庫套件用戶互動的地方。 使用者偏好提供此套件，因為它可讓他們更輕鬆地取得套件的相關信息。 PowerShell 資源庫中的許多套件都是在 GitHub 中開發，其他套件則由具有專用 Web 狀態的組織提供。 每個專案都可以視為項目網站。

新增連結的方式是在指令清單的 PSData 區段中加入 ProjectURI，如下所示：

  # A URL to the main website for this project.
  ProjectUri = 'https://github.com/powershell/powershell'

提供 ProjectURI 時，PowerShell 資源庫會包含套件頁面左側 [項目網站] 的連結。

使用相容的 PSEdition（s） 和平台標記您的套件

使用下列標籤向使用者示範哪些套件可搭配其環境運作良好：

  • PSEdition_Desktop：與 Windows PowerShell 相容的套件
  • PSEdition_Core：與 PowerShell 6 和更新版本相容的套件
  • Windows：與 Windows 作業系統相容的套件
  • Linux：與 Linux 作業系統相容的套件
  • MacOS：與 Mac 操作系統相容的套件

藉由使用相容的平台標記套件，它將會包含在搜尋結果左窗格的 [資源庫搜尋篩選] 中。 如果您在 GitHub 上裝載套件，當您標記套件時，您也可以利用我們的 PowerShell 資源庫相容性防護相容性防護範例。

包含測試

包含開放原始碼測試對使用者很重要，因為它可保證您驗證的內容，並提供程式碼運作方式的相關信息。 它也允許使用者在修改程式碼以符合其環境時，確保它們不會中斷原始功能。

強烈建議您撰寫測試以利用 Pester 測試架構，此架構專為 PowerShell 所設計。 Pester 可在 GitHub、PowerShell 資源庫取得，隨附於 Windows 10、Windows Server 2016、WMF 5.0 和 WMF 5.1。

GitHub 中的 Pester 專案網站 包含撰寫 Pester 測試的良好檔，從開始使用到最佳做法。

測試涵蓋範圍的目標會在 高品質資源模組檔中指出，建議使用 70% 單元測試程式代碼涵蓋範圍。

發佈至 PowerShell 資源庫的所有套件都必須指定授權條款，或受 使用規定 中所含的授權約束，展覽 A。指定不同授權的最佳方法是使用 PSData中的 LicenseURI，提供授權的連結。 如需詳細資訊，請參閱 套件指令清單和資源庫 UI。

PrivateData = @{
    PSData = @{

        # Tags applied to this module. These help with module discovery in online galleries.
        Tags = @('.net','acl','active-directory')

        # A URL to the license for this module.
        LicenseUri = 'http://www.apache.org/licenses/LICENSE-2.0'

簽署您的程序代碼

程式代碼簽署可為使用者提供發佈套件的最高層級保證，而且他們取得的程式代碼複本正是發行者發行的內容。 若要深入瞭解程式代碼簽署一般，請參閱 程式代碼簽署簡介。 PowerShell 支援透過兩個主要方法驗證程式代碼簽署：

  • 簽署腳本檔案
  • 類別目錄簽署模組

簽署 PowerShell 檔案是一種妥善建立的方法，可確保所執行的程式代碼是由可靠的來源所產生，而且尚未修改。 有關如何簽署 PowerShell 腳本檔案的詳細數據，請參閱關於簽署 一文。 在概觀中，簽章可以新增至 PowerShell 在載入腳本時驗證的任何 .PS1 檔案。 PowerShell 可以使用 執行原則 Cmdlet 來限制，以確保使用已簽署的腳本。

目錄簽署模組是 5.1 版中新增至 PowerShell 的功能。 如何在 目錄 Cmdlet 一文中說明如何簽署模組。 在概觀中，目錄簽署是藉由建立目錄檔案來完成，其中包含模組中每個檔案的哈希值，然後簽署該檔案。

PowerShellGetPublish-Module、Install-Module和 Update-Module Cmdlet 會檢查簽章以確保其有效，然後確認每個套件的哈希值符合目錄中的內容。 Save-Module 不會驗證簽章。 如果系統上已安裝舊版的模組，Install-Module 會確認新版本的簽署授權單位符合先前安裝的授權單位。 如果套件未簽署目錄，Install-Module 和 Update-Module 將會在 .PSD1 檔案上使用簽章。 目錄簽署可搭配使用，但不會取代簽署腳本檔案。 PowerShell 不會在模組載入時驗證類別目錄簽章。

遵循 SemVer 版本設定的指導方針

SemVer 是一項公開慣例，描述如何建構和變更版本，以方便解譯變更。 套件的版本必須包含在指令清單數據中。

  • 版本應該結構化為以句點分隔的三個數值區塊，如 0.1.1 或 4.11.192。
  • 從 0 開始的版本表示套件尚未準備好生產環境，而第一個數字應該只以 0 為開頭，如果這是使用的唯一數位。
  • 第一個數位中的變更（1.9.9999 為 2.0.0），表示版本之間的重大和重大變更。
  • 第二個數字的變更（1.1 為 1.2）表示功能層級的變更，例如將新的 Cmdlet 新增至模組。
  • 第三個數字的變更表示非中斷性變更，例如新的參數、更新的範例或新的測試。
  • 列出版本時，PowerShell 會將版本排序為字串，因此會將 1.01.0 視為大於 1.001.0。

PowerShell 是在發行 SemVer 之前建立的，因此它特別支援 SemVer 的大部分但並非所有元素：

  • 它不支援版本號碼中的發行前版本字串。 當發行者想要在提供版本 1.0.0之後提供新版本的預覽版本時，這非常有用。 未來版本的PowerShell資源庫和 PowerShellGet Cmdlet 都支援此功能。
  • PowerShell 和 PowerShell 資源庫允許具有 1、2 和 4 個區段的版本字串。 許多早期模塊沒有遵循指導方針，而來自Microsoft的產品版本包括組建資訊作為第4個數位區塊（例如 5.1.14393.1066）。 從版本控制的觀點來看，會忽略這些差異。

使用本機存放庫進行測試

PowerShell 資源庫並非設計成測試發佈程序的目標。 測試發佈至 PowerShell 資源庫之端對端程式的最佳方式，是設定及使用您自己的本機存放庫。 這可以透過幾種方式來完成，包括：

  • 使用 GitHub 中的 PS 私人資源庫專案 設定本機 PowerShell 資源庫實例。 此預覽專案將協助您設定PowerShell資源庫的實例，以控制及用於測試。
  • 設定 內部 Nuget 存放庫。 這需要更多工作才能設定，但會有驗證更多需求的優點，特別是驗證 API 密鑰的使用，以及發佈時目標中是否存在相依性。
  • 將檔案分享設定為測試 存放庫，。 這很容易設定，但由於它是檔案共用，因此不會進行上述的驗證。 在此情況下，其中一個潛在的優點是檔案共用不會檢查必要的 API 金鑰，因此您可以使用用來發佈至 PowerShell 資源庫的相同密鑰。

使用上述任何解決方案時，請使用 Register-PSRepository 來定義新的 存放庫，您可以在 Publish-Module的 -Repository 參數中使用。

測試發佈的其他一點：您無法在作業小組的協助下刪除您發佈至 PowerShell 資源庫的任何套件，後者將確認任何專案都取決於您想要發佈的套件。 因此，我們不支援 PowerShell 資源庫作為測試目標，而且會連絡任何執行此動作的發行者。

使用 PowerShellGet 發佈

強烈建議發行者在使用PowerShell資源庫時，使用 Publish-Module 和 Publish-Script Cmdlet。 已建立PowerShellGet，以協助您避免記住從PowerShell資源庫安裝及發佈的相關重要詳細數據。 有時候，發行者已選擇略過 PowerShellGet ，並使用 NuGet 用戶端，或 PackageManagement Cmdlet，而不是 Publish-Module。 有許多細節很容易遺漏，這會導致各種支援要求。

如果有理由無法使用 Publish-Module 或 Publish-Script，請讓我們知道。 在 PowerShellGet GitHub 存放庫中提出問題，並提供造成您選擇 NuGet 或 PackageManagement的詳細數據。

針對發佈至 PowerShell 資源庫的套件，我們發現最成功的方法是：

  • 在開放原始碼項目網站中執行初始開發。 PowerShell 小組使用 GitHub。
  • 使用檢閱者的意見反應和 PowerShell 腳本分析器，讓程式代碼進入穩定狀態。
  • 包含檔，讓其他人知道如何使用您的工作。
  • 使用本機存放庫測試發佈動作。
  • 將穩定或Alpha版本發佈至PowerShell資源庫，請務必包含文件和連結至您的項目網站。
  • 收集意見反應並查看項目網站中的程式碼，然後將穩定的更新發佈至PowerShell資源庫。
  • 在您的專案和模組中新增範例和 Pester 測試。
  • 決定是否要撰寫程式代碼簽署套件。
  • 當您覺得專案已準備好在生產環境中使用時，請將 1.0.0 版本發佈至 PowerShell 資源庫。
  • 繼續收集意見反應，並根據使用者輸入來反覆運算您的程序代碼。