Wprowadzenie do NuGet

Podstawowym narzędziem dla każdej nowoczesnej platformy programistycznej jest mechanizm, za pomocą którego deweloperzy mogą tworzyć, udostępniać i korzystać z przydatnego kodu. Często taki kod jest dołączany do "pakietów", które zawierają skompilowany kod (jako biblioteki DLL) wraz z inną zawartością wymaganą w projektach korzystających z tych pakietów.

W przypadku platformy .NET (w tym platformy .NET Core) obsługiwany przez firmę Microsoft mechanizm udostępniania kodu jest NuGet, który definiuje sposób tworzenia, hostowania i korzystania pakietów dla platformy .NET oraz udostępnia narzędzia dla każdej z tych ról.

Po prostu pakiet NuGet to pojedynczy plik ZIP z .nupkg rozszerzeniem zawierającym skompilowany kod (DLL), inne pliki związane z tym kodem oraz opisowy manifest zawierający informacje takie jak numer wersji pakietu. Deweloperzy z kodem, aby udostępniać pakiety i publikować je na hoście publicznym lub prywatnym. Użytkownicy pakietów uzyskują te pakiety z odpowiednich hostów, dodają je do swoich projektów, a następnie wywołają funkcjonalność pakietu w kodzie projektu. NuGet następnie obsługuje wszystkie szczegóły pośrednie.

Ponieważ NuGet obsługuje hosty prywatne obok publicznego hosta nuget.org, można użyć NuGet pakietów do udostępniania kodu, który jest wyłączny dla organizacji lub grupy roboczej. Możesz również użyć pakietów NuGet jako wygodnego sposobu, aby uwzględnić własny kod do użycia w niczym, ale w własnych projektach. Krótko mówiąc, pakiet NuGet jest współużytkową jednostką kodu, ale nie wymaga ani nie oznacza żadnych konkretnych środków udostępniania.

Przepływ pakietów między twórcami, hostami i użytkownikami

W roli hosta publicznego sam NuGet utrzymuje centralne repozytorium ponad 100 000 unikatowych pakietów w nuget.org. Te pakiety są codziennie stosowane przez miliony deweloperów platformy .NET/.NET Core. NuGet umożliwia również hostowanie pakietów prywatnie w chmurze (np. w Azure DevOps), w sieci prywatnej, a nawet w lokalnym systemie plików. Dzięki temu te pakiety są dostępne tylko dla tych deweloperów, którzy mają dostęp do hosta, co daje możliwość udostępniania pakietów określonym grupom odbiorców. Opcje zostały wyjaśnione w temacie Hosting własnych źródeł danych NuGet. Za pomocą opcji konfiguracji można również kontrolować dokładnie, które hosty mogą być dostępne przez dowolny dany komputer, zapewniając w ten sposób, że pakiety są uzyskiwane z określonych źródeł, a nie z repozytorium publicznego, takiego jak nuget.org.

Niezależnie od jego charakteru host służy jako punkt połączenia między twórcami pakietów a konsumentami pakietów. Twórcy tworzą przydatne pakiety NuGet i publikują je na hoście. Następnie użytkownicy szukają przydatnych i zgodnych pakietów na hostach z ułatwieniami dostępu, pobieraniu i dołączaniu tych pakietów w swoich projektach. Po zainstalowaniu w projekcie interfejsy API pakietów są dostępne dla reszty kodu projektu.

Relationship between package creators, package hosts, and package consumers

Zgodność określania wartości docelowej pakietu

Pakiet "zgodny" oznacza, że zawiera zestawy utworzone dla co najmniej jednej docelowej platformy .NET Framework zgodnej z platformą docelową projektu. Deweloperzy mogą tworzyć pakiety specyficzne dla jednej platformy, podobnie jak w przypadku kontrolek platformy UNIWERSALNEJ lub mogą obsługiwać szerszy zakres celów. Aby zmaksymalizować zgodność pakietu, deweloperzy mają docelową platformę .NET Standard, z której mogą korzystać wszystkie projekty .NET i .NET Core. Jest to najbardziej wydajny sposób dla twórców i konsumentów, ponieważ pojedynczy pakiet (zwykle zawierający pojedynczy zestaw) działa dla wszystkich projektów zużywających.

