發行套件Publishing packages

建立套件且具有 .nupkg 檔案之後,只要透過簡單的流程,其他開發人員就能使用此套件 (不論公開或私用):Once you have created a package and have your .nupkg file in hand, it's a simple process to make it available to other developers, either publicly or privately:

  • 如本文中所述,所有開發人員都可以透過 nuget.org 全域使用公用套件 (需要 NuGet 4.1.0+)。Public packages are made available to all developers globally through nuget.org as described in this article (requires NuGet 4.1.0+).
  • 私用套件僅適用於小組或組織,方法是將它們裝載在檔案共用、私用 NuGet 伺服器、Azure Artifacts 協力廠商存放庫 (例如 myget、ProGet、Nexus Repository 和 Artifactory)。Private packages are available to only a team or organization, by hosting them either a file share, a private NuGet server, Azure Artifacts, or a third-party repository such as myget, ProGet, Nexus Repository, and Artifactory. 如需其他詳細資料,請參閱裝載套件概觀For additional details, see Hosting Packages Overview.

此文章涵蓋發行至 nuget.org 的方法;若要發行至 Azure Artifacts,請參閱套件管理This article covers publishing to nuget.org; for publishing to Azure Artifacts, see Package Management.

發行至 nuget.orgPublish to nuget.org

針對 nuget.org,您必須使用 Microsoft 帳戶登入,系統會要求您向 nuget.org 註冊該帳戶。您也可以使用以較舊版本的入口網站建立的 nuget.org 帳戶來登入。For nuget.org, you must sign in with a Microsoft account, with which you'll be asked to register the account with nuget.org. You can also sign in with a nuget.org account created using older versions of the portal.

NuGet 登入位置

接下來,您可以透過 nuget.org Web 入口網站上傳套件、從命令列推送至 nuget.org (需要 nuget.exe 4.1.0+),或透過 Azure DevOps Services 在 CI/CD 流程期間發行,如下列各節中所述。Next, you can either upload the package through the nuget.org web portal, push to nuget.org from the command line (requires nuget.exe 4.1.0+) , or publish as part of a CI/CD process through Azure DevOps Services, as described in the following sections.

Web 入口網站:使用 nuget.org 上的 [Upload Package] (上傳套件) 索引標籤Web portal: use the Upload Package tab on nuget.org

  1. 在 nuget.org 的上方功能表中選取 [上傳],並瀏覽至套件位置。Select Upload on the top menu of nuget.org and browse to the package location.

    在 nuget.org 上上傳套件

  2. nuget.org 會告訴您該套件名稱是否可用。nuget.org tells you if the package name is available. 如果不可使用,請在您專案中變更套件識別碼、重建,並再次嘗試上傳。If it isn't, change the package identifier in your project, rebuild, and try the upload again.

  3. 如果套件名稱可用,nuget.org 會開啟 [確認] 區段,您可在其中檢閱套件資訊清單的中繼資料。If the package name is available, nuget.org opens a Verify section in which you can review the metadata from the package manifest. 若要變更任何中繼資料,請編輯您的專案 (專案檔或 .nuspec 檔案)、重建、重新建立套件,然後再次上傳。To change any of the metadata, edit your project (project file or .nuspec file), rebuild, recreate the package, and upload again.

  4. 在 [匯入文件] 底下,您可以貼上 Markdown、使用 URL 指向您的文件,或上傳文件檔案。Under Import Documentation you can paste Markdown, point to your docs with a URL, or upload a documentation file.

  5. 當所有資訊準備就緒時,請選取 [提交] 按鈕When all the information is ready, select the Submit button

命令列Command line

若要將套件推送至 nuget.org,您必須使用 nuget.exe 4.1.0 版或以上版本,以實作必要的 NuGet 通訊協定To push packages to nuget.org you must use nuget.exe v4.1.0 or above, which implements the required NuGet protocols. 您也需要 API 金鑰,這是在 nuget.org 上建立的。You also need an API key, which is created on nuget.org.

建立 API 金鑰Create API keys

  1. 登入 nuget.org 帳戶 (英文),或者,如果您還沒有帳戶,則建立一個帳戶。Sign into your nuget.org account or create an account if you don't have one already.

    如需有關建立帳戶的詳細資訊,請參閱個人帳戶For more information on creating your account, see Individual accounts.

  2. 選取您的使用者名稱 (在右上方),然後選取 [API 金鑰] 。Select your user name (on the upper right), then select API Keys.

  3. 選取 [建立] ,提供金鑰的名稱,選取 [選取範圍] > [推送] 。Select Create, provide a name for your key, select Select Scopes > Push. 針對 [Glob 模式] 輸入 *,然後選取 [建立] 。Enter * for Glob pattern, then select Create. (如需範圍的詳細資訊,請參閱下方)。(See below for more about scopes.)

  4. 建立金鑰之後,選取 [複製] 以擷取 CLI 中您需要的存取金鑰:Once the key is created, select Copy to retrieve the access key you need in the CLI:

    將 API 金鑰複製到剪貼簿

  5. 重要:將您的金鑰儲存在安全的位置,因為您稍後就無法再次複製此金鑰。Important: Save your key in a secure location because you cannot copy the key again later on. 如果您返回 API 金鑰頁面,則需要重新產生金鑰才能加以複製。If you return to the API key page, you need to regenerate the key to copy it. 如果您不再想要透過 CLI 推送套件,也可以移除 API 金鑰。You can also remove the API key if you no longer want to push packages via the CLI.

