Szybki start: tworzenie i publikowanie pakietu przy użyciu programu Visual Studio (.NET Framework, Windows)

Za pomocą programu Microsoft Visual Studio można utworzyć pakiet NuGet z biblioteki klas programu .NET Framework, a następnie opublikować go w nuget.org przy użyciu narzędzia interfejsu wiersza polecenia NuGet.

Przewodnik Szybki start dotyczy tylko użytkowników systemu Windows. Jeśli używasz Visual Studio dla komputerów Mac, zobacz narzędzia interfejsu wiersza polecenia dotnet.

Wymagania wstępne

• Zainstaluj program Visual Studio 2022 dla systemu Windows przy użyciu dowolnego elementu . Obciążenie związane z platformą NET.

  Możesz zainstalować wersję Community Edition 2022 bezpłatnie z visualstudio.microsoft.com lub użyć wersji Professional lub Enterprise.

  Program Visual Studio 2017 lub nowszy automatycznie obejmuje funkcje NuGet po zainstalowaniu obciążenia platformy .NET.

• Zarejestruj się w celu uzyskania bezpłatnego konta na nuget.org , jeśli jeszcze go nie masz. Przed przekazaniem pakietu NuGet należy zarejestrować i potwierdzić konto.

• Zainstaluj interfejs wiersza polecenia Narzędzia NuGet, pobierając go z nuget.org. Dodaj plik nuget.exe do odpowiedniego folderu i dodaj ten folder do zmiennej środowiskowej PATH.

Tworzenie projektu biblioteki klas

Aby utworzyć projekt biblioteki klas, wykonaj następujące kroki:

1. W programie Visual Studio wybierz pozycje Plik>Nowy>Projekt.

2. W oknie Tworzenie nowego projektu wybierz pozycję C#, Windows i Biblioteka na listach rozwijanych.

3. Na wyświetlonej liście szablonów projektów wybierz pozycję Biblioteka klas (.NET Framework), a następnie wybierz pozycję Dalej.

4. W oknie Konfigurowanie nowego projektu wprowadź ciąg AppLogger jako nazwę projektu, a następnie wybierz pozycję Utwórz.

5. Aby upewnić się, że projekt został utworzony prawidłowo, wybierz pozycję Kompiluj>rozwiązanie. Biblioteka DLL znajduje się w folderze Debug (lub Wydanie, jeśli zamiast tego skompilujesz konfigurację).

6. (Opcjonalnie) W tym przewodniku Szybki start nie trzeba pisać żadnego dodatkowego kodu dla pakietu NuGet, ponieważ biblioteka klas szablonów jest wystarczająca do utworzenia pakietu. Jeśli jednak chcesz, aby kod funkcjonalny dla tego przykładowego pakietu zawierał następujący kod:

   namespace AppLogger
   {
       public class Logger
       {
           public void Log(string text)
           {
               Console.WriteLine(text);
           }
       }
   }
   

   W rzeczywistym pakiecie NuGet prawdopodobnie zaimplementujesz wiele przydatnych funkcji, za pomocą których inne osoby mogą tworzyć aplikacje. Można również ustawić platformy docelowe. Przykłady można znaleźć w temacie UwP i Xamarin.

Konfigurowanie właściwości projektu dla pakietu

Pakiet NuGet zawiera manifest ( .nuspec plik), który zawiera odpowiednie metadane, takie jak identyfikator pakietu, numer wersji, opis i inne. Niektóre z tych metadanych można pobrać bezpośrednio z właściwości projektu, co pozwala uniknąć konieczności oddzielnego aktualizowania ich zarówno w projekcie, jak i manifeście. W poniższych krokach opisano sposób ustawiania odpowiednich właściwości:

1. Wybierz pozycję Właściwości projektu>, a następnie wybierz kartę Aplikacja.

2. W polu Nazwa zestawu nadaj pakietowi unikatowy identyfikator. Jeśli spróbujesz opublikować pakiet o nazwie, która już istnieje, zostanie wyświetlony błąd.

   Ważne

   Należy nadać pakietowi identyfikator unikatowy dla nuget.org lub dowolnego używanego hosta. W przeciwnym razie wystąpi błąd. W tym przewodniku Szybki start zalecamy dołączenie przykładu lub testu w nazwie, ponieważ krok publikowania sprawia, że pakiet jest publicznie widoczny.

3. Wybierz pozycję Informacje o zestawie, w którym jest wyświetlane okno dialogowe, w którym można wprowadzić inne właściwości przenoszone do manifestu (zobacz Tokeny zastępcze). Najczęściej używane pola to Tytuł, Opis, Firma, Prawa autorskie i Wersja zestawu. Ponieważ te właściwości są wyświetlane z pakietem na hoście, na przykład nuget.org po jego opublikowaniu, upewnij się, że są one w pełni opisowe.

   

4. (Opcjonalnie) Aby wyświetlić i edytować właściwości bezpośrednio, otwórz plik Właściwości/AssemblyInfo.cs w projekcie, wybierając pozycję Project Edit Project File (Edytuj plik projektu).>

5. Po ustawieniu tych właściwości ustaw aktywną konfigurację rozwiązania w programie Build>Configuration Manager na Release (Wydanie ) i ponownie skompiluj projekt w celu wygenerowania zaktualizowanej biblioteki DLL.

Generowanie początkowego manifestu

Po ustawieniu właściwości projektu i utworzeniu biblioteki DLL można teraz wygenerować początkowy plik nuspec z projektu. Ten krok obejmuje odpowiednie tokeny zastępcze do rysowania informacji z pliku projektu.

