建立及發行項目

  • 發行項

PowerShell 資源庫是可供您發佈及與更廣大 PowerShell 使用者社群共用穩定的 PowerShell 模組、指令碼及 Desired State Configuration (DSC) 資源的地方。

本文涵蓋準備指令碼或模組並將其發行至「PowerShell 資源庫」的機制和重要步驟。 強烈建議您檢閱發行指導分針 \(英文\)，以了解如何確保您發行的項目將更廣泛地獲得「PowerShell 資源庫」使用者接受。

將項目發行至「PowerShell 資源庫」的最低需求包括：

  • 擁有「PowerShell 資源庫」帳戶及與該帳戶關聯的 API 金鑰
  • 確定您的項目中有「必要的中繼資料」
  • 使用預先驗證工具來確保您的項目已可發行
  • 使用 Publish-Module 和 Publish-Script 命令將項目發行至「PowerShell 資源庫」
  • 對您項目的相關問題與疑慮進行回應

「PowerShell 資源庫」接受 PowerShell 模組和 PowerShell 指令碼。 當我們提到指令碼時，是指本身是單一檔案而不屬於較大模組之一部分的 PowerShell 指令碼。

如需了解如何設定您的「PowerShell 資源庫」帳戶，請參閱建立 PowerShell 資源庫帳戶 \(英文\)。

建立帳戶之後，您可以取得發行項目所需的 API 金鑰。 使用帳戶進行登入之後，您的使用者名稱將會顯示在「PowerShell 資源庫」頁面的頂端，而不會顯示 [註冊]。 按一下您的帳戶名稱就會前往 [我的帳戶] 頁面，您將可以在該頁面找到 API 金鑰。

重要

必須小心保管 API 金鑰，就像對待您的登入和密碼一樣。 您或任何其他使用者只要有了這個金鑰，便可更新「PowerShell 資源庫」中您擁有的所有項目。 建議您定期更新此金鑰，只要使用 [我的帳戶] 頁面上的 [重設金鑰]，即可完成此操作。

「PowerShell 資源庫」會將從指令碼或模組資訊清單所包含之中繼資料欄位取得的資訊，提供給資源庫使用者。 建立或修改要發行至「PowerShell 資源庫」的項目時，針對在項目資訊清單中提供的資訊有一些要求。 強烈建議您檢閱發行指導方針 \(英文\) 的 ＜項目中繼資料＞ (Item Metadata) 一節，以了解如何為您項目的使用者提供最佳資訊。

New-ModuleManifest 和 New-ScriptFileInfo Cmdlet 將會為您建立資訊清單範本，其中會包含所有資訊清單元素的預留位置。

這兩個資訊清單都有對發佈而言相當重要的兩個區段：主索引鍵資料 (Primary Key Data) 及 PrivateData 的 PSData 區域。 PowerShell 模組資訊清單中主索引鍵資料是 PrivateData 區段之外所有的內容。 主索引鍵組會繫結至使用中的 PowerShell 版本，且不支援設為未定義。 PrivateData 支援新增金鑰，因此「PowerShell 資源庫」特定的元素會在 PSData 中。

對您要發行至「PowerShell 資源庫」的項目來說，要填入的最重要資訊清單元素包括：

  • 指令碼或模組名稱 - 這些名稱會取自 .PS1 (適用於指令碼) 或 .PSD1 (適用於模組)。
  • 版本 - 這是必要的主索引鍵，其格式應遵循 SemVer 指導方針。 請參閱「最佳做法」以取得詳細資料。
  • 作者 - 這是必要的主索引鍵，包含要與項目建立關聯的名稱。 請參閱下方的＜作者及擁有者＞。
  • 描述 - 這是必要的主索引鍵，用來簡要說明此項目的功能及使用它時的任何需求
  • ProjectURI - 這是 PSData 中強烈建議使用的 URI 欄位，可提供 GitHub 存放庫的連結，或您在專案上進行開發所在的類似位置
  • 標籤 - 強烈建議您根據其和 PSEditions 及平台的相容性為您的套件加上標籤。 如需詳細資料，請參閱發佈指導方針。

