.NET Conf

Nowoczesne środowisko programistyczne .NET opiera się w dużej mierze na systemie zarządzania pakietami NuGet, który całkowicie zmienił podejście do wymiany kodu oraz kontroli zależności w projektach. Sprawna obsługa NuGet wymaga dogłębnej znajomości package restore, zaawansowanej konfiguracji plików nuget.config, właściwego wykorzystania prywatnych źródeł i skutecznych mechanizmów autoryzacyjnych. W realiach, gdzie firmy coraz częściej wdrażają własne repozytoria i rygorystycznie podchodzą do bezpieczeństwa, umiejętności efektywnego zarządzania ekosystemem NuGet są niezbędne dla każdego programisty .NET.

Spis treści [odkryj]

Mechanizmy package restore w ekosystemie .NET

Mechanizm package restore to kluczowa funkcjonalność, pozwalająca na automatyczne pobieranie i instalację zależności bez konieczności ich przechowywania w systemie kontroli wersji. Proces restore znacząco upraszcza utrzymanie czystego środowiska programistycznego i ogranicza rozmiar repozytoriów, eliminując konieczność umieszczania dużych plików binarnych.

Restore działa, instalując zależności zdefiniowane w pliku projektu lub w packages.config – zaczynając od bezpośrednich, poprzez wszystkie zależności z grafu. Jeśli pakiet nie znajduje się lokalnie, NuGet pobiera go z local global packages lub HTTP cache. W przypadku ich braku, wykorzystuje wszystkie skonfigurowane źródła pakietów.

Podczas restore, NuGet pobiera pakiet z pierwszego dostępnego źródła, niezależnie od kolejności skonfigurowanej w pliku nuget.config. Po nieudanej próbie, błąd zgłaszany jest względem ostatniego źródła, co może utrudniać diagnostykę problemów.

Najważniejsze metody uruchamiania restore to:

  • dotnet restore,
  • automatyczne restore przy dotnet build/run (od .NET Core 2.0),
  • polecenie msbuild -t:restore dla niestandardowych projektów SDK,
  • w Visual Studio restore uruchamiane automatycznie przez edytor.

Architektura i zarządzanie plikami nuget.config

nuget.config stanowi centralny plik konfiguracyjny systemu NuGet, będąc plikiem XML przechowującym ustawienia klucz/wartość i kolekcje ustawień. NuGet korzysta z hierarchii – ustawienia bliższe konkretnego projektu mają priorytet. Elementy pojedyncze zastępują starsze wartości, a kolekcje (np. packageSources) są łączone.

Lokalizacja nuget.config zależy od platformy operacyjnej:

  • w Windows: %appdata%\NuGet\NuGet.Config,
  • w Mac/Linux: ~/.config/NuGet/NuGet.Config,
  • w katalogu repozytorium – rekomendowane dla spójności i powtarzalności konfiguracji.

Prawidłowa konfiguracja prywatnych źródeł w nuget.config wymaga staranności szczególnie w sekcji packageSources. Zarządzanie konfiguracją realizowane jest przez polecenie config w NuGet CLI, z domyślnym zapisem do pliku użytkownika, a z przełącznikiem -configFile – do wskazanego pliku.

  • Klucze w nuget.config są wrażliwe na wielkość liter – różne wielkości traktowane są jako odrębne wpisy,
  • edycja plików na poziomie globalnym wymaga uprawnień administratora,
  • możliwe jest używanie własnych nazw plików zamiast tylko nuget.config.

Wdrażanie i zarządzanie prywatnymi źródłami pakietów

Prywatne źródła pakietów to podstawa korporacyjnego ekosystemu NuGet. Udostępnianie kodu w ramach organizacji odbywa się przez własne serwery NuGet lub hostowane rozwiązania chmurowe. W Visual Studio dodajemy źródło przez Tools → NuGet Package Manager → Package Manager Settings.

