Szybki start: tworzenie i publikowanie pakietu przy użyciu interfejsu wiersza polecenia dotnet

W tym przewodniku Szybki start pokazano, jak szybko utworzyć pakiet NuGet z biblioteki klas .NET i opublikować go w nuget.org przy użyciu interfejsu wiersza polecenia .NET lub interfejsu wiersza polecenia dotnet cli.

Wymagania wstępne

  • Zestaw SDK .NET, który udostępnia narzędzie wiersza polecenia dotnet. Począwszy od Visual Studio 2017, dotnet CLI jest automatycznie instalowane przy dowolnych obciążeniach związanych z .NET lub .NET Core.

  • Bezpłatne konto na nuget.org. Postępuj zgodnie z instrukcjami w temacie Dodawanie nowego indywidualnego konta.

Tworzenie projektu biblioteki klas

Możesz użyć istniejącego projektu biblioteki klas .NET dla kodu, który chcesz spakować, lub utworzyć prosty projekt w następujący sposób:

  1. Utwórz folder o nazwie AppLogger.
  2. Otwórz wiersz polecenia i przejdź do folderu AppLogger . Wszystkie polecenia dotnet w tym przewodniku szybkiego startu działają domyślnie w bieżącym folderze.
  3. Wprowadź dotnet new classlib, który tworzy projekt o bieżącej nazwie folderu.

Aby uzyskać więcej informacji, zobacz dotnet new.

Dodawanie metadanych pakietu do pliku projektu

Każdy pakiet NuGet ma manifest opisujący zawartość i zależności pakietu. W ostatnim pakiecie manifest jest plikiem .nuspec, który używa właściwości metadanych NuGet uwzględnionych w pliku projektu.

Otwórz plik projektu csproj, fsproj lub vbproj i dodaj następujące właściwości wewnątrz istniejącego <PropertyGroup> tagu. Użyj własnych wartości dla nazwy i firmy, a następnie zastąp identyfikator pakietu unikatową wartością.

<PackageId>Contoso.08.28.22.001.Test</PackageId>
<Version>1.0.0</Version>
<Authors>your_name</Authors>
<Company>your_company</Company>

Important

Identyfikator pakietu musi być unikatowy w nuget.org i innych źródłach pakietów. Publikowanie sprawia, że pakiet jest publicznie widoczny, więc jeśli używasz przykładowej biblioteki AppLogger lub innej biblioteki testowej, użyj unikatowej nazwy zawierającej SampleTestlub .

Możesz dodać dowolne opcjonalne właściwości opisane we właściwościach metadanych NuGet.

Note

W przypadku pakietów, które są przeznaczone do użytku publicznego, należy zwrócić szczególną uwagę na właściwość PackageTags. Tagi pomagają innym osobom znaleźć pakiet i zrozumieć, jak działa.

Uruchamianie polecenia pakietu

Aby skompilować pakiet NuGet lub plik nupkg z projektu, uruchom polecenie dotnet pack , które również kompiluje projekt automatycznie.

dotnet pack

Dane wyjściowe zawierają ścieżkę do pliku nupkg :

MSBuild version 17.3.0+92e077650 for .NET
  Determining projects to restore...
  Restored C:\Users\myname\source\repos\AppLogger\AppLogger.csproj (in 64 ms).
  AppLogger -> C:\Users\myname\source\repos\AppLogger\bin\Debug\net6.0\AppLogger.dll
  Successfully created package 'C:\Users\myname\source\repos\AppLogger\bin\Debug\Contoso.08.28.22.001.Test.1.0.0.nupkg'.

Automatyczne generowanie pakietu podczas kompilacji

Aby automatycznie uruchomić dotnet pack za każdym razem, gdy uruchamiasz dotnet build, dodaj następującą linię do pliku projektu w sekcji <PropertyGroup>.

    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Publikowanie pakietu