Deweloperzy pakietów, którzy wymagają interfejsów API spoza platformy .NET Standard, z drugiej strony, tworzą oddzielne zestawy dla różnych platform docelowych, które chcą obsługiwać i dołączają wszystkie te zestawy w tym samym pakiecie (nazywanym "obsługą wielokierunkową"). Gdy użytkownik instaluje taki pakiet, NuGet wyodrębnia tylko te zestawy, które są potrzebne przez projekt. Minimalizuje to ślad pakietu w końcowej aplikacji i/lub zestawach utworzonych przez ten projekt. Pakiet wielokierunkowy jest oczywiście trudniejsze dla jego twórcy do utrzymania.

Uwaga

Aby uzyskać wskazówki dotyczące składników aplikacji a bibliotek wielokrotnego użytku, zobacz dokumentację platformy .NET Standard w temacie.

narzędzia NuGet

Oprócz obsługi hostingu NuGet udostępnia również różne narzędzia używane zarówno przez twórców, jak i konsumentów. Zobacz Instalowanie NuGet narzędzi klienckich, aby uzyskać określone narzędzia.

Narzędzie Platformy Odpowiednie scenariusze Opis
Interfejs wiersza polecenia dotnet Wszystko Tworzenie, zużycie Narzędzie interfejsu wiersza polecenia dla bibliotek .NET Core i .NET Standard oraz dla projektów w stylu zestawu SDK przeznaczonych dla .NET Framework (zobacz atrybut zestawu SDK). Zapewnia pewne NuGet możliwości interfejsu wiersza polecenia bezpośrednio w łańcuchu narzędzi platformy .NET Core. Podobnie jak w przypadku interfejsu nuget.exe wiersza polecenia, interfejs wiersza polecenia dotnet nie współdziała z projektami Visual Studio.
Interfejs wiersza polecenia nuget.exe Wszystko Tworzenie, zużycie Narzędzie interfejsu wiersza polecenia dla bibliotek .NET Framework i projektów innych niż ZESTAW SDK przeznaczonych dla bibliotek .NET Standard. Zapewnia wszystkie NuGet możliwości, a niektóre polecenia stosowane specjalnie do twórców pakietów, niektóre mają zastosowanie tylko do konsumentów, a inne mają zastosowanie do obu tych opcji. Na przykład twórcy pakietów używają nuget pack polecenia , aby utworzyć pakiet z różnych zestawów i powiązanych plików, użytkownicy pakietów używają do dołączania pakietów do folderu projektu, a wszyscy używają nuget confignuget install do ustawiania zmiennych konfiguracji NuGet. Jako narzędzie niezależne od platformy interfejs wiersza polecenia NuGet nie współdziała z projektami Visual Studio.
Konsola menedżera pakietów Visual Studio Windows Zużycie Udostępnia polecenia programu PowerShell do instalowania pakietów i zarządzania nimi w projektach Visual Studio.
Interfejs użytkownika menedżera pakietów Visual Studio Windows Zużycie Zapewnia łatwy w użyciu interfejs użytkownika do instalowania pakietów i zarządzania nimi w projektach Visual Studio.
Zarządzanie interfejsem użytkownika NuGet Visual Studio dla komputerów Mac Zużycie Zapewnij łatwy w użyciu interfejs użytkownika do instalowania pakietów i zarządzania nimi w projektach Visual Studio dla komputerów Mac.
MSBuild Windows Tworzenie, zużycie Zapewnia możliwość tworzenia pakietów i przywracania pakietów używanych w projekcie bezpośrednio za pośrednictwem łańcucha narzędzi MSBuild.

Jak widać, narzędzia NuGet, z którymi pracujesz, zależą znacznie od tego, czy tworzysz, zużywasz, czy publikujesz pakiety, a także platformę, z którą pracujesz. Twórcy pakietów są zwykle również konsumentami, ponieważ opierają się na funkcjach, które istnieją w innych pakietach NuGet. I te pakiety, oczywiście, mogą z kolei zależeć od innych.

Aby uzyskać więcej informacji, zacznij od przepływu pracy tworzenia pakietów i przepływu pracy Zużycie pakietów .

Zarządzanie zależnościami

Możliwość łatwego budowania pracy innych jest jedną z najbardziej zaawansowanych funkcji systemu zarządzania pakietami. W związku z tym większość NuGet zarządza tym drzewem zależności lub "grafem" w imieniu projektu. Po prostu musisz martwić się tylko o te pakiety, które są bezpośrednio używane w projekcie. Jeśli którykolwiek z tych pakietów korzysta z innych pakietów (z kolei może korzystać z innych), NuGet zajmuje się wszystkimi zależnościami na poziomie podrzędnym.

Na poniższej ilustracji przedstawiono projekt, który zależy od pięciu pakietów, które z kolei zależą od wielu innych.

An example NuGet dependency graph for a .NET project

