Работа с реестром NuGet

Интерфейс командной строки можно настроить dotnet для публикации пакетов GitHub Packages NuGet и использования пакетов, хранящихся GitHub Packages в качестве зависимостей в проекте .NET.

В этой статье

Примечание.

Этот тип пакета может быть недоступен для вашего экземпляра, так как администраторы сайта могут включить или отключить каждый поддерживаемый тип пакета. Дополнительные сведения см. в разделе Настройка поддержки экосистемы пакетов для предприятия.

Аутентификация в GitHub Packages

Примечание.

GitHub Packages поддерживает проверку подлинности только с помощью personal access token (classic). Дополнительные сведения см. в разделе Управление личными маркерами доступа.

Для публикации, установки и удаления частных, внутренних и общедоступных пакетов требуется маркер доступа.

Можно использовать personal access token (classic) для проверки подлинности в API GitHub Packages или API GitHub . При создании personal access token (classic)можно назначить маркер различным областям в зависимости от ваших потребностей. Дополнительные сведения о областях, связанных с пакетами, для personal access token (classic), см. в разделе Сведения о разрешениях для пакетов GitHub.

Для проверки подлинности в реестре GitHub Packages в рабочем процессе GitHub Actions можно использовать следующее:

  • GITHUB_TOKEN для публикации пакетов, связанных с репозиторием рабочих процессов.
  • personal access token (classic) с по крайней мере read:packages областью действия для установки пакетов, связанных с другими частными репозиториями (GITHUB_TOKEN можно использовать, если репозиторий предоставлен доступ на чтение к пакету. См . раздел AUTOTITLE.

Проверка подлинности в GitHub Actions рабочем процессе

Используйте следующую команду, чтобы пройти проверку подлинности GitHub Packages в GitHub Actions рабочем процессе, используя GITHUB_TOKEN вместо жесткого personal access token кода файл в nuget.config файле в репозитории:

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_TOKEN использовании в рабочих процессах GitHub Actions см. в разделе Использование GITHUB_TOKEN для проверки подлинности в рабочих процессах.

Аутентификация с помощью personal access token

Примечание.

GitHub Packages поддерживает проверку подлинности только с помощью personal access token (classic). Дополнительные сведения см. в разделе Управление личными маркерами доступа.

Для публикации, установки и удаления частных, внутренних и общедоступных пакетов требуется маркер доступа.

Можно использовать personal access token (classic) для проверки подлинности в API GitHub Packages или API GitHub . При создании personal access token (classic)можно назначить маркер различным областям в зависимости от ваших потребностей. Дополнительные сведения о областях, связанных с пакетами, для personal access token (classic), см. в разделе Сведения о разрешениях для пакетов GitHub.

Для проверки подлинности в реестре GitHub Packages в рабочем процессе GitHub Actions можно использовать следующее:

  • GITHUB_TOKEN для публикации пакетов, связанных с репозиторием рабочих процессов.
  • personal access token (classic) с по крайней мере read:packages областью действия для установки пакетов, связанных с другими частными репозиториями (GITHUB_TOKEN можно использовать, если репозиторий предоставлен доступ на чтение к пакету. См . раздел AUTOTITLE.

Необходимо использовать personal access token (classic) с соответствующими областями для публикации и установки пакетов в GitHub Packages. Дополнительные сведения см. в разделе Введение в GitHub Packages.

Чтобы выполнить проверку подлинности GitHub Packages с помощью dotnet интерфейса командной строки (CLI), создайте _ файлnuget.config_ в каталоге проекта, GitHub Packages указывающий в качестве источника packageSources для dotnet клиента CLI.

Необходимо заменить:

  • 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_ , используя --api-key параметр командной строки с вашей GitHubpersonal access token (classic) командой или с помощью команды, которая может выполняться непосредственно из командной строки с помощью 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

Если у вас еще нет учетной personal access token записи GitHub, см. раздел Управление личными маркерами доступа.

  1. Создайте новый project. Замените PROJECT_NAME на имя, которое вы хотите дать project.

    dotnet new console --name PROJECT_NAME

  2. Упаковывайте project.

    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

При публикации, OWNER должен соответствовать NAMESPACE используемому в файле проверки подлинности nuget.config. Укажите или увеличьте номер версии в CSPROJ-файле, а затем используйте команду dotnet pack, чтобы создать NUSPEC-файл для этой версии. Дополнительные сведения о создании пакета см. в статье "Создание и публикация пакета" в документации Майкрософт.

  1. Пройдите проверку подлинности в GitHub Packages. Дополнительные сведения см. в разделе "Проверка подлинности в GitHub Packages.

  2. Создайте новый project. Замените PROJECT_NAME на имя, которое вы хотите дать project.

    dotnet new console --name PROJECT_NAME

  3. Добавьте конкретную информацию вашего project в файл вашего project, который заканчивается на .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. Упаковывайте project.

    dotnet pack --configuration Release

  5. Опубликуйте пакет, используя key, указанный в файле nuget.config. Замените PROJECT_NAME на название project и замените 1.0.0 на номер версии упаковки.

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

После публикации пакет можно просмотреть здесь: GitHub. Дополнительные сведения см. в разделе Просмотр пакетов.

Публикация нескольких пакетов в одном репозитории

Чтобы подключить несколько пакетов к одному репозиторию, используйте один и тот же GitHub URL-адрес репозитория в полях во RepositoryURL всех файлах проекта CSPROJ . 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 в вашем project см. Работа с пакетами NuGet в документации Microsoft.

  1. Пройдите проверку подлинности в GitHub Packages. Дополнительные сведения см. в разделе "Проверка подлинности в GitHub Packages.

  2. Чтобы использовать пакет, добавьте ItemGroup и настройте поле PackageReference в файле .csproj project. Замените PACKAGE_NAME значение Include="PACKAGE_NAME" в зависимости пакета и замените X.X.X его Version="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

Устранение неполадок

Пакет NuGet может не отправляться, если RepositoryUrl в CSPROJ не задан ожидаемый репозиторий.

Если вы используете nuspec-файл, убедитесь, что он имеет repository элемент с обязательными type атрибутами.url

Если вы используете GITHUB_TOKEN проверку подлинности в GitHub Packages реестре GitHub Actions в рабочем процессе, маркер не может получить доступ к пакетам на основе частного репозитория в другом репозитории, отличном от того, где выполняется рабочий процесс. Чтобы получить доступ к пакетам, связанным с другими репозиториями, вместо этого создайте personal access token (classic)read:packages область с областью и передайте этот маркер в виде секрета.

Прерывистые ошибки 403 при восстановлении публичных пакетов

Если вы используете GitHub Packages вместе с nuget.org и испытываете периодические ошибки 403 Запрещено при восстановлении стандартных общедоступных пакетов (например), это может произойти, так как Microsoft.Extensions.*NuGet запрашивает все настроенные источники пакетов для каждого пакета. Если GitHub Packages проверка подлинности завершается временной ошибкой, она может блокировать весь процесс восстановления даже для пакетов, в которых нет GitHub Packages.

Чтобы избежать этого, используйте NuGet Package Source Mapping для маршрутизации пакетов к конкретным источникам.

Замените:

  • NAMESPACE с именем личной учетной записи или организации, которая владеет веб-каналом GitHub Packages NuGet.
  • PACKAGE-ID-PREFIX с префиксом идентификатора пакета NuGet, который используется для пакетов, размещенных в GitHub Packages. При использовании нескольких префиксов добавьте дополнительные <package> записи для каждого префикса.
  • HOSTNAME с именем узла для ваш экземпляр GitHub Enterprise Server.

Если у экземпляра включена изоляция поддомена:

<configuration>
    <packageSources>
        <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
        <add key="github" value="https://nuget.HOSTNAME/NAMESPACE/index.json" />
    </packageSources>
    <packageSourceMapping>
        <packageSource key="nuget.org">
            <package pattern="*" />
        </packageSource>
        <packageSource key="github">
            <package pattern="PACKAGE-ID-PREFIX.*" />
        </packageSource>
    </packageSourceMapping>
</configuration>

Если у экземпляра отключена изоляция поддомена:

<configuration>
    <packageSources>
        <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
        <add key="github" value="https://HOSTNAME/_registry/nuget/NAMESPACE/index.json" />
    </packageSources>
    <packageSourceMapping>
        <packageSource key="nuget.org">
            <package pattern="*" />
        </packageSource>
        <packageSource key="github">
            <package pattern="PACKAGE-ID-PREFIX.*" />
        </packageSource>
    </packageSourceMapping>
</configuration>

NuGet использует наиболее конкретный шаблон сопоставления, поэтому сопоставления PACKAGE-ID-PREFIX.* пакетов извлекаются только из GitHub Packagesних, а все остальные пакеты извлекаются из nuget.org. Это также помогает предотвратить атаки на путаницу зависимостей, гарантируя, что частные пакеты могут поступать только из GitHub Packages вашего веб-канала.

Дополнительные материалы