設定範圍可讓您針對不同用途建立個別的 API 金鑰。Scoping allows you to create separate API keys for different purposes. 每個金鑰都有其到期的時間範圍,且可將範圍設定為特定套件 (或 Glob 模式)。Each key has its expiration timeframe and can be scoped to specific packages (or glob patterns). 每個金鑰也可將範圍設定為特定作業:新套件和更新的推送、僅更新的推送,或取消列入。Each key is also scoped to specific operations: push of new packages and updates, push of updates only, or delisting. 透過設定範圍,您就可針對組織中管理套件的不同人員建立 API 金鑰,讓他們只具有所需的權限。Through scoping, you can create API keys for different people who manage packages for your organization such that they have only the permissions they need. 如需詳細資訊,請參閱限定範圍的 API 金鑰For more information, see scoped API keys.

使用 dotnet nuget push 發行Publish with dotnet nuget push

  1. 變更為包含 .nupkg 檔案的資料夾。Change to the folder containing the .nupkg file.

  2. 執行下列命令,指定套件名稱 (使用套件識別碼) 並使用您的 API 金鑰來取代金鑰值:Run the following command, specifying your package name (unique package ID) and replacing the key value with your API key:

    dotnet nuget push AppLogger.1.0.0.nupkg -k qz2jga8pl3dvn2akksyquwcs9ygggg4exypy3bhxy6w6x6 -s https://api.nuget.org/v3/index.json
    
  3. dotnet 會顯示發行程序的結果:dotnet displays the results of the publishing process:

    info : Pushing AppLogger.1.0.0.nupkg to 'https://www.nuget.org/api/v2/package'...
    info :   PUT https://www.nuget.org/api/v2/package/
    info :   Created https://www.nuget.org/api/v2/package/ 12620ms
    info : Your package was pushed.
    

請參閱 dotnet nuget pushSee dotnet nuget push.

使用 nuget push 發行Publish with nuget push

  1. 在命令提示字元中執行下列命令,將 <your_API_key> 取代為從 nuget.org 取得的金鑰:At a command prompt, run the following command, replacing <your_API_key> with the key obtained from nuget.org:

    nuget setApiKey <your_API_key>
    

    此命令會將您的 API 金鑰儲存在 NuGet 設定中,如此您就不需要在同一部電腦上再次重複此步驟。This command stores your API key in your NuGet configuration so that you don't need to repeat this step again on the same computer.

  2. 使用下列命令,將套件推送至 NuGet 資源庫:Push your package to NuGet Gallery using the following command:

    nuget push YourPackage.nupkg -Source https://api.nuget.org/v3/index.json
    

發行已簽署的套件Publish signed packages

若要提交已簽署的套件,必須先註冊用來簽署套件的憑證To submit signed packages, you must first register the certificate used for signing the packages.

警告

nuget.org 會拒絕不符合簽署的套件需求的套件。nuget.org rejects packages that don't satisfy the signed package requirements.

套件驗證和編製索引Package validation and indexing

推送至 nuget.org 的套件會歷經數次驗證,例如病毒檢查。Packages pushed to nuget.org undergo several validations, such as virus checks. (nuget.org 上的所有套件都會定期掃描)。(All packages on nuget.org are periodically scanned.)

套件通過所有驗證檢查時,可能需要一些時間進行編製索引,並顯示在搜尋結果中。When the package has passed all validation checks, it might take a while for it to be indexed and appear in search results. 編製索引完成之後,您會收到一封電子郵件,確認已成功發行套件。Once indexing is complete, you receive an email confirming that the package was successfully published. 如果套件讓驗證檢查失敗,則會更新套件詳細資料頁面以顯示相關聯的錯誤,而且您也會收到一封電子郵件通知您有關該錯誤。If the package fails a validation check, the package details page will update to display the associated error and you also receive an email notifying you about it.

套件驗證和編製索引通常在 15 分鐘內完成。Package validation and indexing usually takes under 15 minutes. 如果套件發佈所需的時間超出預期,請前往 status.nuget.org,以檢查 nuget.org 是否發生任何中斷。If the package publishing is taking longer than expected, visit status.nuget.org to check if nuget.org is experiencing any interruptions. 如果所有系統都可以正常運作,但未在一個小時內成功發佈套件,請登入 nuget.org,並使用套件頁面上的 [連絡客戶支援] 連結與我們連絡。If all systems are operational and the package hasn't been successfully published within an hour, please login to nuget.org and contact us using the Contact Support link on the package page.

若要查看封裝的狀態,請在 nuget.org 的帳戶名稱底下選取 [管理套件]。驗證完成時,您會收到確認電子郵件。To see the status of a package, select Manage packages under your account name on nuget.org. You receive a confirmation email when validation is complete.

