Szybki start: tworzenie i publikowanie pakietu NuGet przy użyciu programu Visual Studio (tylko system Windows)
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 Szybki start dotyczy tylko użytkowników systemu Windows. Jeśli używasz Visual Studio dla komputerów Mac, zobacz Tworzenie pakietu NuGet z istniejących projektów biblioteki lub używanie interfejsu wiersza polecenia platformy .NET.
Wymagania 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.com lub użyć wersji Professional lub Enterprise.
Program Visual Studio 2017 lub nowszy automatycznie obejmuje funkcje NuGet podczas instalowania programu . Obciążenie związane z platformą NET.
Zainstaluj interfejs wiersza polecenia platformy .NET, jeśli nie został jeszcze zainstalowany.
W przypadku programu Visual Studio 2017 lub nowszego interfejs wiersza polecenia platformy .NET jest automatycznie instalowany z dowolnym obciążeniem powiązanym z platformą .NET Core. W przeciwnym razie zainstaluj zestaw .NET Core SDK , aby uzyskać interfejs wiersza polecenia platformy .NET. Interfejs wiersza polecenia platformy .NET jest wymagany dla projektów platformy .NET korzystających z formatu zestawu SDK (atrybutu zestawu SDK). Domyślny szablon biblioteki klas platformy .NET w programie Visual Studio 2017 i nowszych używa atrybutu ZESTAWU SDK.
Ważne
Jeśli pracujesz z projektem w stylu innego niż zestaw SDK, wykonaj procedury opisane w temacie Tworzenie i publikowanie pakietu .NET Framework (Visual Studio), aby utworzyć i opublikować pakiet. W tym artykule zaleca się interfejs wiersza polecenia platformy .NET. 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 w projektach innych niż zestaw SDK (zazwyczaj .NET Framework).
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
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:
W programie Visual Studio wybierz pozycje Plik>Nowy>Projekt.
W oknie Tworzenie nowego projektu wybierz pozycję C#, Windows i Biblioteka na listach rozwijanych.
Na wynikowej liście szablonów projektów wybierz pozycję Biblioteka klas (z opisem Projekt do tworzenia biblioteki klas, która jest przeznaczona dla platformy .NET lub .NET Standard), a następnie wybierz pozycję Dalej.
W oknie Konfigurowanie nowego projektu wprowadź ciąg AppLogger jako nazwę projektu, a następnie wybierz przycisk Dalej.
W oknie Dodatkowe informacje wybierz odpowiednią platformę, a następnie wybierz pozycję 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 platformy, zobacz Kiedy należy używać platformy .NET 5.0 lub .NET 6.0 w porównaniu z platformą .NET Standard.
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ę).
(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 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:
Wybierz projekt w Eksplorator rozwiązań, a następnie wybierz pozycję Project><project name> Properties (Właściwości projektu), gdzie <nazwa projektu to nazwa> projektu.
Rozwiń węzeł Pakiet, a następnie wybierz pozycję Ogólne.
Węzeł Pakiet jest wyświetlany tylko dla projektów w stylu zestawu SDK w programie Visual Studio. Jeśli projekt jest przeznaczony dla projektu w stylu innym niż ZESTAW SDK (zazwyczaj .NET Framework), przeprowadź migrację projektu lub zobacz Tworzenie i publikowanie pakietu .NET Framework, aby uzyskać instrukcje krok po kroku.
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.
Nadaj pakietowi unikatowy identyfikator pakietu i wypełnij wszystkie inne żądane właściwości. Aby zapoznać się z tabelą przedstawiającą 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 (Obiekty docelowe pakietów). Opis właściwości pliku nuspec można znaleźć w dokumentacji pliku nuspec. Wszystkie te właściwości przechodzą do manifestu tworzonego
.nuspecprzez program Visual Studio dla projektu.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.
(Opcjonalnie) Aby wyświetlić właściwości bezpośrednio w pliku projektu AppLogger.csproj, wybierz pozycję Project Edit Project File (Edytuj plik projektu>).
Zostanie załadowana karta AppLogger.csproj .
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 (Projekt>rozładuj projekt), zanim będzie można edytować plik projektu.
Uruchamianie polecenia pakietu
Aby utworzyć pakiet NuGet z projektu, wykonaj następujące kroki:
Wybierz pozycję Build Configuration Manager (Kompiluj>program Configuration Manager), a następnie ustaw opcję Active solution configuration (Aktywna konfiguracja rozwiązania) na Release (Wydanie).
Wybierz projekt AppLogger w Eksplorator rozwiązań, a następnie wybierz pozycję Pack (Pakiet).
Program Visual Studio kompiluje projekt i tworzy plik nupkg .
Sprawdź okno Dane wyjściowe, aby uzyskać szczegółowe informacje, które zawiera ścieżkę do pliku pakietu. W tym przykładzie wbudowany zestaw znajduje się w elemecie bin\Release\net6.0 , ponieważ pasuje do docelowego elementu docelowego platformy .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 ==========Jeśli nie widzisz polecenia Pack w menu, projekt prawdopodobnie nie jest projektem w stylu zestawu SDK i musisz użyć interfejsu wiersza polecenia NuGet. Migrowanie projektu i używanie 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:
Wybierz projekt w Eksplorator rozwiązań, a następnie wybierz pozycję Project><project name> Properties (Właściwości projektu), gdzie <nazwa projektu to nazwa> projektu (AppLogger w tym przypadku).
Rozwiń węzeł Pakiet, wybierz pozycję Ogólne, a następnie wybierz pozycję Generuj pakiet 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 nuGet 4.x+ i MSBuild 15.1+ obsługuje pack element docelowy, gdy projekt zawiera niezbędne dane pakietu:
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.
Uruchom następujące polecenie:
msbuild -t:pack.
Aby uzyskać więcej informacji, zobacz Tworzenie pakietu przy użyciu programu MSBuild.
Publikowanie pakietu
Po utworzeniu pliku nupkg opublikuj go w nuget.org przy użyciu interfejsu wiersza polecenia platformy .NET lub interfejsu wiersza polecenia NuGet wraz 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
Przed opublikowaniem pakietu NuGet utwórz klucz 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ą 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ę narzędzia interfejsu wiersza polecenia — interfejs wiersza polecenia platformy .NET lub interfejs wiersza polecenia NuGet.
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 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.
Dodawanie pliku readme lub innego pliku
Aby bezpośrednio określić pliki do uwzględnienia w pakiecie, zmodyfikuj plik projektu i dodaj content właściwość:
<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
Uwaga
Jeśli dodasz tylko readme.txt w katalogu głównym projektu bez uwzględniania go we content właściwości pliku projektu, nie zostanie on uwzględniony w pakiecie.
Powiązany film wideo
Więcej filmów NuGet można znaleźć w witrynach 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.
Aby dowiedzieć się więcej o tym, co ma do zaoferowania NuGet, zobacz następujące artykuły: