Arbeiten mit der NuGet-Registrierung

Sie können die dotnet Befehlszeilenschnittstelle (CLI) konfigurieren, um NuGet-Pakete in GitHub Packages zu veröffentlichen und Pakete zu verwenden, die in GitHub Packages als Abhängigkeiten in einem .NET project gespeichert sind.

Wer kann dieses Feature verwenden?

Enterprise Managed Users können im Namespace einer Organisation veröffentlicht werden. Diese Benutzer können keine Pakete im Namespace ihres Kontos veröffentlichen, da keine persönliche Speicherzuweisung vorhanden ist. Weitere Informationen zu Enterprise Managed Users findest du unter Informationen zu Enterprise Managed Users.

In diesem Artikel

URL für die NuGet-Registrierung

Wenn Sie auf GitHub unter GitHub.com zugreifen, werden Sie Pakete auf https://nuget.pkg.github.com veröffentlichen. In den Beispielen in diesem Artikel wird diese URL verwendet.

Wenn Sie auf GitHub unter einer anderen Domain zugreifen, z. B. octocorp.ghe.com, ersetzen Sie "https://nuget.pkg.github.com" durch https://nuget.SUBDOMAIN.ghe.com, wobei SUBDOMAIN die eindeutige Subdomain Ihres Unternehmens ist.

Sich bei GitHub Packages authentifizieren

Hinweis

GitHub Packages unterstützt nur die Authentifizierung mit einem personal access token (classic). Weitere Informationen finden Sie unter Verwalten deiner persönlichen Zugriffstoken.

Du benötigst ein Zugriffstoken, um private, interne und öffentliche Pakete zu veröffentlichen, zu installieren und zu löschen.

Du kannst ein personal access token (classic) verwenden, um dich bei GitHub Packages oder der GitHub-API zu authentifizieren. Wenn du ein personal access token (classic) erstellst, kannst du dem Token je nach Bedarf verschiedene Bereiche zuweisen. Weitere Informationen zu paketbezogenen Bereichen für ein personal access token (classic) findest du unter Informationen zu Berechtigungen für GitHub-Pakete.

Um dich bei einer GitHub Packages-Registrierung innerhalb eines GitHub Actions-Workflows zu authentifizieren, kannst du Folgendes verwenden:

  • GITHUB_TOKEN, um Pakete zu veröffentlichen, die mit dem Workflowrepository verbunden sind.
  • Ein personal access token (classic) mit mindestens dem read:packages-Bereich für die Installation von Paketen, die anderen privaten Repositorys zugeordnet sind (GITHUB_TOKEN kann verwendet werden, wenn das Repository Lesezugriff auf das Paket enthält. Weitere Informationen findest du unter Konfigurieren der Zugriffssteuerung und Sichtbarkeit von Paketen).

Authentifizieren in einem GitHub Actions-Workflow

Diese Registrierung unterstützt präzise Berechtigungen. Wenn dein GitHub Actions-Workflow ein personal access token zum Authentifizieren bei einer Registrierung verwendet, solltest du für Registrierungen, die differenzierte Berechtigungen unterstützen, deinen Workflow unbedingt so aktualisieren, dass das GITHUB_TOKEN verwendet wird. Eine Anleitung zum Aktualisieren deiner Workflows, die sich mit einem personal access token bei einer Registrierung authentifizieren, findest du unter Veröffentlichen und Installieren eines Pakets mit GitHub Actions.

Hinweis

Die Möglichkeit für GitHub Actions-Workflows, Pakete mithilfe der REST-API zu löschen und wiederherzustellen, befindet sich derzeit in der öffentliche Vorschau. Änderungen sind vorbehalten.

Sie können ein GITHUB_TOKEN in einem GitHub Actions-Workflow verwenden, um ein Paket mithilfe der REST-API zu löschen oder wiederherzustellen, wenn das Token über die admin-Berechtigung für das Paket verfügt. Repositorys, die Pakete mithilfe eines Workflows veröffentlichen, und Repositorys, die du explizit mit Paketen verbunden hast, erhalten automatisch die admin-Berechtigung für Pakete im Repository.

Weitere Informationen zum GITHUB_TOKEN findest du unter Verwenden von GITHUB_TOKEN für die Authentifizierung in Workflows. Weitere Informationen zu den Best Practices bei der Verwendung einer Registrierung in Actions findest du unter Referenz zur sicheren Verwendung.

