Udostępnij za pośrednictwem

Szybki start: tworzenie i publikowanie pakietu NuGet przy użyciu programu Visual Studio (tylko system Windows)

  • Artykuł

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

Przewodnik szybkiego startu dotyczy tylko użytkowników systemu Windows. Jeśli używasz komputera Mac, użyj .NET CLI.

Warunki wstępne

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

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

    Visual Studio 2017 i późniejsze automatycznie obejmuje funkcje NuGet podczas instalowania obciążenia związanego z platformą .NET.

  • Zainstaluj .NET CLI, jeśli nie jest jeszcze zainstalowany.

    W przypadku programu Visual Studio 2017 lub nowszego, .NET CLI jest automatycznie instalowane z każdym obciążeniem związanym z .NET Core. W przeciwnym razie zainstaluj zestaw SDK platformy .NET Core, aby uzyskać interfejs wiersza polecenia platformy .NET. Interfejs CLI dla .NET jest wymagany dla projektów .NET korzystających z formatu w stylu SDK (atrybut SDK). Domyślny szablon biblioteki klas .NET w programie Visual Studio 2017 i nowszych używa atrybutu SDK.

    Ważny

    Jeśli pracujesz z projektem w stylu innym niż SDK, zamiast tego wykonaj procedury opisane w artykule Tworzenie i publikowanie pakietu .NET Framework (Visual Studio), aby utworzyć i opublikować pakiet. Do tego artykułu zaleca się użycie .NET CLI. Chociaż można opublikować dowolny pakiet NuGet przy użyciu interfejsu wiersza polecenia NuGet, niektóre kroki opisane w tym artykule są specyficzne dla projektów w stylu zestawu SDK i interfejsu wiersza polecenia platformy .NET. Interfejs wiersza polecenia NuGet jest używany do projektów innych niż zestaw SDK (zazwyczaj .NET Framework).

  • zarejestruj się w celu uzyskania bezpłatnego konta na nuget.org, jeśli jeszcze go nie masz. Aby móc przekazać pakiet NuGet, musisz najpierw zarejestrować i potwierdzić konto.

  • Zainstaluj interfejs wiersza polecenia 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

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

  1. W programie Visual Studio wybierz pozycję Plik >Nowy>Projekt.

  2. W oknie Utwórz nowy projekt wybierz z list rozwijanych: C#, Windowsi Biblioteka.

  3. Na wyświetlonej liście szablonów projektów wybierz pozycję Biblioteka klas (z opisem projekt tworzenia biblioteki klas przeznaczonej dla platformy .NET lub .NET Standard), a następnie wybierz pozycję Dalej.

  4. W oknie Konfigurowanie nowego projektu wprowadź AppLoggerjako nazwę projektu, a następnie wybierz pozycję Dalej.

  5. W oknie Dodatkowe informacje wybierz odpowiednią Strukturę, a następnie wybierz Utwórz.

    Jeśli nie masz pewności, którą strukturę wybrać, najnowsza wersja jest dobrym wyborem i można ją łatwo zmienić później. Aby uzyskać informacje na temat, którego frameworku użyć, sprawdź When to target .NET 5.0 or .NET 6.0 vs. .NET Standard.

  6. Aby mieć pewność, że projekt został utworzony prawidłowo, wybierz pozycję Build>Build Solution. Biblioteka DLL znajduje się w folderze Debug (lub Release, jeśli zamiast tego zbudujesz tę konfigurację).

  7. (Opcjonalnie) W tym przewodniku szybkiego startu nie trzeba pisać żadnego dodatkowego kodu dla pakietu NuGet, ponieważ biblioteka klas szablonowa jest wystarczająca do utworzenia pakietu. Jeśli jednak chcesz, aby pakiet zawierał kod funkcjonalny, dołącz następujący kod:

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

Konfigurowanie właściwości pakietu