「PowerShell 資源庫」項目的「作者」和「擁有者」是相關的概念，但未必一定相符。 項目「擁有者」是「PowerShell 資源庫」帳戶具有項目維護權限的使用者。 可能會有許多個能夠更新任何項目的「擁有者」。 「擁有者」只有從「PowerShell 資源庫」中才有提供，且如果將項目從一個系統複製到另一個系統，就會遺失擁有者。 「作者」是建置在資訊清單資料中的字串，因此它一律是項目的一部分。 針對來自 Microsoft 產品的項目，建議事項包括：

  • 設定多個擁有者，其中至少有一個是產生項目的小組名稱
  • 將「作者」設為已知的小組名稱 (例如 Azure SDK Team) 或 Microsoft Corporation

預先驗證您的項目

將項目發行至「PowerShell 資源庫」之前，有一些您必須針對程式碼執行的工具：

  • PowerShell 指令碼分析程式：此工具位於「PowerShell 資源庫」中
  • 針對模組，請執行 Test-ModuleManifest，這包含在 PowerShell 中
  • 針對指令碼，請執行 Test-ScriptFileInfo，這隨附於 PowerShell Get

PowerShell 指令碼分析程式 是一個靜態的程式碼分析工具，會掃描您的程式碼以確保它符合基本的 PowerShell 程式碼編寫指導方針。 此工具會識別您程式碼中的一般和重大問題，在開發期間應該定期執行，以協助您備妥項目以供發行。 「PowerShell 指令碼分析工具」會提供識別為「錯誤」、「警告」及「資訊」的問題清單。 您必須解決所有錯誤，才能將項目發行至「PowerShell 資源庫」。 警告需要經過檢閱，且大多數都應該加以解決。 每次在「PowerShell 資源庫」中發行或更新項目時，都會執行「PowerShell 指令碼分析工具」。 「資源庫作業」小組將會連絡項目擁有者來解決所發現的問題。

如果「PowerShell 資源庫」基礎結構無法讀取您項目中的資訊清單資訊，您將無法發行該項目。 Test-ModuleManifest 會捕捉將造成模組在安裝後無法使用的常見問題。 您必須先針對每個模組執行此 Cmdlet，才能將模組發行至「PowerShell 資源庫」。

同樣地，Test-ScriptFileInfo會驗證指令碼中的中繼資料，且必須在發佈到 PowerShell 資源庫前，先在每個指令碼上執行 (與模組分開發佈)。

發行項目

您必須使用 Publish-Script 或 Publish-Module 將項目發行至「PowerShell 資源庫」。 這些命令都需要：

  • 您將發行之項目的路徑。 針對模組，請使用針對您模組命名的資料夾。 如果您指定的資料夾包含同一個模組的多個版本，您就必須指定 RequiredVersion。
  • Nuget API 金鑰。 這是在「PowerShell 資源庫」上 [我的帳戶] 頁面中找到的 API 金鑰。

命令列中大多數其他選項應該都在您要發行之項目的資訊清單資料中，因此您應該不需要在命令中指定它們。

為了避免錯誤，強烈建議您在發佈之前，先使用 -WhatIf -Verbose 來嘗試執行命令。 這將可大幅節省時間，因為每次您發行至「PowerShell 資源庫」時，都必須更新項目資訊清單區段中的版本號碼。

範例為：

  • Publish-Module -Path ".\MyModule" -NugetAPIKey "GUID" -WhatIf -Verbose
  • Publish-Script -Path ".\MyScriptFile.PS1" -NugetAPIKey "GUID" -WhatIf -Verbose

請小心檢閱輸出，如果沒看見任何錯誤或警告，請在不使用 -WhatIf 的情況下重複執行該命令。

系統會對所有發行至「PowerShell 資源庫」的項目進行病毒掃描，並使用「PowerShell 指令碼分析工具」進行分析。 在該時間出現的所有問題都會傳回給發行者來進行解析。

將項目發行至「PowerShell 資源庫」之後，您將必須監看有關項目的意見反應。

  • 請務必監看與用來發行之帳戶相關的電子郵件地址。 使用者及「PowerShell 資源庫作業」小組將會透過提供該帳戶提供意見反應，包括來自 PSSA 或防毒軟體掃描的問題。 如果該電子郵件帳戶無效，或將嚴重問題回報給該帳戶而長時間未獲得解決，系統就可能將項目視為已遭捨棄，而將會如使用規定所述，從「PowerShell 資源庫」中移除。