Zwróć uwagę, że niektóre pakiety są wyświetlane wiele razy na wykresie zależności. Na przykład istnieją trzy różne konsumentów pakietu B, a każdy odbiorca może również określić inną wersję dla tego pakietu (nie jest pokazana). Jest to typowe wystąpienie, szczególnie w przypadku powszechnie używanych pakietów. NuGet na szczęście wykonuje całą ciężką pracę, aby określić dokładnie, która wersja pakietu B spełnia wszystkich użytkowników. NuGet następnie wykonuje to samo dla wszystkich innych pakietów, bez względu na to, jak głęboki jest wykres zależności.

Aby uzyskać więcej informacji na temat sposobu NuGet wykonywania tej usługi, zobacz Rozwiązywanie zależności.

Śledzenie odwołań i przywracanie pakietów

Ponieważ projekty mogą łatwo przenosić się między komputerami deweloperskimi, repozytoriami kontroli źródła, serwerami kompilacji itd., bardzo niepraktyczne jest zachowanie zestawów binarnych pakietów NuGet bezpośrednio powiązanych z projektem. W ten sposób każda kopia projektu niepotrzebnie się rozdęła (a tym samym marnowałaby miejsce w repozytoriach kontroli źródła). Bardzo trudno byłoby również zaktualizować pliki binarne pakietów do nowszych wersji, ponieważ aktualizacje musiałyby być stosowane we wszystkich kopiach projektu.

NuGet zamiast tego utrzymuje prostą listę odwołań pakietów, na których zależy projekt, w tym zarówno zależności najwyższego poziomu, jak i na poziomie podrzędnym. Oznacza to, że za każdym razem, gdy instalujesz pakiet z określonego hosta w projekcie, NuGet rejestruje identyfikator pakietu i numer wersji na liście referencyjnej. (Odinstalowanie pakietu, oczywiście, usuwa go z listy). NuGet następnie zapewnia metodę przywracania wszystkich odwołanych pakietów po żądaniu, zgodnie z opisem w temacie Przywracanie pakietu.

A NuGet reference list is created on package installation and can be used to restore packages elsewhere

Tylko lista odwołań NuGet może następnie ponownie zainstalować — czyli przywrócić — wszystkie te pakiety z hostów publicznych i/lub prywatnych w dowolnym późniejszym czasie. Podczas zatwierdzania projektu do kontroli źródła lub udostępniania go w inny sposób należy dołączyć tylko listę referencyjną i wykluczyć wszystkie pliki binarne pakietu (zobacz Pakiety i kontrola źródła).

Komputer odbierający projekt, taki jak serwer kompilacji, uzyskując kopię projektu w ramach zautomatyzowanego systemu wdrażania, po prostu prosi NuGet o przywrócenie zależności zawsze wtedy, gdy są potrzebne. W tym celu systemy kompilacji, takie jak Azure DevOps, zapewniają kroki "NuGet przywracania". Podobnie, gdy deweloperzy uzyskują kopię projektu (tak jak podczas klonowania repozytorium), mogą wywołać polecenie takie jak nuget restore (interfejs wiersza polecenia NuGet), dotnet restore (interfejs wiersza polecenia dotnet) lub Install-Package (Menedżer pakietów Konsola) w celu uzyskania wszystkich niezbędnych pakietów. Visual Studio ze swojej strony automatycznie przywraca pakiety podczas kompilowania projektu (pod warunkiem włączenia automatycznego przywracania zgodnie z opisem w temacie Przywracanie pakietu).

Oczywiście podstawową rolą NuGet, w której deweloperzy są zainteresowani, jest utrzymanie tej listy referencyjnej w imieniu projektu i zapewnienie środków efektywnego przywracania (i aktualizowania) tych odwołanych pakietów. Ta lista jest przechowywana w jednym z dwóch formatów zarządzania pakietami, ponieważ są one nazywane:

  • PackageReference (lub "odwołania do pakietu w plikach projektu") | (NuGet 4.0+) Utrzymuje listę zależności najwyższego poziomu projektu bezpośrednio w pliku projektu, więc nie jest potrzebny żaden oddzielny plik. Skojarzony plik obj/project.assets.json, jest generowany dynamicznie w celu zarządzania ogólnym grafem zależności pakietów używanych przez projekt wraz ze wszystkimi zależnościami na poziomie podrzędnym. Funkcja PackageReference jest zawsze używana przez projekty platformy .NET Core.

  • packages.config: (NuGet 1.0+) Plik XML, który utrzymuje płaską listę wszystkich zależności w projekcie, w tym zależności innych zainstalowanych pakietów. Zainstalowane lub przywrócone pakiety są przechowywane w folderze packages .