Opublikuj plik .nupkg na nuget.org przy użyciu polecenia dotnet nuget push z kluczem API uzyskanym z nuget.org.

Note

  • Nuget.org skanuje wszystkie przesłane pakiety w poszukiwaniu wirusów i odrzuca wszelkie pakiety zawierające wirusy. Nuget.org również okresowo skanuje wszystkie istniejące pakiety wymienione na liście.

  • Pakiety publikowane w nuget.org są publicznie widoczne dla innych deweloperów, chyba że je ukryjesz. Aby hostować pakiety prywatnie, zapoznaj się z Udostępnianie własnych źródeł NuGet.

Pobierz swój klucz API

  1. Zaloguj się do konta nuget.org lub utwórz konto , jeśli jeszcze go nie masz.

  2. W prawym górnym rogu wybierz nazwę użytkownika, a następnie wybierz pozycję Klucze interfejsu API.

  3. Wybierz pozycję Utwórz, a następnie wprowadź nazwę klucza.

  4. W obszarze Wybierz zakresy wybierz pozycję Prześlij.

  5. W obszarze Wybierz pakiety w polu Wzorzec globu wprowadź gwiazdkę (*).

  6. Wybierz Utwórz.

  7. Wybierz pozycję Kopiuj , aby skopiować nowy klucz.

    Zrzut ekranu przedstawiający stronę nuget.org zawierającą nowy klucz interfejsu API, komunikat o skopiowaniu klucza teraz i wyróżniony przycisk Kopiuj.

Important

  • Zawsze przechowuj klucz interfejsu API jako klucz tajny. Klucz interfejsu API jest jak hasło, którego każdy może używać do zarządzania pakietami w Twoim imieniu. Usuń lub ponownie wygeneruj klucz interfejsu API, jeśli zostanie on przypadkowo ujawniony.
  • Zapisz klucz w bezpiecznej lokalizacji, ponieważ nie można ponownie skopiować klucza później. Jeśli wrócisz do strony klucza interfejsu API, musisz ponownie wygenerować klucz, aby go skopiować. Możesz również usunąć klucz API, jeśli nie chcesz już przesyłać pakietów.

Określenie zakresu zapewnia sposób tworzenia oddzielnych kluczy interfejsu API do różnych celów. Każdy klucz ma przedział czasu wygaśnięcia i można określić zakres klucza dla określonych pakietów lub wzorców globu. Zakres każdego klucza można również ograniczyć do określonych operacji: Wypychanie nowych pakietów i wersji pakietów, wypychanie tylko nowych wersji pakietów lub anulowanie listy.

Za pomocą określania zakresu można tworzyć klucze interfejsu API dla różnych osób, które zarządzają pakietami w organizacji, aby miały one tylko wymagane uprawnienia.

Aby uzyskać więcej informacji, zobacz Zakresowe klucze API.

Publikuj za pomocą polecenia dotnet nuget push

W folderze zawierającym plik nupkg uruchom następujące polecenie. Zastąp <package-file> nazwą swojego pliku .nupkg i zastąp <API-key> swoim kluczem API.

dotnet nuget push <package-file> --api-key <API-key> --source https://api.nuget.org/v3/index.json

Dane wyjściowe przedstawiają wyniki procesu publikowania:

Pushing <package-file> to 'https://www.nuget.org/api/v2/package'...
  PUT https://www.nuget.org/api/v2/package/
  Created https://www.nuget.org/api/v2/package/ 2891ms
Your package was pushed.

Aby uzyskać więcej informacji, zobacz dotnet nuget push.

Błędy publikowania

Po uruchomieniu push polecenia czasami występuje błąd. Na przykład może wystąpić błąd w następujących sytuacjach:

  • Klucz interfejsu API jest nieprawidłowy lub wygasł.
  • Próbujesz opublikować pakiet o identyfikatorze, który już istnieje na hoście.
  • Wprowadzasz zmiany w opublikowanym pakiecie, ale zapomnisz zaktualizować numer wersji, zanim spróbujesz opublikować go ponownie.

