Poznámka:
Přístup k této stránce vyžaduje autorizaci. Můžete se zkusit přihlásit nebo změnit adresáře.
Přístup k této stránce vyžaduje autorizaci. Můžete zkusit změnit adresáře.
V některých případech můžete chtít vytvořit svůj vlastní zdroj 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. Pro více informací si přečtěte o verzování protokolu.
Chronology
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 | Feature |
|---|---|
| 2013 |
Blogový příspěvek vysvětlující, jak spravovat vlastníky balíčků na nuget.org objasnil, že vlastníci zobrazené na webu jsou účty, které mají oprávnění k nahrá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 |
Zastarání balíčku (RegistrationBaseUrl zdroj metadat balíčku) |
|
| 2020 |
Informace o zranitelnosti balíčku v RegistrationsBaseUrl (prostředek metadat balíčku) |
Přidání packageTypes parametru dotazu do SearchQueryService požadavků |
|
| 2021 | Vložený soubor readme |
| 2023 |
Předběžné ověření ověřených požadavků VulnerabilityInfo zdroj |
| 2025 | Povolit vložené soubory README ke stažení |
Vlastník pole
Zvažte dvě pole souboru manifestu balíčku (.nuspec) a <authors>. <owners>
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 pole .nuspec ze souboru <owners> ve vlastnosti owners v 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.
verified Vyhledávací pole odpovědi
Uživatelské rozhraní Správce balíčků sady Visual Studio zobrazuje modré zaškrtnutí vedle balíčků ve výsledcích vyhledávací služby , když je nové pole verified nastaveno 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í.
Podpora sémantické verze 2.0.0
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 Semantic Versioning 2.0.0 umožňuje, aby identifikátory předběžné verze byly odděleny znaky . (a zakazuje číselnému identifikátoru mít úvodní nulu), a navíc umožňuje přidat metadata sestavení za +.
Ve zdroji metadat balíčku (RegistrationsBaseUrl) musí verze zdrojů nižší než 3.6.0 vrátit pouze balíčky, které vyhovují .NETu nebo Sémantickému verzování 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 u prostředku metadat balíčku nesmí být balíčky, jejichž verze je kompatibilní pouze se sémantickým verzováním 2.0.0, vráceny, pokud je hodnota semVerLevel nižší než 2.0.0.
Vložené soubory
Ikony balíčků, licence a soubory readme můžou být (a doporučuje se) vkládat do balíčku.
Tyto soubory potřebují URL endpoint, buď extrahovaný a vložený na statický souborový server, nebo URL, která dynamicky extrahuje soubory z .nupkg na vyžádání, aby bylo možné je zobrazit bez stažení celého souboru nupkg.
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 musí prostředek metadat balíčku a prostředek vyhledávání obsahovat hostovanou adresu URL v iconUrl, licenseUrl a/nebo readmeUrl vlastnostech odpovědi JSON.
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, mohou mít ve výsledcích vyhledávání a metadat balíčku nastaven licenseUrl na licenční výraz, URL zakódovaný, a připojený 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.
Známé zranitelnosti a znehodnocení dat
Prostředek metadat balíčku (RegistrationsBaseUrl)
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í Správce balíčků sady Visual Studio 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 vaše úložiště balíčků přejímá balíčky z jiného úložiště za účelem jejich zrcadlení ve vašem vlastním kanálu, doporučujeme pravidelně kontrolovat původní zdroj, zda nedošlo k zastarání nebo zjištění zranitelností, a tato metadata následně zrcadlit ve vašem vlastním úložišti.
Pokud vaše úložiště balíčků přebírá balíčky z nuget.org, můžete sledováním stavu poslední kontroly (tzv. „kurzor“) efektivně pomocí Catalog zdroje zjistit, zda existují nějaké aktualizace balíčků, které zrcadlíte, aniž byste museli stahovat velké množství souborů JSON s metadaty balíčků z nadřazené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.
Známá databáze zranitelností (VulnerabilityInfo)
Aby bylo možné během obnovení balíčku zajistit výkonné skenování zranitelností, NuGet stáhne úplný seznam známých zranitelností z VulnerabilityInfo prostředku.
Nuget.org poskytuje údaje o zranitelnostech všech doporučení revidovaných GitHubem z databáze upozornění GitHubu, která zahrnuje balíčky, které nejsou hostovány na nuget.org.
Pokud vaše úložiště balíčků hostuje interní balíčky a chcete zákazníkům prostřednictvím vlastního kanálu poskytnout informace o zranitelnostech, ale ještě nemáte žádné zveřejněné zranitelnosti balíčků, měli byste poskytnout index zranitelností s jednou nebo více stránkami zranitelností, jejichž obsah je prázdné pole JSON ([]).
Znovuvyužití dat o zranitelnostech z nuget.org
NuGet nevyžaduje, aby prostředky v indexu služby nebo index ohrožení zabezpečení byly na stejném serveru jako samotný index služby. Existuje však několik důvodů, proč se některé společnosti rozhodnou blokovat nuget.org v bráně firewall, nebo mají lokální úložiště v odpojené síti. Pokud se chcete vyhnout problémům s připojením, doporučujeme poskytovat data o zranitelnostech z vaší vlastní webové aplikace, aby klienti NuGet navazovali pouze HTTP připojení k hostiteli, na kterém je informační kanál nainstalován.
✔️ Ukládejte do mezipaměti nebo proxy stránky zranitelností ve vaší vlastní webové aplikaci
❌ NEinzerujte api.nuget.org v indexu služby nebo indexu ohrožení zabezpečení bez konfigurace, aby se tato možnost vypnula.
packageTypes vyhledávací dotaz
Rozhraní .NET příkazového řádku umožňuje pomocí příkazu vyhledat balíčky nástrojů .NET.
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> .
Struktura adres URL pro ověřené informační kanály
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 .NETHttpClientHandler.PreAuthenticate, který brání anonymním požadavkům HTTP pouze tehdy, pokud jsou následné adresy URL ve stejném virtuálním adresáři nebo podadresáři adresy URL, která byla již 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.
Tady je několik příkladů:
| 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 jménu 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 byl požadavek indexu služby ověřen na nekanonické adrese URL (v našem příkladu feed - "přátelský" název), pak ne, žádné požadavky na prostředky pod kanonickou adresou URL nebudou odpovídat pravidlům HttpClientHandler pro PreAuthenticate.
Pokud je ale nekanonická adresa URL přesměrováním HTTP na kanonickou adresu URL, pak se tato adresa URL použije ve mezipaměti přihlašovacích údajů https://pkgs.contoso.com/nuget/v3/{guid}/index.json.
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 HttpClientHandlerPreAuthenticate, budete muset použít reverzní proxy server, abyste zajistili, že všechny adresy URL zaměřené na zákazníka v indexu služby odpovídaly pravidlu "stejného adresáře nebo podadresáře".
Povolit vložené soubory README ke stažení
Nový prostředek byl zdokumentován pro vytvoření adresy URL, která se dá použít ke stažení souboru README pro daný balíček. To umožní klientovi, jako je uživatelské rozhraní pro správu balíčků ve VS, zobrazit vložený soubor README pro balíčky, které uživatel předtím nenainstaloval. Klient vytvoří tuto adresu URL a pokusí se stáhnout soubor README pomocí odpovědi na požadavek, který určí, jestli je soubor README k dispozici. To znamená, že servery by měly při navigaci v uživatelském rozhraní PM očekávat více požadavků na vytvořený koncový bod.