Format zarządzania pakietami jest stosowany w dowolnym projekcie zależy od typu projektu i dostępnej wersji NuGet (i/lub Visual Studio). Aby sprawdzić, jaki format jest używany, po prostu poszukaj packages.config go w katalogu głównym projektu po zainstalowaniu pierwszego pakietu. Jeśli nie masz tego pliku, poszukaj w pliku projektu bezpośrednio <elementu PackageReference> .

Jeśli masz wybór, zalecamy użycie funkcji PackageReference. packages.config jest utrzymywany do starszych celów i nie jest już aktywnie opracowywany.

Porada

Różne nuget.exe polecenia interfejsu wiersza polecenia, takie jak nuget install, nie dodają automatycznie pakietu do listy odwołań. Lista jest aktualizowana podczas instalowania pakietu przy użyciu Visual Studio Menedżer pakietów (interfejsu użytkownika lub konsoli) oraz przy użyciu dotnet.exe interfejsu wiersza polecenia.

Co jeszcze NuGet zrobić?

Do tej pory poznaliśmy następujące cechy NuGet:

  • NuGet zapewnia centralne repozytorium nuget.org z obsługą hostingu prywatnego.
  • NuGet udostępnia narzędzia potrzebne deweloperom do tworzenia, publikowania i używania pakietów.
  • Co najważniejsze, NuGet utrzymuje listę referencyjną pakietów używanych w projekcie oraz możliwość przywracania i aktualizowania tych pakietów z tej listy.

Aby te procesy działały wydajnie, NuGet wykonuje pewne optymalizacje w tle. Przede wszystkim NuGet zarządza pamięcią podręczną pakietów i folderem pakietów globalnych w celu instalacji skrótów i ponownej instalacji. Pamięć podręczna pozwala uniknąć pobierania pakietu, który został już zainstalowany na maszynie. Folder pakietów globalnych umożliwia wielu projektom współużytkowania tego samego zainstalowanego pakietu, co zmniejsza ogólny rozmiar NuGet na komputerze. Folder pamięci podręcznej i pakietów globalnych jest również bardzo przydatny podczas częstego przywracania większej liczby pakietów, jak na serwerze kompilacji. Aby uzyskać więcej informacji na temat tych mechanizmów, zobacz Zarządzanie globalnymi pakietami i folderami pamięci podręcznej.

W ramach pojedynczego projektu NuGet zarządza ogólnym grafem zależności, który ponownie obejmuje rozpoznawanie wielu odwołań do różnych wersji tego samego pakietu. Często projekt przyjmuje zależność od co najmniej jednego pakietu, które mają te same zależności. Niektóre z najbardziej przydatnych pakietów narzędziowych na nuget.org są stosowane przez wiele innych pakietów. W całym grafie zależności można łatwo mieć dziesięć różnych odwołań do różnych wersji tego samego pakietu. Aby uniknąć wprowadzenia wielu wersji tego pakietu do samej aplikacji, NuGet ustalić, która wersja może być używana przez wszystkich użytkowników. (Aby uzyskać więcej informacji, zobacz Rozwiązywanie zależności).

Poza tym NuGet zachowuje wszystkie specyfikacje związane ze strukturą pakietów (w tym lokalizację i symbole debugowania) oraz sposób ich przywołowania (w tym zakresy wersji i wersje wstępne). NuGet udostępnia również różne interfejsy API do pracy z jego usługami programowo i zapewnia obsługę deweloperów, którzy piszą Visual Studio rozszerzenia i szablony projektów.

Poświęć chwilę na przejrzenie spisu treści dla tej dokumentacji i zobaczysz, że wszystkie te możliwości są tam reprezentowane, wraz z informacjami o wersji pochodzącymi z początków NuGet.

Więcej NuGet filmów wideo można znaleźć w witrynach Channel 9 i YouTube.

Komentarze, współtworzenie i problemy

Na koniec z zadowoleniem przyjmujemy komentarze i współtworzenie tej dokumentacji — wystarczy wybrać polecenia Feedback and Edit w górnej części dowolnej strony lub odwiedzić repozytorium dokumentacji i listę problemów z dokumentami na GitHub.

Zachęcamy również do udziału w NuGet się za pośrednictwem różnych repozytoriów GitHub; NuGet problemy można znaleźć w witrynie https://github.com/NuGet/home/issues.

Ciesz się swoim NuGet doświadczeniem!