Komunikat o błędzie zazwyczaj wskazuje źródło problemu.

Załóżmy na przykład, że identyfikator Contoso.App.Logger.Test istnieje w nuget.org. Jeśli spróbujesz opublikować pakiet przy użyciu tego identyfikatora, zostanie wyświetlony następujący błąd:

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.).

Aby rozwiązać tę sytuację, sprawdź zakres, datę wygaśnięcia i wartość klucza interfejsu API. Jeśli klucz jest prawidłowy, błąd wskazuje, że identyfikator pakietu już istnieje na hoście. Aby rozwiązać ten problem, zmień identyfikator pakietu na unikatowy, ponownie skompiluj projekt, ponownie utwórz plik nupkg i spróbuj ponownie wykonać push polecenie.

Zarządzanie opublikowanym pakietem

Po pomyślnym opublikowaniu pakietu otrzymasz wiadomość e-mail z potwierdzeniem. Aby wyświetlić opublikowany pakiet, przejdź do nuget.org, wybierz swoją nazwę użytkownika w prawym górnym rogu, a następnie wybierz pozycję Zarządzaj pakietami.

Note

Indeksowanie pakietu i wyświetlenie go w wynikach wyszukiwania, gdzie inne osoby mogą je znaleźć, może zająć trochę czasu. W tym czasie pakiet zostanie wyświetlony w obszarze Pakiety nieznajdujące się na liście, a na stronie pakietu zostanie wyświetlony następujący komunikat:

Zrzut ekranu przedstawiający komunikat ostrzegawczy nuget.org o tym, że pakiet nie został jeszcze opublikowany. Tekst wskazuje, że walidacja i indeksowanie mogą potrwać godzinę.

Po opublikowaniu pakietu NuGet w nuget.org inni deweloperzy mogą go używać w swoich projektach.

Jeśli tworzysz pakiet, który nie jest przydatny (taki jak ten przykładowy pakiet z pustej biblioteki klas) lub jeśli nie chcesz, aby pakiet był widoczny, możesz usunąć jego listę , aby ukryć go przed wynikami wyszukiwania:

  1. Po pojawieniu się pakietu w obszarze Opublikowane pakiety na stronie Zarządzanie pakietami wybierz ikonę ołówka obok listy pakietów.

    Zrzut ekranu przedstawiający stronę pakiety nuget.org. Sekcja Opublikowane pakiety zawiera listę jednego pakietu. Ikona edycji jest wyróżniona.

  2. Na następnej stronie wybierz pozycję Lista, wyczyść pole wyboru Lista w wynikach wyszukiwania , a następnie wybierz pozycję Zapisz.

    Zrzut ekranu przedstawiający stronę nuget.org. W sekcji Lista wyróżniono opcję wyświetlania listy pakietu w wynikach wyszukiwania.

Pakiet jest teraz wyświetlany w obszarze Pakiety nieznajdowane w obszarze Zarządzanie pakietami i nie jest już wyświetlany w wynikach wyszukiwania.

Note

Aby uniknąć opublikowania pakietu testowego na stronie live nuget.org, możesz opublikować go na witrynie testowej nuget.org pod adresem https://int.nugettest.org. Należy pamiętać, że pakiety przekazane do int.nugettest.org mogą nie być zachowywane.

Gratulujemy utworzenia i opublikowania pierwszego pakietu NuGet!

Więcej filmów NuGet można znaleźć w witrynach Channel 9 i YouTube.

Następne kroki

Zobacz więcej szczegółów na temat tworzenia pakietów za pomocą interfejsu wiersza polecenia dotnet:

Tworzenie pakietu NuGet za pomocą interfejsu wiersza polecenia dotnet

Uzyskaj więcej informacji na temat tworzenia i publikowania pakietów NuGet:

  • Last updated on