快速入門:建立及發佈套件 (dotnet CLI)Quickstart: Create and publish a package (dotnet CLI)

使用 dotnet 命令列介面 (CLI) 從 .NET 類別庫建立 NuGet 套件,並將它發行到 nuget.org 是個簡單的程序。It's a simple process to create a NuGet package from a .NET Class Library and publish it to nuget.org using the dotnet command-line interface (CLI).

必要條件Prerequisites

  1. 安裝 .NET Core SDK,其中包括 dotnet CLI。Install the .NET Core SDK, which includes the dotnet CLI.

  2. 如果您還沒有帳戶,請在 nuget.org 上註冊一個免費帳戶 (英文)。Register for a free account on nuget.org if you don't have one already. 建立新的帳戶會傳送一封確認電子郵件。Creating a new account sends a confirmation email. 您必須確認帳戶,才可以上傳套件。You must confirm the account before you can upload a package.

建立類別庫專案Create a class library project

您可以針對要封裝的程式碼使用現有的 .NET 類別庫專案,或建立一個簡單的專案,如下所示:You can use an existing .NET Class Library project for the code you want to package, or create a simple one as follows:

  1. 建立名為 AppLogger 的資料夾並變更成它。Create a folder called AppLogger and change into it.

  2. 使用 dotnet new classlib 建立專案,它會針對專案使用目前資料夾的名稱。Create the project using dotnet new classlib, which uses the name of the current folder for the project.

將套件中繼資料新增至專案檔Add package metadata to the project file