Po utworzeniu projektu można skonfigurować właściwości pakietu NuGet, wykonując następujące kroki:

  1. Wybierz projekt w eksploratorze rozwiązań , a następnie wybierz nazwa projektu><nazwa projektu> właściwości, gdzie nazwa projektu <> jest nazwą projektu.

  2. Rozwiń węzeł pakietu, a następnie wybierz pozycję Ogólne.

    Węzeł Package jest wyświetlany tylko dla projektów w stylu SDK w Visual Studio. Jeśli celujesz w projekt przeznaczony dla innego stylu niż SDK (zazwyczaj .NET Framework), przeprowadź migrację projektulub zobacz sekcję Tworzenie i publikowanie pakietu .NET Framework, aby uzyskać instrukcje krok po kroku.

    Zrzut ekranu przedstawiający właściwości pakietu NuGet w projekcie programu Visual Studio.

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

  4. Nadaj pakietowi unikatowy identyfikator pakietu i wypełnij wszelkie inne żądane właściwości. Tabela przedstawiająca sposób mapowania właściwości programu MSBuild (projektów w stylu zestawu SDK) na właściwości pliku .nuspec, zobacz pack targets. Aby uzyskać opis właściwości pliku .nuspec, zobacz .nuspec file reference. Wszystkie te właściwości przechodzą do manifestu .nuspec tworzonego przez program Visual Studio dla projektu.

    Ważny

    Należy nadać pakietowi identyfikator unikatowy dla nuget.org lub dowolnego używanego hosta. W przeciwnym razie wystąpi błąd. W tym szybkim przewodniku zalecamy umieszczenie Sample lub Test w nazwie, ponieważ proces publikacji sprawia, że pakiet staje się publicznie widoczny.

  5. (Opcjonalnie) Aby wyświetlić właściwości bezpośrednio w pliku projektu AppLogger.csproj, wybierz pozycję Project>Edit Project File.

    Karta AppLogger.csproj ładuje się.

    Ta opcja jest dostępna od programu Visual Studio 2017 dla projektów korzystających z atrybutu w stylu zestawu SDK. W przypadku wcześniejszych wersji programu Visual Studio należy wybrać pozycję Project>Unload Project, zanim będzie można edytować plik projektu.

Uruchom polecenie pakowanie

Aby utworzyć pakiet NuGet z projektu, wykonaj następujące kroki:

  1. Wybierz pozycję Buduj>Menedżer Konfiguracji, a następnie ustaw Aktywną konfigurację rozwiązania na Wydanie.

  2. Wybierz projekt AppLogger w eksploratorze rozwiązań , a następnie wybierz pozycję Pack.

    Program Visual Studio kompiluje projekt i tworzy plik .nupkg.

  3. Sprawdź okno Output w celu uzyskania szczegółowych informacji, które zawiera ścieżkę do pliku pakietu. W tym przykładzie zbudowany zestaw jest w bin\Release\net6.0, jak przystało na platformę docelową .NET 6.0.

    1>------ Build started: Project: AppLogger, Configuration: Release Any CPU ------
1>AppLogger -> d:\proj\AppLogger\AppLogger\bin\Release\net6.0\AppLogger.dll
1>Successfully created package 'd:\proj\AppLogger\AppLogger\bin\Release\AppLogger.1.0.0.nupkg'.
========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

  4. Jeśli w menu nie widzisz polecenia Pack, projekt prawdopodobnie nie jest projektem w stylu SDK i musisz użyć narzędzia CLI NuGet. przeprowadzić migrację projektu i użyć interfejsu wiersza polecenia platformy .NET lub zobacz Tworzenie i publikowanie pakietu .NET Framework, aby uzyskać instrukcje krok po kroku.

(Opcjonalnie) Generowanie pakietu na kompilacji

Program Visual Studio można skonfigurować tak, aby automatycznie generował pakiet NuGet podczas kompilowania projektu:

  1. Wybierz projekt w eksploratorze rozwiązań , a następnie wybierz nazwę projektu><project> Properties, gdzie <nazwa projektu> jest nazwą projektu (w tym przypadku AppLogger).

  2. Rozwiń węzeł pakietu Package, wybierz pozycję Ogólne, a następnie wybierz pozycję Wygeneruj pakiet NuGet na kompilację.

    Zrzut ekranu przedstawiający właściwości pakietu z wybraną funkcją Generowanie pakietu NuGet podczas kompilacji.

Uwaga

Po automatycznym wygenerowaniu pakietu dodatkowy czas do spakowania zwiększa całkowity czas kompilacji projektu.

(Opcjonalnie) Pakowanie za pomocą programu MSBuild

Alternatywą dla używania polecenia menu Pack jest to, że NuGet 4.x+ i MSBuild 15.1+ obsługują cel pack, gdy projekt zawiera niezbędne dane pakietu.

  1. Po otwarciu projektu w Eksploratorze rozwiązań , otwórz wiersz polecenia, wybierając Narzędzia>Wiersz polecenia>Wiersz poleceń dewelopera.

    Wiersz polecenia otwiera się w katalogu projektu.

  2. Uruchom następujące polecenie: msbuild -t:pack.

Aby uzyskać więcej informacji, zobacz Create a package using MSBuild.

Publikowanie pakietu

Po utworzeniu pliku .nupkg opublikuj go w nuget.org przy użyciu CLI .NET lub CLI NuGet, wraz z kluczem API uzyskanym z nuget.org.

Notatka

  • 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 je ukryjesz. Aby hostować pakiety prywatnie, zobacz Hostowanie własnych źródeł danych NuGet.

Uzyskaj klucz API

Przed opublikowaniem pakietu NuGet utwórz klucz 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 API.

  3. Wybierz pozycję Utwórzi podaj nazwę klucza.

  4. W obszarze wybierz pozycję Zakresy, a następnie wybierz pozycję Wypychanie.

  5. W obszarze Wybierz pakiety>Wzorzec globuwprowadź *.

  6. Wybierz pozycję Utwórz.

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

    Zrzut ekranu przedstawiający nowy klucz interfejsu API z linkiem do kopiowania.