Verwende den folgenden Befehl, um dich bei GitHub Packages in einem GitHub Actions-Workflow mit dem GITHUB_TOKEN zu authentifizieren, anstatt ein hartcodiertes personal access token in einer Datei vom Typ „nuget.config“ im Repository zu verwenden:

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

Ersetze NAMESPACE durch den Namen des persönlichen Kontos oder der Organisation , auf das bzw. die deine Pakete ausgerichtet sind.

Ersetzen Sie USERNAME durch den Benutzernamen, der beim Herstellen einer Verbindung mit einer authentifizierten Quelle zu verwenden ist.

Du kannst außerdem auswählen, ob du Zugriffsberechtigungen auf Pakete unabhängig voneinander für GitHub Codespaces und GitHub Actions erteilen möchtest. Weitere Informationen findest du unter Konfigurieren der Zugriffssteuerung und Sichtbarkeit von Paketen und Konfigurieren der Zugriffssteuerung und Sichtbarkeit von Paketen.

Authentifizieren mit einem personal access token

Hinweis

GitHub Packages unterstützt nur die Authentifizierung mit einem personal access token (classic). Weitere Informationen finden Sie unter Verwalten deiner persönlichen Zugriffstoken.

Du benötigst ein Zugriffstoken, um private, interne und öffentliche Pakete zu veröffentlichen, zu installieren und zu löschen.

Du kannst ein personal access token (classic) verwenden, um dich bei GitHub Packages oder der GitHub-API zu authentifizieren. Wenn du ein personal access token (classic) erstellst, kannst du dem Token je nach Bedarf verschiedene Bereiche zuweisen. Weitere Informationen zu paketbezogenen Bereichen für ein personal access token (classic) findest du unter Informationen zu Berechtigungen für GitHub-Pakete.

Um dich bei einer GitHub Packages-Registrierung innerhalb eines GitHub Actions-Workflows zu authentifizieren, kannst du Folgendes verwenden:

  • GITHUB_TOKEN, um Pakete zu veröffentlichen, die mit dem Workflowrepository verbunden sind.
  • Ein personal access token (classic) mit mindestens dem read:packages-Bereich für die Installation von Paketen, die anderen privaten Repositorys zugeordnet sind (GITHUB_TOKEN kann verwendet werden, wenn das Repository Lesezugriff auf das Paket enthält. Weitere Informationen findest du unter Konfigurieren der Zugriffssteuerung und Sichtbarkeit von Paketen).

Du musst ein personal access token (classic) mit den entsprechenden Bereichen verwenden, um Pakete in GitHub Packages zu veröffentlichen und zu installieren. Weitere Informationen finden Sie unter Einführung in GitHub-Pakete.

Um sich bei GitHub Packages über die Befehlszeilenschnittstelle (CLI) dotnet zu authentifizieren, erstellen Sie eine nuget.config-Datei in Ihrem Projektverzeichnis, in der GitHub Packages als Quelle unter packageSources für den CLI-Client dotnet angegeben ist.

Dabei musst du Folgendes ersetzen: * USERNAME mit dem Namen deines persönlichen Kontos auf GitHub. * TOKEN mit Ihrem personal access token (classic) * NAMESPACE mit dem Namen des persönlichen Kontos oder der Organisation , auf das/die Ihre Pakete angewendet werden.

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

Veröffentlichen eines Pakets

Hinweis

Das nupkg-Archiv für eine NuGet-Paketversion muss kleiner als 2,147 GB sein.

Sie können ein Paket in GitHub Packages veröffentlichen, indem Sie sich mit einer nuget.config-Datei authentifizieren, die --api-key Befehlszeilenoption mit Ihrem GitHub personal access token (classic) verwenden oder einen Befehl verwenden, der direkt über die Befehlszeile mit der dotnet Befehlszeilenschnittstelle (CLI) ausgeführt werden kann.

Ersetzen Sie OWNER durch Ihren Benutzernamen oder den Firmennamen und YOUR_GITHUB_PAT durch Ihr personal access token.

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

Die NuGet-Registrierung speichert Pakete in deinem Organisationskonto oder in deinem persönlichen Konto und ermöglicht die Zuordnung von Paketen zu einem Repository. Du kannst wählen, ob Berechtigungen von einem Repository geerbt oder präzise Berechtigungen unabhängig von einem Repository festgelegt werden sollen.