Uruchom polecenie nuget spec tylko raz, aby wygenerować początkowy manifest. Jeśli zaktualizujesz pakiet, zmień wartości w projekcie lub edytujesz manifest bezpośrednio:

1. Po otwarciu projektu w Eksplorator rozwiązań otwórz wiersz polecenia, wybierając pozycję Narzędzia>Wiersz polecenia Dla deweloperów wiersza>polecenia.

   Wiersz polecenia zostanie otwarty w katalogu projektu, w AppLogger.csproj którym znajduje się plik.

2. Uruchom następujące polecenie: nuget spec AppLogger.csproj.

   NuGet tworzy manifest zgodny z nazwą projektu, w tym przypadku AppLogger.nuspec. Zawiera również tokeny zastępcze w manifeście.

3. Otwórz AppLogger.nuspec plik w edytorze tekstów, aby sprawdzić jego zawartość, która będzie podobna do następującego kodu:

   <?xml version="1.0"?>
   <package >
     <metadata>
       <id>Package</id>
       <version>1.0.0</version>
       <authors>Your username</authors>
       <owners>Your username</owners>
       <license type="expression">MIT</license>
       <!-- <icon>icon.png</icon> -->
       <projectUrl>http://PROJECT_URL_HERE_OR_DELETE_THIS_LINE</projectUrl>
       <requireLicenseAcceptance>false</requireLicenseAcceptance>
       <description>Package description</description>
       <releaseNotes>Summary of changes made in this release of the package.</releaseNotes>
       <copyright>Copyright 2022</copyright>
       <tags>Tag1 Tag2</tags>
     </metadata>
   </package>
   

Edytowanie manifestu

1. Przed kontynuowaniem edytuj następujące właściwości. W przeciwnym razie, jeśli spróbujesz utworzyć pakiet NuGet z wartościami domyślnymi w .nuspec pliku, wystąpi błąd. Aby uzyskać informacje o tych właściwościach, zobacz Opcjonalne elementy metadanych:

   • licenseUrl
   • projectUrl
   • releaseNotes
   • tags

2. W przypadku pakietów utworzonych do użytku publicznego zwróć szczególną uwagę na właściwość Tags , ponieważ tagi pomagają innym osobom znaleźć pakiet i zrozumieć, co robi.

3. W tej chwili można również dodać inne elementy do manifestu, zgodnie z opisem w dokumentacji pliku nuspec.

4. Zapisz plik przed kontynuowaniem.

Uruchamianie polecenia pakietu

1. Po otwarciu projektu w Eksplorator rozwiązań otwórz wiersz polecenia, wybierając pozycję Narzędzia>Wiersz polecenia Dla deweloperów wiersza>polecenia.

   Wiersz polecenia zostanie otwarty w katalogu projektu.

2. Uruchom następujące polecenie: nuget pack.

   NuGet generuje plik nupkg w postaci identifier.version.nupkg w bieżącym folderze.

Publikowanie pakietu

Po utworzeniu pliku nupkg opublikuj go w nuget.org przy użyciu interfejsu wiersza polecenia NuGet z kluczem interfejsu API uzyskanym z nuget.org. W przypadku nuget.org należy użyć nuget.exe wersji 4.1.0 lub nowszej.

Jeśli chcesz przetestować i zweryfikować pakiet przed opublikowaniem go w publicznej galerii, możesz przekazać go do środowiska testowego, takiego jak int.nugettest.org zamiast nuget.org. Należy pamiętać, że pakiety przekazane do int.nugettest.org mogą nie być zachowywane.

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

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

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

3. Wybierz pozycję Utwórz i podaj nazwę klucza.

4. W obszarze Wybierz zakresy wybierz pozycję Wypchnij.

5. W obszarze Wybierz wzorzec globu pakietów>wprowadź *.

6. Wybierz pozycję Utwórz.

7. 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ą interfejsu wiersza polecenia Narzędzia NuGet

Użycie interfejsu wiersza polecenia NuGet (nuget.exe) jest alternatywą dla używania interfejsu wiersza polecenia platformy .NET:

1. Otwórz wiersz polecenia i przejdź do folderu zawierającego plik nupkg .

2. Uruchom następujące polecenie: Zastąp <nazwę pliku> pakietu nazwą pakietu i zastąp <wartość> klucza interfejsu API kluczem interfejsu API. Nazwa pliku pakietu jest połączeniem identyfikatora pakietu i numeru wersji z rozszerzeniem nupkg . Na przykład AppLogger.1.0.0.nupkg:

   nuget push <package filename> <api key value> -Source https://api.nuget.org/v3/index.json
   

   Wynik procesu publikowania jest wyświetlany w następujący sposób:

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

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

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:

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

   

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

Następne kroki

Gratulacje dotyczące tworzenia pakietu NuGet przy użyciu programu Visual Studio .NET Framework. Przejdź do następnego artykułu, aby dowiedzieć się, jak utworzyć pakiet NuGet za pomocą interfejsu wiersza polecenia NuGet.

Tworzenie pakietu przy użyciu interfejsu wiersza polecenia Narzędzia NuGet

Aby dowiedzieć się więcej o tym, co ma do zaoferowania NuGet, zobacz następujące artykuły:

• Publikowanie pakietu
• Tworzenie pakietu w wersji wstępnej
• Obsługa wielu platform docelowych
• Przechowywanie wersji pakietów
• Tworzenie zlokalizowanego pakietu