Ważny

  • 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 API, jeśli nie chcesz już przesyłać pakietów.

'Scoping' umożliwia tworzenie oddzielnych kluczy 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 dostępu interfejsu API z ograniczonym zakresem.

Publikowanie za pomocą interfejsu wiersza polecenia platformy .NET lub interfejsu wiersza polecenia NuGet

Każde z poniższych narzędzi interfejsu wiersza polecenia umożliwia wypchnięcie pakietu na serwer i opublikowanie go. Wybierz kartę dla narzędzia CLI: .NET CLI lub NuGet CLI.

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

W folderze zawierającym plik .nupkg uruchom następujące polecenie. Określ nazwę pliku .nupkg i zastąp wartość klucza 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.

Notatka / Uwaga

Jeśli chcesz uniknąć opublikowania swojego pakietu testowego na nuget.org, możesz wypchnąć go do testowej strony nuget.org pod adresem https://int.nugettest.org. Należy pamiętać, że pakiety przekazane do int.nugettest.org mogą nie być zachowane.

Błędy publikowania

Błędy z polecenia push 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, polecenie push daje 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 ponów próbę push polecenia.

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.orgwybierz swoją nazwę użytkownika w prawym górnym rogu, a następnie wybierz pozycję Zarządzaj pakietami.

Notatka

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 jest wyświetlany w obszarze Pakiety nieznajdujące się na liście, a na stronie pakietu jest wyświetlany następujący komunikat:

Zrzut ekranu przedstawiający komunikat publikowania wyświetlany podczas przekazywania pakietu do nuget.org.

Opublikowałeś teraz pakiet NuGet na 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 z pustą biblioteką klas) lub nie chcesz, aby pakiet był widoczny, możesz usunąć listę pakietu, aby ukryć go przed wynikami wyszukiwania:

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

    Zrzut ekranu przedstawiający ikonę Edytuj dla listy pakietów w nuget.org.

  2. Na następnej stronie wybierz pozycję Lista, usuń zaznaczenie listy w wynikach wyszukiwania, a następnie wybierz Zapisz.

    Zrzut ekranu przedstawiający wyczyszczenie pola wyboru Lista dla pakietu w nuget.org.

Pakiet jest teraz wyświetlany w sekcji Pakiety nielistowane w Zarządzaj pakietami i nie jest już wyświetlany w wynikach wyszukiwania.

Notatka

Aby uniknąć upublicznienia pakietu testowego na nuget.org, możesz przesłać go na witrynę testową nuget.org pod adresem https://int.nugettest.org. Należy pamiętać, że pakiety przesłane do int.nugettest.org mogą nie być zachowywane.

Dodawanie pliku readme lub innego pliku

Aby bezpośrednio określić pliki do uwzględnienia w pakiecie, zmodyfikuj plik projektu i dodaj właściwość content:

<ItemGroup>
  <Content Include="readme.txt">
    <Pack>true</Pack>
    <PackagePath>\</PackagePath>
  </Content>
</ItemGroup>

W tym przykładzie właściwość określa plik o nazwie readme.txt w katalogu głównym projektu. Program Visual Studio wyświetla zawartość tego pliku jako zwykły tekst natychmiast po zainstalowaniu pakietu. Pliki Readme nie są wyświetlane dla pakietów zainstalowanych jako zależności. Na przykład oto plik readme pakietu HtmlAgilityPack:

1 ----------------------------------------------------
2 ---------- Html Agility Pack Nuget Readme ----------
3 ----------------------------------------------------
4
5 ----Silverlight 4 and Windows Phone 7.1+ projects-----
6 To use XPATH features: System.Xml.Xpath.dll from the 3 Silverlight 4 SDK must be referenced.
7 This is normally found at
8 %ProgramFiles(x86)%\Microsoft SDKs\Microsoft SDKs\Silverlight\v4.0\Libraries\Client
9 or
10 %ProgramFiles%\Microsoft SDKs\Microsoft SDKs\Silverlight\v4.0\Libraries\Client
11
12 ----Silverlight 5 projects-----
13 To use XPATH features: System.Xml.Xpath.dll from the Silverlight 5 SDK must be referenced.
14 This is normally found at
15 %ProgramFiles(x86)%\Microsoft SDKs\Microsoft SDKs\Silverlight\v5.0\Libraries\Client
16 or
17 %ProgramFiles%\Microsoft SDKs\Microsoft SDKs\Silverlight\v5.0\Libraries\Client

Notatka

Jeśli dodasz tylko readme.txt w katalogu głównym projektu bez uwzględniania go we właściwości content pliku projektu, nie zostanie on uwzględniony w pakiecie.

Znajdź filmy NuGet na Channel 9 i YouTube.

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

Tworzenie pakietu przy użyciu interfejsu wiersza polecenia NuGet

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