Wenn du ein Paket zum ersten Mal veröffentlichst, ist die Sichtbarkeit standardmäßig auf privat eingestellt. Informationen zum Ändern der Sichtbarkeit oder zum Festlegen von Zugriffsberechtigungen findest du unter Konfigurieren der Zugriffssteuerung und Sichtbarkeit von Paketen. Weitere Informationen zum Verknüpfen eines veröffentlichten Pakets mit einem Repository finden Sie unter Verbinden eines Repositorys mit einem Paket.

Wenn Sie eine RepositoryURL in der _.csproj_Datei ihres project angeben, wird das veröffentlichte Paket automatisch mit dem angegebenen Repository verbunden. Weitere Informationen finden Sie unter Arbeiten mit der NuGet-Registrierung. Informationen zum Verknüpfen eines bereits veröffentlichten Pakets mit einem Repository finden Sie unter Verbinden eines Repositorys mit einem Paket.

Veröffentlichen eines Pakets unter Verwendung eines personal access token für GitHub als API-Schlüssel

Falls Sie noch keine personal access token für Ihr Konto auf GitHub haben, siehe Verwalten deiner persönlichen Zugriffstoken.

  1. Erstellen Sie ein neues Projekt. Ersetzen Sie PROJECT_NAME durch den Namen, den Sie dem project zuweisen möchten.

    dotnet new console --name PROJECT_NAME

  2. Verpacken Sie das Projekt.

    dotnet pack --configuration Release

  3. Veröffentliche das Paket, und verwende dabei dein personal access token als API-Schlüssel. Ersetzen Sie PROJECT_NAME durch den Namen des Projekts, 1.0.0 durch die Versionsnummer des Pakets, und YOUR_GITHUB_PAT durch Ihre personal access token.

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

Nachdem Du ein Paket veröffentlicht hast, kannst Du das Paket auf GitHub ansehen. Weitere Informationen finden Sie unter Pakete anzeigen.

Veröffentlichen eines Pakets mithilfe einer Datei nuget.config

Wenn du eine Veröffentlichung ausführst,wenn du dein Paket mit einem Repository verknüpfst, muss der OWNER des in deiner CSPROJ-Datei angegebenen Repositorys mit dem NAMESPACE übereinstimmen, den du in deiner nuget.config-Authentifizierungsdatei verwendest. Gib die Versionsnummer in deiner CSPROJ-Datei an, oder erhöhe sie, und erstelle dann mit dem Befehl dotnet pack eine NUSPEC-Datei für diese Version. Weitere Informationen zum Erstellen deines Pakets findest du in der Microsoft-Dokumentation unter Erstellen und Veröffentlichen eines Pakets.

Hinweis

Wenn du ein Paket veröffentlichst, das mit einem Repository verknüpft ist, erbt das Paket automatisch die Zugriffsberechtigungen des verknüpften Repositorys, und GitHub Actions-Workflows im verknüpften Repository erhalten automatisch Zugriff auf das Paket – es sei denn, deine Organisation hat die automatische Vererbung von Zugriffsberechtigungen deaktiviert. Weitere Informationen finden Sie unter Konfigurieren der Zugriffssteuerung und Sichtbarkeit von Paketen.

  1. Authentifizieren bei GitHub Packages. Weitere Informationen findest Du unter Authentifizieren bei GitHub Packages.

  2. Erstellen Sie ein neues Projekt. Ersetzen Sie PROJECT_NAME durch den Namen, den Sie dem project zuweisen möchten.

    dotnet new console --name PROJECT_NAME

  3. Fügen Sie die spezifischen Informationen Ihres Projekts zur Datei Ihres Projekts hinzu, die auf .csproj endet. Stelle sicher, dass du Folgendes ersetzt:

    •      `1.0.0` mit der Versionsnummer des Pakets.

    •      `OWNER` mit dem Namen des persönlichen Kontos oder der Organisation, die das Repository besitzt, zu dem du dein Paket verknüpfen möchtest.

    •      `REPOSITORY` mit dem Namen des Repositorys, mit dem du dein Paket verbinden möchtest

    <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://github.com/OWNER/REPOSITORY</RepositoryUrl>
  </PropertyGroup>

</Project>

  4. Verpacken Sie das Projekt.

    dotnet pack --configuration Release

  5. Veröffentliche das Paket mit dem key, den du in der Datei nuget.config angegeben hast. Ersetzen Sie PROJECT_NAME durch den Namen des project, und ersetzen Sie 1.0.0 durch die Versionsnummer des Pakets.

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

