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 platformy .NET i opublikować go w nuget.org przy użyciu interfejsu wiersza polecenia platformy .NET lub interfejsu wiersza polecenia dotnet.
Wymagania wstępne
Zestaw .NET SDK, który udostępnia narzędzie wiersza polecenia dotnet. Począwszy od programu Visual Studio 2017, interfejs wiersza polecenia dotnet jest automatycznie instalowany z dowolnymi obciążeniami powiązanymi z platformą .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 platformy .NET dla kodu, który chcesz spakować, lub utworzyć prosty projekt w następujący sposób:
- Utwórz folder o nazwie AppLogger.
- Otwórz wiersz polecenia i przejdź do folderu AppLogger . Wszystkie polecenia interfejsu wiersza polecenia dotnet w tym przewodniku Szybki start są uruchamiane domyślnie w bieżącym folderze.
- Wprowadź
dotnet new classlibciąg , 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ędniony w pliku projektu.
Otwórz plik projektu .csproj, .fproj 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>
Ważne
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.
Uwaga
W przypadku pakietów przeznaczonych do użytku publicznego należy zwrócić szczególną PackageTags uwagę na właściwość . Tagi pomagają innym osobom znaleźć pakiet i zrozumieć, co robi.
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ć za każdym razem, gdy uruchomisz dotnet packdotnet buildpolecenie , dodaj następujący wiersz do pliku projektu w pliku <PropertyGroup>:
<GeneratePackageOnBuild>true</GeneratePackageOnBuild>
Publikowanie pakietu
Opublikuj plik nupkg w celu nuget.org przy użyciu polecenia dotnet nuget push z kluczem interfejsu API uzyskanym z nuget.org.
Uwaga
Nuget.org skanuje wszystkie przekazane pakiety wirusów i odrzuca pakiety, jeśli znajdzie jakiekolwiek 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 nie zostaną one wyświetlone. Aby hostować pakiety prywatnie, zobacz Hostowanie własnych źródeł danych NuGet.
Uzyskiwanie klucza interfejsu API
Zaloguj się do konta nuget.org lub utwórz konto , jeśli jeszcze go nie masz.
Wybierz swoją nazwę użytkownika w prawym górnym rogu, a następnie wybierz pozycję Klucze interfejsu API.
Wybierz pozycję Utwórz i podaj nazwę klucza.
W obszarze Wybierz zakresy wybierz pozycję Wypchnij.
W obszarze Wybierz wzorzec globu pakietów>wprowadź *.
Wybierz pozycję Utwórz.
Wybierz pozycję Kopiuj , aby skopiować nowy klucz.
Ważne
- Zawsze przechowuj klucz interfejsu API jako klucz tajny. Klucz interfejsu API jest jak hasło, które umożliwia każdemu zarządzać 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 interfejsu API, jeśli nie chcesz już wypychać pakietów.
Określenie zakresu umożliwia tworzenie 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 klucze interfejsu API o określonym zakresie.
Publikowanie za pomocą polecenia dotnet nuget push
W folderze zawierającym plik nupkg uruchom następujące polecenie. Określ nazwę pliku nupkg i zastąp wartość klucza klucz kluczem interfejsu API.
dotnet nuget push Contoso.08.28.22.001.Test.1.0.0.nupkg --api-key qz2jga8pl3dvn2akksyquwcs9ygggg4exypy3bhxy6w6x6 --source https://api.nuget.org/v3/index.json
Dane wyjściowe przedstawiają wyniki procesu publikowania:
Pushing Contoso.08.28.22.001.Test.1.0.0.nupkg to 'https://www.nuget.org/api/v2/package'...
PUT https://www.nuget.org/api/v2/package/
warn : All published packages should have license information specified. Learn more: https://aka.ms/nuget/authoring-best-practices#licensing.
Created https://www.nuget.org/api/v2/package/ 1221ms
Your package was pushed.
Aby uzyskać więcej informacji, zobacz dotnet nuget push.
Uwaga
Jeśli chcesz uniknąć wygaśnięcia pakietu testowego na nuget.org, możesz wypchnąć do witryny testowej nuget.org pod adresem https://int.nugettest.org. Należy pamiętać, że pakiety przekazane do int.nugettest.org mogą nie być zachowywane.
Błędy publikowania
Błędy z push polecenia zwykle wskazują problem. Na przykład być może nie pamiętasz o zaktualizowaniu numeru wersji w projekcie, więc próbujesz opublikować pakiet, który już istnieje.
Występują również błędy, jeśli klucz interfejsu API jest nieprawidłowy lub wygasł lub jeśli próbujesz opublikować pakiet przy użyciu identyfikatora, który już istnieje na hoście. Załóżmy na przykład, że identyfikator AppLogger-test już istnieje w nuget.org. Jeśli spróbujesz opublikować pakiet przy użyciu tego identyfikatora, push polecenie zwraca 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.).
Jeśli wystąpi ten błąd, sprawdź, czy używasz prawidłowego klucza interfejsu API, który nie wygasł. Jeśli tak jest, błąd wskazuje, że identyfikator pakietu już istnieje na hoście. Aby rozwiązać ten problem, zmień identyfikator pakietu na unikatowy, ponownie skompiluj projekt, utwórz ponownie 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ć właśnie opublikowany pakiet, w nuget.org wybierz swoją nazwę użytkownika w prawym górnym rogu, a następnie wybierz pozycję Zarządzaj pakietami.
Uwaga
Indeksowanie pakietu i wyświetlanie go w wynikach wyszukiwania, w których 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:
Opublikowano pakiet NuGet w celu nuget.org, którego inni deweloperzy mogą używać w swoich projektach.
Jeśli utworzono pakiet, który nie jest przydatny (taki jak ten przykładowy pakiet utworzony przy użyciu pustej biblioteki klas) lub nie chcesz, aby pakiet był widoczny, możesz usunąć jego listę , aby ukryć go przed wynikami wyszukiwania:
Po pojawieniu się pakietu w obszarze Opublikowane pakiety na stronie Zarządzanie pakietami wybierz ikonę ołówka obok listy pakietów.
Na następnej stronie wybierz pozycję Lista, usuń zaznaczenie pola wyboru Lista w wynikach wyszukiwania, a następnie wybierz pozycję Zapisz.
Pakiet jest teraz wyświetlany w obszarze Pakiety nieznajdowane w obszarze Zarządzanie pakietami i nie jest już wyświetlany w wynikach wyszukiwania.
Uwaga
Aby uniknąć wygaśnięcia pakietu testowego na nuget.org, możesz wypchnąć do witryny 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!
Powiązany film wideo
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:
Uzyskaj więcej informacji na temat tworzenia i publikowania pakietów NuGet:
Opinia
Dostępne już wkrótce: W 2024 r. będziemy stopniowo wycofywać zgłoszenia z serwisu GitHub jako mechanizm przesyłania opinii na temat zawartości i zastępować go nowym systemem opinii. Aby uzyskać więcej informacji, sprawdź: https://aka.ms/ContentUserFeedback.
Prześlij i wyświetl opinię dla