請注意,您的套件進行編製索引可能需要一些時間,並顯示在其他人可以找到它的搜尋結果中;在這段期間,您會在套件頁面上看到下列訊息:Note that it might take a while for your package to be indexed and appear in search results where others can find it, during which time you see the following message on your package page:

指出套件尚未發行的訊息

Azure DevOps Services (CI/CD)Azure DevOps Services (CI/CD)

如果您在持續整合/部署處理序期間,使用 Azure DevOps Services 將套件推送至 nuget.org,則必須在 NuGet 工作中使用 nuget.exe 4.1 或以上版本。If you push packages to nuget.org using Azure DevOps Services as part of your Continuous Integration/Deployment process, you must use nuget.exe 4.1 or above in the NuGet tasks. 於您的組建中使用最新的 NuGet (Microsoft DevOps blog) 上可以找到詳細資料。Details can be found on Using the latest NuGet in your build (Microsoft DevOps blog).

在 nuget.org 上管理套件擁有者Managing package owners on nuget.org

雖然每個 NuGet 套件的 .nuspec 檔案都會定義套件的作者,所以 nuget.org 資源庫不會使用該中繼資料來定義擁有權。Although each NuGet package's .nuspec file defines the package's authors, the nuget.org gallery does not use that metadata to define ownership. 相反地,nuget.org 會將初始擁有權指派給發行套件的人員。Instead, nuget.org assigns initial ownership to the person who publishes the package. 這是已透過 nuget.org UI 上傳套件的已登入使用者,或已搭配使用其 API 金鑰與 nuget SetApiKeynuget push 的使用者。This is either the logged-in user who uploaded the package through the nuget.org UI, or the users whose API key was used with nuget SetApiKey or nuget push.

所有套件擁有者都具有套件的完整權限,包含新增和移除其他擁有者,以及發行更新。All package owners have full permissions for the package, including adding and removing other owners, and publishing updates.

若要變更套件的擁有權,請執行下列動作:To change ownership of a package, do the following:

  1. 使用套件之目前擁有者的帳戶來登入 nuget.org。Sign in to nuget.org with the account that is the current owner of the package.
  2. 選取您的帳戶名稱,選取 [管理套件],然後展開 [已發行的套件]。Select your account name, select Manage packages, and expand Published Packages.
  3. 選取您要管理的套件,然後在右側選取 [管理擁有者]。Select on the package you want to manage, then on the right side select Manage owners.

在這裡,您有數個選項:From here you have several options:

  1. 移除 [目前擁有者] 底下所列的所有擁有者。Remove any owner listed under Current Owners.
  2. 在 [新增擁有者]下,透過輸入其使用者名稱、訊息,並選取 [新增] 來新增擁有者。Add an owner under Add Owner by entering their user name, a message, and selecting Add. 此動作會將含有確認連結的電子郵件傳送給這個新的共同擁有者。This action sends an email to that new co-owner with a confirmation link. 確認之後,該人員具有新增和移除擁有者的完整權限Once confirmed, that person has full permissions to add and remove owners. (確認之後,[目前擁有者] 區段會指出該人員等待核准。)(Until confirmed, the Current Owners section indicates pending approval for that person.)
  3. 若要移轉擁有權 (擁有權變更時,或透過錯誤的帳戶發行套件之後),請新增擁有者,而且在確認擁有權之後,即可從清單中將您移除。To transfer ownership (as when ownership changes or a package was published under the wrong account), add the new owner, and once they've confirmed ownership they can remove you from the list.

若要將擁有權指派給公司或群組,請使用轉寄給適當小組成員的電子郵件別名來建立 nuget.org 帳戶。To assign ownership to a company or group, create a nuget.org account using an email alias that is forwarded to the appropriate team members. 例如,各種 Microsoft ASP.NET 套件都是由 microsoftaspnet 帳戶共同擁有,這可簡化這類別名。For example, various Microsoft ASP.NET packages are co-owned by the microsoft and aspnet accounts, which simply such aliases.

復原套件擁有權Recovering package ownership

套件有時可能沒有作用中的擁有者。Occasionally, a package may not have an active owner. 例如,原始擁有者可能已經離開產生套件的公司、遺失 nuget.org 認證,或資源庫中的更早 Bug 讓套件變成無擁有者。For example, the original owner may have left the company that produces the package, nuget.org credentials are lost, or earlier bugs in the gallery left a package ownerless.

如果您是套件的合法擁有者,而且需要重新獲得擁有權,請使用 nuget.org 上的連絡表,向 NuGet 小組說明您的情況。If you are the rightful owner of a package and need to regain ownership, use the contact form on nuget.org to explain your situation to the NuGet team. 我們接著會遵循確認套件擁有權的程序,包含嘗試透過套件的專案 URL、Twitter、電子郵件或其他方式找出現有擁有者。We then follow a process to verify your ownership of the package, including trying to locate the existing owner through the package's Project URL, Twitter, email, or other means. 但是,如果全部都失敗,則我們可以傳送給您成為擁有者的新邀請。But if all else fails, we can send you a new invite to become an owner.