Nachdem Du ein Paket veröffentlicht hast, kannst Du das Paket auf GitHub ansehen. Weitere Informationen finden Sie unter Pakete anzeigen.

Veröffentlichen mehrerer Pakete im gleichen Repository

Um mehrere Pakete mit demselben Repository zu verbinden, verwenden Sie dieselbe GitHub Repository-URL in den RepositoryURL Feldern in allen .csproj-Dateien. GitHub ermittelt das Repository anhand dieses Felds.

Im folgenden Beispiel werden die Projekte MY_APP und MY_OTHER_APP im selben Repository veröffentlicht:

<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://github.com/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://github.com/my-org/my-repo</RepositoryUrl>
  </PropertyGroup>

</Project>

Installieren eines Pakets

Das Verwenden von Paketen aus GitHub in Ihrem Projekt ähnelt der Verwendung von Paketen von nuget.org. Fügen Sie Ihre Paketabhängigkeiten zu Ihrer Datei .csproj hinzu, indem Sie den Paketnamen und die Version angeben. Weitere Informationen zur Verwendung einer datei .csproj in Ihrem project finden Sie in der Microsoft-Dokumentation unter Working with NuGet packages.

  1. Authentifizieren bei GitHub Packages. Weitere Informationen findest Du unter Authentifizieren bei GitHub Packages.

  2. Um ein Paket zu verwenden, fügen Sie ItemGroup hinzu, und konfigurieren Sie das Feld PackageReference in der Datei .csproj project. Ersetze den PACKAGE_NAME-Wert in Include="PACKAGE_NAME" durch deine Paketabhängigkeit, und ersetze den X.X.X-Wert in Version="X.X.X" durch die Version des Pakets, die du verwenden möchtest:

    <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://github.com/OWNER/REPOSITORY</RepositoryUrl>
  </PropertyGroup>

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

</Project>

  3. Du installierst die Pakete mit dem Befehl restore.

    dotnet restore

Problembehandlung

Wenn du GITHUB_TOKEN verwendest, um dich bei einer GitHub Packages-Registrierung in einem GitHub Actions-Workflow zu authentifizieren, kann das Token nicht auf Pakete in privaten Repositorys zugreifen, wenn es sich um ein anderes Repository aus dasjenige handelt, in dem der Workflow ausgeführt wird. Um auf Pakete zuzugreifen, die anderen Repositorys zugeordnet sind, musst du stattdessen ein personal access token (classic) mit dem Geltungsbereich read:packages definieren und dieses Token als Geheimnis übergeben.

Zeitweilige 403 Fehler beim Wiederherstellen öffentlicher Pakete

Wenn Sie GitHub Packages zusammen mit nuget.org verwenden und beim Wiederherstellen von Standard-Paketen (wie Microsoft.Extensions.*) zeitweise 403 Forbidden-Fehler auftreten, kann dies daran liegen, dass NuGet für jedes Paket alle konfigurierten Paketquellen abfragt. Wenn die GitHub Packages Authentifizierung vorübergehend fehlschlägt, kann dies die gesamte Wiederherstellung blockieren, sogar für Pakete, die auf GitHub Packages nicht existieren.

Um dies zu vermeiden, verwenden Sie die NuGet-Paketquellzuordnung , um Pakete an bestimmte Quellen weiterzuleiten.

Ersetzen Sie: * NAMESPACE mit dem Namen des persönlichen Kontos oder der Organisation, der Ihr GitHub Packages NuGet-Feed gehört. * PACKAGE-ID-PREFIX mit dem NuGet-Paket-ID-Präfix, das Sie bei Paketen verwenden, die auf GitHub Packages gehostet werden. Wenn Sie mehrere Präfixe verwenden, fügen Sie zusätzliche <package> Einträge für jedes Präfix hinzu.

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

NuGet verwendet das spezifischste Abgleichsmuster, sodass Pakete, die PACKAGE-ID-PREFIX.* entsprechen, nur aus GitHub Packages abgerufen werden, während alle anderen Pakete aus nuget.org abgerufen werden. Dies hilft auch, Abhängigkeitsverwechslungen zu verhindern, indem sichergestellt wird, dass Ihre privaten Pakete nur aus Ihrem GitHub Packages-Feed stammen können.

Weitere Informationen

  •         [AUTOTITLE](/packages/learn-github-packages/deleting-and-restoring-a-package)