使用 NuGet 注册表

你可以配置 dotnet 命令行接口 (CLI) 以将 NuGet 包发布到 GitHub Packages 并将存储在 GitHub Packages 上的包用作 .NET 项目中的依赖项。

本文内容

注意：这种包类型可能不适用于你的实例，因为站点管理员可以启用或禁用每种支持的包类型。 有关详细信息，请参阅“为企业配置包生态系统支持”。

向 GitHub Packages 验证

GitHub Packages 仅支持使用 personal access token (classic) 进行身份验证。 有关详细信息，请参阅“管理个人访问令牌”。

需要访问令牌才能发布、安装和删除专用、内部和公共包。

可使用 personal access token (classic) 向 GitHub Packages 或 GitHub Enterprise Server API 进行身份验证。 创建 personal access token (classic) 时，可根据需要为令牌分配不同的作用域。 有关 personal access token (classic) 的包相关范围的详细信息，请参阅“关于 GitHub Packages 的权限”。

要在 GitHub Actions 工作流程内向 GitHub Packages 注册表验证，您可以使用：

  • GITHUB_TOKEN 发布与工作流存储库相关联的包。
  • 范围至少为 read:packages 的 personal access token (classic)，用于安装与其他专用存储库（GITHUB_TOKEN 无法访问）关联的包。

在 GitHub Actions 工作流中进行身份验证

在 GitHub Actions 工作流中通过以下命令使用 GITHUB_TOKEN 向 GitHub Packages 进行身份验证，而不是对存储库的 nuget.config 文件中的 personal access token 进行硬编码：

dotnet nuget add source --username USERNAME --password ${{ secrets.GITHUB_TOKEN }} --store-password-in-clear-text --name github "https://nuget.HOSTNAME/NAMESPACE/index.json"

将 NAMESPACE 替换为拥有托管包的存储库的个人帐户或组织的名称。

将 USERNAME 替换为连接到已经过身份验证的源时要使用的用户名。

有关 GitHub Actions 工作流中使用的 GITHUB_TOKEN 的详细信息，请参阅“自动令牌身份验证”。

使用 personal access token 进行身份验证

GitHub Packages 仅支持使用 personal access token (classic) 进行身份验证。 有关详细信息，请参阅“管理个人访问令牌”。

需要访问令牌才能发布、安装和删除专用、内部和公共包。

可使用 personal access token (classic) 向 GitHub Packages 或 GitHub Enterprise Server API 进行身份验证。 创建 personal access token (classic) 时，可根据需要为令牌分配不同的作用域。 有关 personal access token (classic) 的包相关范围的详细信息，请参阅“关于 GitHub Packages 的权限”。

要在 GitHub Actions 工作流程内向 GitHub Packages 注册表验证，您可以使用：

  • GITHUB_TOKEN 发布与工作流存储库相关联的包。
  • 范围至少为 read:packages 的 personal access token (classic)，用于安装与其他专用存储库（GITHUB_TOKEN 无法访问）关联的包。

必须使用具有适当范围的 personal access token (classic) 才可在 GitHub Packages 中发布和安装包。 有关详细信息，请参阅“GitHub Packages 简介”。

要使用 dotnet 命令行接口 (CLI) 向 GitHub Packages 进行身份验证，请在项目目录中创建一个 nuget.config 文件，将 GitHub Packages 指定为 dotnet CLI 客户端的 packageSources 下的源。

必须：

  • 将 USERNAME 替换为 GitHub 上的个人帐户的名称。
  • 将 TOKEN 替换为 personal access token (classic)。
  • 将 NAMESPACE 替换为拥有托管包的存储库的个人帐户或组织的名称。
  • 将 HOSTNAME 替换为 你的 GitHub Enterprise Server 实例 的主机名。

如果实例启用了子域隔离：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <packageSources>
        <clear />
        <add key="github" value="https://nuget.HOSTNAME/NAMESPACE/index.json" />
    </packageSources>
    <packageSourceCredentials>
        <github>
            <add key="Username" value="USERNAME" />
            <add key="ClearTextPassword" value="TOKEN" />
        </github>
    </packageSourceCredentials>
</configuration>

如果实例禁用了子域隔离：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <packageSources>
        <clear />
        <add key="github" value="https://HOSTNAME/_registry/nuget/NAMESPACE/index.json" />
    </packageSources>
    <packageSourceCredentials>
        <github>
            <add key="Username" value="USERNAME" />
            <add key="ClearTextPassword" value="TOKEN" />
        </github>
    </packageSourceCredentials>
</configuration>

发布包

将包发布到 GitHub Packages 的方式包括使用 nuget.config __ 文件进行身份验证，使用包含 GitHub personal access token (classic) 的 --api-key 命令行选项，或者使用可以通过 dotnet 命令行接口 (CLI) 从命令行直接运行的命令。

将 OWNER 替换为你的用户名或公司名称，并将 YOUR_GITHUB_PAT 替换为 personal access token。

dotnet nuget add source --username OWNER --password YOUR_GITHUB_PAT --store-password-in-clear-text --name github "https://nuget.HOSTNAME/OWNER/index.json"

使用 GitHub personal access token 作为 API 密钥发布包

