Průvodce implementací serveru NuGet
V některých případech můžete chtít implementovat vlastní informační kanál balíčků NuGet. Existuje mnoho existujících implementací , které umožňují hostovat vlastní informační kanál různými způsoby, ale protokol mezi oficiálním klientským softwarem NuGet a informačním kanálem balíčků je zdokumentovaný, takže můžete vytvořit vlastní implementaci informačního kanálu úplně od začátku.
Protokol se v průběhu času vyvíjí a tato příručka je zaměřená na ty, které chtějí nebo již implementovaly server balíčků NuGet.
Od počátečního vydání protokolu NuGet V3 v roce 2015 se NuGet vyvinul tak, aby vývojářům poskytoval bohatší prostředí. To vyžaduje, aby úložiště balíčků dělala další práci, aby poskytla další hodnotu uživatelům balíčků, kromě pouhého přesného metadata z hostovaných balíčků a vrácení metadat v různých formách. Například koncové body metadat vyhledávání a balíčku obsahují více než jen metadata nalezená v souboru nupkg nuspec.
Všimněte si, že tato příručka se zaměřuje na protokol NuGet V3, protože protokol V2 je v podstatě nezdokumentovaný a od roku 2015 se doporučený protokol pro komunikaci klienta NuGet a serveru označuje jako protokol V3. Další informace o správě verzí protokolu.
Abychom autorům existujících úložišť NuGet pomohli udržovat aktuální informace o nejnovějších funkcích NuGetu, tady je chronologie relevantních funkcí uvedených ve zbývající části dokumentu.
Year (Rok) | Funkce |
---|---|
2013 | Blogový příspěvek vysvětlující, jak spravovat vlastníky balíčků na nuget.org objasnil, že vlastníci, kteří se zobrazují na webu, jsou účty, které mají oprávnění k nahrávání nových verzí, a proto owners jsou metadata v balíčku ignorována. |
2017 | Přidáno verified do SearchQueryService odpovědí. |
Podpora sémantické verze 2.0.0 | |
2018 | Vložené licence |
2019 | Vložené ikony |
Vyřazení balíčku ( RegistrationBaseUrl prostředek metadat balíčku) |
|
2020 | Informace o ohrožení zabezpečení balíčku v RegistrationsBaseUrl (prostředek metadat balíčku) |
Přidání packageTypes parametru dotazu do SearchQueryService požadavků |
|
2021 | Vložený readme |
2023 | Předběžné ověření ověřených požadavků VulnerabilityInfo Zdrojů |
Zvažte dvě pole souboru manifestu balíčku (.nuspec
) a <owners>
. <authors>
Autoři balíčků, kteří zabalí obsah třetích stran, často do pole zadají název <authors>
třetí strany.
Pole <owners>
bylo určeno k označení, kdo balíček publikoval v úložišti, a proto by se měl obrátit v případě problémů s balením nebo otázek.
To bylo vysvětleno v blogovém příspěvku z roku 2013, takže <owners>
pole je v souboru považováno za zastaralé .nuspec
.
Pokud manifest balíčku obsahuje tato metadata, měl by se ignorovat.
Nevracejte hodnotu .nuspec
pole souboru <owners>
ve vlastnosti v owners
odpovědi JSON prostředku vyhledávání nebo prostředku metadat balíčku.
Pokud má vaše úložiště oprávnění pro jednotlivé balíčky, doporučujeme nahlásit účty, které mají oprávnění k publikování nových verzí v owner
metadatech pro odpovědi JSON pro vyhledávání a prostředky metadat balíčku.
Uživatelské rozhraní sady Visual Studio Správce balíčků zobrazuje modré zaškrtnutí vedle balíčků ve výsledcích vyhledávací služby, když je nové pole verified
nastavené na true
.
NuGet.org to používá s daty předpony balíčku (data na straně serveru, ne součást rozhraní NuGet API), aby se toto zaškrtnutí zobrazilo jenom zákazníkům, když účet, který vlastní balíček, nahrál balíček.
Například každý balíček s předponou microsoft.*
je ověřený pouze v případě, že balíček vlastní účet Microsoft na nuget.org. Každý, kdo nahrál balíček s ID balíčku počínaje microsoft.
před implementací rezervovaných předpon, nebude mít tuto ověřenou značku zaškrtnutí.
NuGet.org také umožňuje, aby předpony nebyly exkluzivní, takže kdokoli může nahrát balíček pod Contoso.ToolWithPlugins.Community.*
, ale nebude mít ověřenou značku zaškrtnutí.
NuGet podporuje hybridní verzi mezi System.Version
verzí a sémantickou verzí, ale v roce 2017 byla přidána podpora sémantické verze 2.0.0.
Proto prostředky rozhraní NuGet API, které vrací verze do klientských verzí nižší než 3.6.0, nesmí vracet balíčky, které používají sémantické funkce 2.0.0, které nejsou kompatibilní s sémantickou verzí 1.0.0.
Nejdůležitější rozdíly mezi těmito dvěma verzemi jsou popisky předběžné verze a řetězec metadat.
Specifikace sémantické verze 1.0.0 poskytuje [0-9A-Za-z-]
jako ukázkový řetězec regulárního výrazu pro jediné znaky povolené jako součást popisku předběžné verze a nepodporuje řetězce metadat.
Specifikace sémantické verze 2.0.0 umožňuje oddělit .
identifikátory předběžné verze znaky (a zakáže číselný identifikátor, aby měl úvodní nulu) a navíc umožňuje přidat metadata sestavení za znakem +
.
V prostředku metadat balíčku (RegistrationsBaseUrl
)musí verze prostředků nižší než 3.6.0 vrátit pouze balíčky, které vyhovují . System.Version
Rozhraní NET nebo sémantická správa verzí 1.0.0
To znamená, že balíčky, jejichž verze jsou kompatibilní pouze se sémantickou verzí 2.0.0, jsou pro tyto verze klienta neviditelné.
Podobně vyhledávací služba (SearchQueryService
) a služba automatického dokončování (SearchAutocompleteService
) přidala &semVerLevel={version}
parametry dotazu.
Pokud semVerLevel
chybí, předpokládejme hodnotu 1.0.0
.
Podobně jako prostředek metadat balíčku nesmí být balíčky, jejichž verze je kompatibilní pouze se sémantickou verzí 2.0.0, pokud semVerLevel
je hodnota nižší než 2.0.0.
Ikony balíčků, licence a soubory readme můžou být (a doporučuje se) vkládat do balíčku.
Tyto soubory potřebují koncový bod adresy URL, buď extrahovaný a vložený na statický souborový server, nebo adresu URL, která dynamicky extrahuje soubory z .nupkg
požadavku, aby je bylo možné zobrazit bez stažení celého nupkg
souboru .
Pokud vaše úložiště balíčků poskytuje procházení a zobrazování podrobností o balíčku, můžete pomocí adres URL zobrazit zákazníkům vložený obsah na vašem webu.
Nakonec prostředek metadat balíčku a prostředek vyhledávání musí obsahovat hostované adresy URL v licenseUrl
iconUrl
odpovědi JSON a/nebo readmeUrl
vlastnosti.
Balíčky (.nupkg
soubory) nesmí být změněny, protože funkce klienta (zamykací soubory a podepsané balíčky) rozpozná úpravy, protože se s balíčkem manipulovalo.
Všimněte si, že licence může být výraz SPDX nebo vložený soubor (ale ne obojí).
Balíčky, které používají licenční výraz, pokud jsou reprezentovány ve výsledcích vyhledávání a metadat balíčku, mohou mít nastavenou licenseUrl
licenci výraz, adresu URL kódovanou a připojenou na konec https://licenses.nuget.org/.
Například https://licenses.nuget.org/Apache-2.0.
Tým NuGet.org serveru má další dokumentaci k licenses.nuget.org.
Prostředek metadat balíčku může obsahovat informace o vyřazení a ohrožení zabezpečení. To umožňuje zákazníkům procházet balíčky v uživatelském rozhraní sady Visual Studio Správce balíčků nebo ekvivalentních v jiných prostředích IDEs, aby dostávali oznámení o důležitých problémech se zabezpečením nebo údržbou.
Pokud je úložiště balíčků "up-sourcing" balíčky z jiného úložiště, aby bylo možné zrcadlit balíčky ve vašem vlastním informačním kanálu, doporučujeme pravidelně kontrolovat původní zdroj, pokud dojde k vyřazení nebo ohrožení zabezpečení dat, a zrcadlit tato metadata ve vašem vlastním úložišti.
Pokud je vaše úložiště balíčků v provozu z nuget.org konkrétně tím, že si ponecháte stav posledního zaškrtnutí ("kurzor"), můžete pomocí Catalog
prostředku efektivně zkontrolovat, jestli nedošlo k nějakým aktualizacím balíčků, které zrcadlíte, aniž byste museli stahovat velký počet souborů JSON metadat balíčku z nadřazeného informačního kanálu.
K dispozici je průvodce používáním prostředku katalogu s ukázkovým kódem, který vám pomůže začít.
Aby bylo možné během obnovení balíčku zajistit kontrolu ohrožení zabezpečení s vysokým výkonem, NuGet stáhne úplný seznam známých ohrožení zabezpečení z VulnerabilityInfo
prostředku.
Nuget.org poskytuje data o ohrožení zabezpečení všech kontrolovaných doporučení GitHubu z databáze Advisories GitHubu, která zahrnuje balíčky, které nejsou hostované v nuget.org.
Pokud vaše úložiště balíčků hostuje balíčky první strany a chcete zákazníkům s vlastním informačním kanálem poskytnout informace o ohrožení zabezpečení, ale ještě nemáte žádné ohrožení zabezpečení balíčku, měli byste poskytnout index ohrožení zabezpečení s jednou nebo více stránkami ohrožení zabezpečení, jejichž obsah je prázdné pole JSON ([]
).
Pokud má být úložiště balíčků používáno aplikacemi jako výchozím úložištěm (místo nuget.org), můžete použít data ohrožení zabezpečení nuget.org.
Jednou z možností je použít v indexu služby adresu URL indexu ohrožení zabezpečení nuget.org.
Další možností je pravidelně kontrolovat index nuget.org VulnerabilityInfo
a stahovat všechny změněné stránky, aby se zrcadlily místně.
Rozhraní příkazového dotnet tool search
řádku .NET umožňuje vyhledat balíčky nástrojů .NET pomocí příkazu.
To se implementuje přidáním parametru &packageTypes={value}
dotazu do prostředku vyhledávacího dotazu, který čte hodnoty z pole souboru balíčku .nuspec
<packageTypes>
.
Jak je popsáno v přehledu rozhraní NuGet API, počáteční adresa URL pro veškerou komunikaci serveru NuGet je index služby.
Tento dokument obsahuje adresy URL pro všechny ostatní prostředky, na které budou klienti NuGet dotazovat.
Od NuGetu 6.7 (Visual Studio & MSBuild 17.7 a .NET SDK 7.0.400) používá NuGet . HttpClientHandler.PreAuthenticate
NET , který zabraňuje pouze anonymním požadavkům HTTP, pokud jsou následné adresy URL ve stejném virtuálním adresáři nebo podadresáři adresy URL, která byla dříve ověřena.
Tím se výrazně sníží počet neověřených požadavků HTTP odeslaných na server, a tím se sníží zatížení serveru.
Několik příkladů:
Adresa URL | Bude předběžné ověření? |
---|---|
https://pkgs.contoso.com/nuget/v3/feed/index.json | Není k dispozici, jedná se o index služby. |
https://pkgs.contoso.com/nuget/v3/search | Ne, ne ve stejném nebo podadresáři jako index služby. |
https://search.pkgs.contoso.com/nuget/v3/feed/ | Ne, ne na stejném názvu hostitele jako index služby. |
https://pkgs.contoso.com/nuget/v3/feed/search | Ano, ve stejném adresáři jako index služby. |
https://pkgs.contoso.com/nuget/v3/registration/ | Ne, ne v podadresáři indexu služby. |
https://pkgs.contoso.com/nuget/v3/feed/registration/ | Ano, v podadresáři indexu služby. |
https://pkgs.contoso.com/nuget/v3/{guid}/registration/ | Viz níže. |
V posledním příkladu může mít server kanonický název (v tomto příkladu guid) a má jeden nebo více aliasů.
Pokud se požadavek indexu služby ověřil na jiné než kanonické adrese URL (v našem příkladu feed
popisný název), nebudou žádné požadavky na prostředky pod kanonickou adresou URL odpovídat HttpClientHandler
pravidlům PreAuthenticate
.
Pokud je ale nekananonická adresa URL přesměrováním HTTP na kanonické adrese URL, https://pkgs.contoso.com/nuget/v3/{guid}/index.jsonpoužije se tato adresa URL v HttpClientHandler
mezipaměti přihlašovacích údajů.
V takovém případě každý požadavek na index služby bude mít kvůli přesměrování další latenci.
Zatímco rozhraní API NuGet v3 bylo navržené tak, aby fungovalo na statickém souborovém serveru, vyhledávací prostředek je výjimkou, která k zpracování požadavků vždy vyžaduje dynamickou webovou službu.
Pokud chcete hostovat vyhledávání nebo jakýkoli jiný prostředek rozhraní NuGet API, na různých serverech, abyste mohli využít výhod HttpClientHandler
PreAuthenticate
, budete muset použít reverzní proxy server, abyste zajistili, že všechny adresy URL, které mají na straně zákazníka v indexu služby, splňují pravidlo "stejného nebo podadresáře".