Dodając prywatne źródło, należy określić:

  • nazwę źródła (np. InternalFeed),
  • adres URL (np. https://nuget.mojafirma.pl/nuget),
  • podanie poświadczeń, jeżeli wymagane (Windows Auth, tokeny API),
  • wybór źródła w Manage NuGet Packages podczas instalacji/aktualizacji pakietu.

Lokalne źródła konfigurujemy również przez nuget.config z wpisem:

<packageSources>
    <add key="CustomNuGet" value="http://localhost:81/nuget/" />
</packageSources>

W przypadku integracji z Azure DevOps istotne jest prawidłowe wprowadzenie sekcji packageSourceCredentials. W zaawansowanych scenariuszach stosujemy Azure Artifact Credential Provider oraz zmienne środowiskowe do automatyzacji procesu pobierania poświadczeń.

Systemy autoryzacji oraz mechanizmy uwierzytelniania

Bezpieczeństwo prywatnych źródeł NuGet opiera się na skutecznych systemach autoryzacji i uwierzytelniania.

  • poświadczenia trzymane w plikach konfiguracyjnych,
  • uzyskiwane ze zmiennych środowiskowych,
  • automatycznie zarządzane przez credential provider (najwyższy poziom bezpieczeństwa).

W przypadku zapytań HTTP NuGet najpierw wykonuje żądanie bez uwierzytelnienia, a po błędzie 401 przeszukuje skonfigurowane poświadczenia. Credential providers zintegrowane z Visual Studio lub CLI automatyzują pobieranie i odświeżanie tokenów.

Dla dotnet.exe uwierzytelnianie interaktywne uruchamiamy przez –interactive, postępując zgodnie z instrukcjami autoryzacji przez przeglądarkę.

Narzędzia i najlepsze praktyki w obsłudze NuGet

Najważniejsze narzędzia NuGet w codziennej pracy to:

  • NuGet CLI (nuget.exe) – pełna funkcjonalność (restore, publish, zarządzanie źródłami),
  • Visual Studio Package Manager Console – PowerShell w środowisku deweloperskim,
  • Package Manager UI w Visual Studio.

NuGet CLI oferuje szeroki wachlarz opcji:

  • -AllVersions – wyświetlanie wszystkich wersji,
  • -ConfigFile – wskazanie alternatywnego pliku konfiguracyjnego,
  • -Source – wybór źródła pakietu,
  • -Verbosity – poziom szczegółowości logów (normal, quiet, detailed).

Korzystanie z credential providerów, przechowywanie poświadczeń w zmiennych środowiskowych i unikanie jawnie wpisanych haseł w nuget.config należą do najlepszych praktyk bezpieczeństwa.

Integracja NuGet z CI/CD i konteneryzacją

Procesy CI/CD i budowanie obrazów Dockerów wymagają bezpiecznego dostępu do prywatnych źródeł NuGet. Najczęściej stosowane scenariusze to:

  • Wykorzystanie pliku NuGet.Config z sekcjami packageSources oraz packageSourceCredentials (preferowany sposób), z tokenami typu Personal Access Token;
  • Automatyzacja za pomocą Azure Artifact Credential Provider oraz niezbędnych zmiennych środowiskowych (np. NUGET_CREDENTIALPROVIDER_SESSIONTOKENCACHE_ENABLED, VSS_NUGET_EXTERNAL_FEED_ENDPOINTS);
  • Dodanie źródła przez dotnet nuget add source wraz z poświadczeniami bez konieczności modyfikowania pliku nuget.config (lub bezpośrednio w Dockerfile).

W Azure DevOps do obsługi autoryzacji w pipeline służy zadanie NuGetAuthenticate@1 (dla NuGet ≥ 4.8.5385, dotnet ≥ 6, MSBuild ≥ 15.8.166.59604).

Zaawansowana integracja MSBuild – scenariusze restore

Integracja NuGet z MSBuild pozwala na automatyzację pracy z zależnościami. W praktyce MSBuild wspiera:

  • target restore (msbuild -t:restore) – obsługuje przywracanie zarówno z PackageReference, jak i (od v16.5+) z packages.config,
  • generowanie plików project.assets.json oraz *.props i *.targets,
  • zalecane oddzielanie restore i build (msbuild -t:build -restore zamiast łączenia w jedno polecenie).

Przy pracy z API Web i tokenami Bearer należy zainstalować zgodne pakiety NuGet oraz odpowiednio skonfigurować walidację tokenów JWT.

Bezpieczeństwo ekosystemu NuGet

Bezpieczeństwo zarządzania pakietami NuGet jest kluczowe, zwłaszcza dla kodu własnościowego i prywatnych repozytoriów. Rekomendowane jest uwierzytelnianie oparte na tożsamości (identity-based), zarówno w pracy interaktywnej, jak i w automatyzacji procesu (machine-to-machine).

Credential providers powinny spełniać rygorystyczne wymagania dotyczące bezpieczeństwa, nie modyfikować plików nuget.config, obsługiwać proxy i komunikować się przez stdout (odpowiedzi w JSON). W .NET Framework provider może otwierać okno, natomiast w .NET Core użytkownik powinien być instruowany do logowania przez przeglądarkę.

Najlepsze praktyki bezpieczeństwa:

  • Stosowanie zmiennych środowiskowych lub makr w nuget.config zamiast jawnych haseł,
  • przechowywanie poświadczeń w zmiennych środowiskowych, gdy niemożliwe są lepsze zabezpieczenia,
  • jawny zapis poświadczeń w nuget.config wyłącznie w najbardziej awaryjnych sytuacjach.

Diagnostyka i rozwiązywanie problemów z NuGet

Sprawna diagnostyka pracy z NuGet jest istotna dla szybkiego wychwycenia błędów.

  • Błędy w składni pliku nuget.config – nowsze wersje NuGet (od 3.4.3) ignorują pliki z niepoprawnym XML,
  • Problemy z restore – NuGet pobiera pakiet z pierwszego dostępnego źródła, a błędy raportuje tylko z ostatniego,
  • warto systematycznie testować wszystkie źródła i poświadczenia,
  • precyzyjna diagnostyka credential provider wymaga szczegółowej analizy parametrów (Uri, NonInteractive, IsRetry, Verbosity),
  • nie łącz restore i build w jednym poleceniu – stosuj msbuild -t:build -restore,
  • w środowiskach eksperymentalnych wykonaj oba polecenia osobno dla porównania wyników.

Dodatkowo w kontenerach zawsze należy sprawdzić konfigurację credential providera i istotne zmienne środowiskowe:

  • NUGET_CREDENTIALPROVIDER_SESSIONTOKENCACHE_ENABLED,
  • VSS_NUGET_EXTERNAL_FEED_ENDPOINTS – poprawność tokenów i endpointów.

Rekomendacje

Efektywna praca z NuGet w środowisku .NET wymaga znajomości package restore, poprawnej konfiguracji plików nuget.config i zarządzania poświadczeniami. Najwyższy poziom bezpieczeństwa uzyskasz stosując credential provider lub uwierzytelnianie oparte na tożsamości. W integracji z CI/CD i konteneryzacją rekomendujemy zmienne środowiskowe lub zadania dedykowane, jak NuGetAuthenticate@1 w Azure DevOps. Konieczne jest stosowanie najlepszych praktyk związanych z hierarchią nuget.config oraz systematyczna diagnostyka problemów przy restore i budowie projektów.