如果还没有用于 GitHub 上帐户的personal access token，请参阅“管理个人访问令牌”。

  1. 创建新项目。 将 PROJECT_NAME 替换为要为项目指定的名称。

    dotnet new console --name PROJECT_NAME

  2. 打包项目。

    dotnet pack --configuration Release

  3. 使用 personal access token 作为 API 密钥发布包。 将 PROJECT_NAME 替换为项目名称，将 1.0.0 替换为包的版本号，并将 YOUR_GITHUB_PAT 替换为 personal access token。

    dotnet nuget push "bin/Release/PROJECT_NAME.1.0.0.nupkg"  --api-key YOUR_GITHUB_PAT --source "github"

在发布包后，您可以在 GitHub 上查看该包。 有关详细信息，请参阅“查看包”。

使用 nuget.config 文件发布包

发布时，.csproj 文件中指定的存储库的 OWNER 必须与 nuget.config 身份验证文件中使用的 NAMESPACE 匹配 。 在 .csproj 文件中指定或递增版本号，然后使用 dotnet pack 命令创建该版本的 .nuspec 文件 。 有关创建包的详细信息，请参阅 Microsoft 文档中的“创建和发布包”。

  1. 向 GitHub Packages 验证。 有关详细信息，请参阅“向 GitHub Packages 进行身份验证”。

  2. 创建新项目。 将 PROJECT_NAME 替换为要为项目指定的名称。

    dotnet new console --name PROJECT_NAME

  3. 将项目的特定信息添加到以 .csproj 结尾的项目文件中。 请务必将

    • 将 1.0.0 替换为包的版本号。
    • 将 OWNER 替换为拥有你要向其发布包的存储库的个人帐户或组织的名称。
    • 将 REPOSITORY 替换为要将包连接到的存储库的名称。
    • 将 HOSTNAME 替换为 你的 GitHub Enterprise Server 实例 的主机名。
    <Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.0</TargetFramework>
    <PackageId>PROJECT_NAME</PackageId>
    <Version>1.0.0</Version>
    <Authors>AUTHORS</Authors>
    <Company>COMPANY_NAME</Company>
    <PackageDescription>PACKAGE_DESCRIPTION</PackageDescription>
    <RepositoryUrl>https://HOSTNAME/OWNER/REPOSITORY</RepositoryUrl>
  </PropertyGroup>

</Project>

  4. 打包项目。

    dotnet pack --configuration Release

  5. 使用在 nuget.config 文件中指定的 key 发布包。 将 PROJECT_NAME 替换为项目名称，并将 1.0.0 替换为包的版本号。

    dotnet nuget push "bin/Release/PROJECT_NAME.1.0.0.nupkg" --source "github"

在发布包后，您可以在 GitHub 上查看该包。 有关详细信息，请参阅“查看包”。

将多个包发布到同一个仓库

若要将多个包连接到同一个存储库，可以在所有 .csproj 项目文件的 RepositoryURL 字段中使用同一个 GitHub 存储库 URL。 GitHub 根据该字段匹配仓库。

以下示例将项目 MY_APP 和 MY_OTHER_APP 发布到同一存储库 ：

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.0</TargetFramework>
    <PackageId>MY_APP</PackageId>
    <Version>1.0.0</Version>
    <Authors>Octocat</Authors>
    <Company>GitHub</Company>
    <PackageDescription>This package adds a singing Octocat!</PackageDescription>
    <RepositoryUrl>https://HOSTNAME/my-org/my-repo</RepositoryUrl>
  </PropertyGroup>

</Project>

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.0</TargetFramework>
    <PackageId>MY_OTHER_APP</PackageId>
    <Version>1.0.0</Version>
    <Authors>Octocat</Authors>
    <Company>GitHub</Company>
    <PackageDescription>This package adds a dancing Octocat!</PackageDescription>
    <RepositoryUrl>https://HOSTNAME/my-org/my-repo</RepositoryUrl>
  </PropertyGroup>

</Project>

安装包

在项目中使用来自 GitHub 的包类似于使用来自 nuget.org 的包。将包依赖项添加到 .csproj 文件，并指定包名称和版本 。 有关在项目中使用 .csproj 文件的详细信息，请参阅 Microsoft 文档中的“使用 NuGet 包”。

  1. 向 GitHub Packages 验证。 有关详细信息，请参阅“向 GitHub Packages 进行身份验证”。

  2. 要使用包，请在 .csproj 项目文件中添加 ItemGroup 并配置 PackageReference 字段。 将 Include="PACKAGE_NAME" 中的 PACKAGE_NAME 值替换为包依赖项，并将 Version="X.X.X" 中的 X.X.X 值替换为要使用的包的版本：

    <Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.0</TargetFramework>
    <PackageId>My-app</PackageId>
    <Version>1.0.0</Version>
   <Authors>Octocat</Authors>
    <Company>GitHub</Company>
   <PackageDescription>This package adds an Octocat!</PackageDescription>
    <RepositoryUrl>https://HOSTNAME/OWNER/REPOSITORY</RepositoryUrl>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="PACKAGE_NAME" Version="X.X.X" />
  </ItemGroup>

</Project>

  3. 使用 restore 命令安装包。

    dotnet restore

故障排除

如果 .csproj 中的 RepositoryUrl 未设置为预期存储库，则 NuGet 包可能无法推送。

如果使用的是 nuspec 文件，请确保它具有包含必要的 type 和 url 属性的 repository 元素。

如果使用 GITHUB_TOKEN 对 GitHub Actions 工作流内的 GitHub Packages 注册表进行身份验证，则令牌无法在工作流运行范围以外的其他存储库中访问基于专用存储库的包。 若要访问与其他存储库关联的包，请改为生成具有 read:packages 范围的 personal access token (classic)，并将此令牌作为机密传入。

延伸阅读