每個 NuGet 套件都需要資訊清單來描述套件的內容和相依性。Every NuGet package needs a manifest that describes the package's contents and dependencies. 在最後一個套件中,資訊清單是一個 .nuspec 檔案,這是從您納入專案檔中的 NuGet 中繼資料屬性所產生的檔案。In a final package, the manifest is a .nuspec file that is generated from the NuGet metadata properties that you include in the project file.

  1. 開啟專案檔 (.csproj),並在現有的 <PropertyGroup> 標籤內新增下列基本屬性,適當地變更值:Open your project file (.csproj) and add the following minimal properties inside the existing <PropertyGroup> tag, changing the values as appropriate:

    <PackageId>AppLogger</PackageId>
    <Version>1.0.0</Version>
    <Authors>your_name</Authors>
    <Company>your_company</Company>
    

    重要

    為套件指定識別碼,此識別碼在 nuget.org 上或您使用的任何主機上都必須是唯一的。Give the package an identifier that's unique across nuget.org or whatever host you're using. 針對此逐步解說,我們建議在名稱中包含 "Sample" 或 "Test" (如同稍後發行步驟所做的),讓套件能夠成為公開可見的 (儘管實際上不太可能會有人使用它)。For this walkthrough we recommend including "Sample" or "Test" in the name as the later publishing step does make the package publicly visible (though it's unlikely anyone will actually use it).

  2. 新增任何選擇性的屬性,如 NuGet 中繼資料屬性中所述。Add any optional properties described on NuGet metadata properties.

    注意

    針對公眾取用而建置的套件,請特別注意 PackageTags 屬性,因為標籤可協助其他人找到您的套件,並了解其用途。For packages built for public consumption, pay special attention to the PackageTags property, as tags help others find your package and understand what it does.

執行 pack 命令Run the pack command

若要從專案建置 NuGet 套件 (.nupkg 檔案),請執行 dotnet pack 命令,該命令也會自動建置專案:To build a NuGet package (a .nupkg file) from the project, run the dotnet pack command, which also builds the project automatically:

# Uses the project file in the current folder by default
dotnet pack

輸出將顯示 .nupkg 檔案的路徑:The output shows the path to the .nupkg file:

Microsoft (R) Build Engine version 15.5.180.51428 for .NET Core
Copyright (C) Microsoft Corporation. All rights reserved.

  Restore completed in 29.91 ms for D:\proj\AppLoggerNet\AppLogger\AppLogger.csproj.
  AppLogger -> D:\proj\AppLoggerNet\AppLogger\bin\Debug\netstandard2.0\AppLogger.dll
  Successfully created package 'D:\proj\AppLoggerNet\AppLogger\bin\Debug\AppLogger.1.0.0.nupkg'.

建置時自動產生套件Automatically generate package on build

若要在您執行 dotnet build 時自動執行 dotnet pack,請將下列程式行加入專案檔的 <PropertyGroup> 中:To automatically run dotnet pack when you run dotnet build, add the following line to your project file within <PropertyGroup>:

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

發行套件Publish the package

一旦擁有 .nupkg 檔案之後,您會使用 dotnet nuget push 命令以及從 nuget.org 取得的 API 金鑰,將它發行到 nuget.org。Once you have a .nupkg file, you publish it to nuget.org using the dotnet nuget push command along with an API key acquired from nuget.org.

注意

病毒掃描:會掃描所有上傳至 nuget.org 的套件是否有病毒,並在發現任何病毒時予以拒絕。Virus scanning: All packages uploaded to nuget.org are scanned for viruses and rejected if any viruses are found. 也會定期掃描 nuget.org 上列出的所有套件。All packages listed on nuget.org are also scanned periodically.

除非您取消列出已發行至 nuget.org 的套件,否則也會向其他開發人員公開顯示這些套件。Packages published to nuget.org are also publicly visible to other developers unless you unlist them. 若要私下裝載套件,請參閱裝載套件To host packages privately, see Hosting packages.

取得 API 金鑰Acquire your API key

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

  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. 在 [API 金鑰] 底下,針對 [Glob 模式] 輸入 *,然後選取 [建立]。Under API Key, 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 金鑰簡介 (英文) (blogs.nuget.org)。For more information, see Introducing scoped API keys (blogs.nuget.org).

使用 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 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.

發行錯誤Publish errors

來自 push 命令的錯誤通常代表發生問題。Errors from the push command typically indicate the problem. 例如,您可能忘記更新專案中的版本號碼,因而嘗試發行已經存在的套件。For example, you may have forgotten to update the version number in your project and are therefore trying to publish a package that already exists.

當您嘗試使用主機上已經存在的識別碼來發行套件時,也會看到錯誤。You also see errors when trying to publish a package using an identifier that already exists on the host. 例如,名稱 "AppLogger" 已經存在。The name "AppLogger", for example, already exists. 在這種情況下,push 命令會產生下列錯誤:In such a case, the push command gives the following error:

Response status code does not indicate success: 403 (The specified API key is invalid,
has expired, or does not have permission to access the specified package.).

如果您使用剛建立的有效 API 金鑰,則此訊息表示命名衝突,這無法從錯誤的「權限」部分中完全清除。If you're using a valid API key that you just created, then this message indicates a naming conflict, which isn't entirely clear from the "permission" part of the error. 請變更套件識別碼、重新建置專案、重新建立 .nupkg 檔案,然後重試 push 命令。Change the package identifier, rebuild the project, recreate the .nupkg file, and retry the push command.

管理已發行的套件Manage the published package

從您在 nuget.org 上的設定檔,選取 [管理套件] 以查看您剛發行的套件。From your profile on nuget.org, select Manage Packages to see the one you just published. 您也會收到確認電子郵件。You also receive a confirmation email. 請注意,可能需要一些時間才會編製套件的索引,並顯示在其他人可以找到它的搜尋結果中。Note that it might take a while for your package to be indexed and appear in search results where others can find it. 在這段期間,套件頁面會顯示下列訊息:During that time your package page shows the message below:

此套件尚未編製索引。

就是這麼容易!And that's it! 您剛剛已將第一個 NuGet 套件發行至 nuget.org,其他開發人員可以在他們自己的專案中使用它。You've just published your first NuGet package to nuget.org that other developers can use in their own projects.

如果您在本逐步解說中建立的套件不是真的很實用 (例如,使用空類別庫建立的套件),則您應該「取消列出」該套件,以便在搜尋結果中加以隱藏:If in this walkthrough you created a package that isn't actually useful (such as a package created with an empty class library), you should unlist the package to hide it from search results:

  1. 在 nuget.org,選取您的使用者名稱 (頁面右上方),然後選取 [管理套件]。On nuget.org, select your user name (upper right of the page), then select Manage Packages.

  2. 在 [已發行] 下方找出您想要取消列出的套件,然後選取右邊的資源回收筒圖示:Locate the package you want to unlist under Published and select the trash can icon on the right:

    針對 nuget.org 上列出之套件顯示的資源回收筒圖示

  3. 在後續頁面上,清除標籤為 [在搜尋結果中列出 (package-name)] 的方塊,然後選取 [儲存]:On the subsequent page, clear the box labeled List (package-name) in search results and select Save:

    針對 nuget.org 上的套件清除 [列出] 核取方塊