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

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

Szybki start dotyczy tylko użytkowników Windows. Jeśli używasz Visual Studio na Mac, zapoznaj się z narzędziami CLI dotnet.

Wymagania wstępne

• Zainstaluj program Visual Studio 2022 dla systemu Windows z dowolnym obciążeniem związanym z platformą .NET.

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

  Visual Studio 2017 lub nowsze wersje automatycznie zawierają funkcje NuGet po zainstalowaniu workloadu .NET.

• Zarejestruj się w celu uzyskania bezpłatnego konta na nuget.org , jeśli jeszcze go nie masz. Należy zarejestrować i potwierdzić konto, zanim będzie można przesłać pakiet NuGet.

• Zainstaluj Narzędzie wiersza poleceń NuGet, pobierając je z nuget.org. Dodaj plik nuget.exe do odpowiedniego folderu i dodaj ścieżkę folderu 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 Utwórz nowy projekt wybierz C#, Windows i Library na listach rozwijanych.

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

4. W oknie Konfiguruj nowy projekt wprowadź AppLogger jako nazwę projektu, a następnie wybierz 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 Release, jeśli zamiast tego skompilujesz tę 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. Aby zapoznać się z przykładem, zobacz UwP.

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 Project > Properties, a następnie wybierz kartę Application.

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.

   Important

   Należy nadać pakietowi identyfikator unikatowy dla nuget.org lub dowolnego używanego hosta. W przeciwnym razie wystąpi błąd. W tym szybkim starcie zalecamy umieszczenie Przykładu lub Testu w nazwie, ponieważ pakiet po opublikowaniu staje się 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 Properties/AssemblyInfo.cs w project, wybierając pozycję Project>Edytuj plik Project.

5. Po ustawieniu tych właściwości ustaw konfigurację rozwiązania Active w Build>Configuration Manager na Release i 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. W tym kroku używane są odpowiednie tokeny zastępcze do pozyskiwania informacji z pliku projektu.

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

1. Po otwarciu projektu w Solution Explorer, otwórz wiersz polecenia, wybierając Tools>Command Line>Developer Command Prompt.

   Wiersz polecenia zostanie otwarty w katalogu projektu, gdzie znajduje się plik AppLogger.csproj.

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

   NuGet tworzy manifest zgodny z nazwą projektu, w tym przypadku AppLogger.nuspec. Również zawiera 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 odniesieniu do pliku .nuspec.

4. Zapisz plik przed kontynuowaniem.

Uruchamianie polecenia pakietu

1. Po otwarciu projektu w Solution Explorer, otwórz wiersz polecenia, wybierając Tools>Command Line>Developer Command Prompt.

   Wiersz polecenia otwiera się 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.

Uzyskaj klucz interfejsu 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.

   

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.

Publikowanie z użyciem NuGet CLI

Użycie interfejsu wiersza polecenia NuGet (nuget.exe) jest alternatywą dla używania interfejsu wiersza polecenia .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 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.

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.

   

2. Na następnej stronie wybierz pozycję Lista, wyczyść pole 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.

Następne kroki

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

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

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