Megjegyzés
Az oldalhoz való hozzáféréshez engedély szükséges. Megpróbálhat bejelentkezni vagy módosítani a címtárat.
Az oldalhoz való hozzáféréshez engedély szükséges. Megpróbálhatja módosítani a címtárat.
Bizonyos esetekben érdemes lehet saját NuGet-csomagcsatornát implementálni. Számos meglévő implementáció létezik , amelyek lehetővé teszik a saját hírcsatorna különböző módon történő üzemeltetését, de a hivatalos NuGet-ügyfélszoftver és a csomagcsatorna közötti protokoll dokumentálva van, amely lehetővé teszi saját hírcsatorna-implementáció létrehozását az alapoktól.
A protokoll idővel fejlődik, és ez az útmutató azoknak szól, akik szeretnék vagy már implementálták a NuGet-csomagkiszolgálót.
A NuGet V3 protokoll 2015-ös első kiadása óta a NuGet úgy alakult, hogy a fejlesztőknek gazdagabb élményt nyújtson, és ehhez a csomagtárházaknak további munkát kell végezniük a csomagfelhasználók további értékének biztosítása érdekében, a üzemeltetett csomagok metaadatainak pontosításán és a metaadatok különböző formában történő visszaadásán túl. A keresési és csomag metaadat-végpontjai például nem csupán az nupkg nuspec fájljában található metaadatokat tartalmazzák.
Vegye figyelembe, hogy ez az útmutató a NuGet V3 protokollra összpontosít, mivel a V2 protokoll lényegében nincs dokumentálva, és 2015 óta a NuGet-ügyfél- és kiszolgálókommunikáció ajánlott protokollja a V3 protokoll. További információ a protokoll verziószámozásáról.
Kronológia
Annak érdekében, hogy a meglévő NuGet-adattárak szerzői naprakészek maradjanak a NuGet legújabb funkcióival, itt találja a dokumentum hátralévő részében említett releváns funkciók kronológiáját.
| Év | Tulajdonság |
|---|---|
| 2013 |
Egy blogbejegyzés, amely elmagyarázza, hogyan kezelheti a csomagtulajdonosokat a nuget.org egyértelművé tette, hogy a webhelyen látható tulajdonosok azok a fiókok, amelyek rendelkeznek engedéllyel az új verziók feltöltésére, ezért a owners csomag metaadatai figyelmen kívül lesznek hagyva |
| 2017 |
A verified hozzáadva a SearchQueryService válaszokhoz. |
| Szemantikus verziószámozás 2.0.0-támogatás | |
| 2018 | Beágyazott licencek |
| 2019 | Beágyazott ikonok |
A csomag elavulása (a csomag metaadat-erőforrásában RegistrationBaseUrl ) |
|
| 2020 |
Csomag sebezhetőségi információi a RegistrationsBaseUrl csomag metaadat-erőforrásában |
Lekérdezési paraméter hozzáadva packageTypes a SearchQueryService kérésekhez |
|
| 2021 | Beágyazott olvasási eszköz |
| 2023 |
Hitelesített kérések előzetes hitelesítése VulnerabilityInfo erőforrás |
| 2025 | Beágyazott README-letöltések engedélyezése |
Tulajdonos mező
Fontolja meg a csomagjegyzék fájl (.nuspec) két mezőjét: <authors> és <owners>.
A harmadik féltől származó tartalmakat csomagolást végző csomagkészítők gyakran a harmadik fél nevét helyezik el a <authors> mezőben.
A <owners> mező azt jelzi, hogy ki tette közzé a csomagot egy adattárban, ezért kivel kell felvenni a kapcsolatot csomagolási problémák vagy kérdések esetén.
Ezt egy 2013-ban készült blogbejegyzésben ismertette, így a <owners> mező elavultnak minősül a .nuspec fájlban.
Ha a csomag jegyzékfájlja tartalmazza ezeket a metaadatokat, figyelmen kívül kell hagyni.
Ne adja vissza a .nuspec fájl <owners> mezőjének értékét a ownerskeresési erőforrás vagy a csomag metaadat-erőforrás JSON-válaszában.
Ha az adattár csomagonkénti engedélyekkel rendelkezik, javasoljuk, hogy jelentse azokat a fiókokat, amelyek engedélyekkel rendelkeznek az új verziók közzétételére a metaadatokban a owner keresési és csomag metaadat-erőforrások JSON-válaszaihoz.
verified keresési válasz mező
A Visual Studio Package Manager felhasználói felülete kék pipát jelenít meg a keresési szolgáltatás találatai között a csomagok mellett, ha egy új mező verified be van állítva true.
NuGet.org ezt csomagelőtag-adatokkal (kiszolgálóoldali adatokkal, nem a NuGet API-val) használja, így ez az pipa csak akkor jelenik meg az ügyfelek számára, ha a csomag tulajdonosa a csomagot feltöltötte.
Az előtaggal microsoft.* kezdődő csomagokat például csak akkor ellenőrzi a rendszer, ha a csomagot a Microsoft-fiók birtokolja a nuget.org-on. Azok, akik a csomagazonosítóval microsoft. rendelkező csomagot a fenntartott előtagok implementálása előtti eltelt időpontban töltötték fel, nem kapják meg az ellenőrzött pipát.
NuGet.org azt is lehetővé teszi, hogy az előtagok ne legyenek kizárólagosak, így bárki feltölthet egy csomagot az adott előtag alatt, de nem kap hitelesített jelölést.
Szemantikus verziószámozás 2.0.0-támogatás
A NuGet támogatja a hibrid és a szemantikus verziótSystem.Version, de a Szemantikus 2.0.0-s verzió támogatása 2017-ben lett hozzáadva.
Ezért azok a NuGet API-erőforrások, amelyek 3.6.0-nál alacsonyabb verziószámú kliensek számára adnak vissza verziókat, nem adhatnak vissza olyan csomagokat, amelyek a Semantic 2.0.0 olyan funkcióit használják, amelyek nem kompatibilisek a Semantic Verziózás 1.0.0-val.
A két verzió között a legfontosabb különbség a kiadás előtti címkék és a metaadat-sztring.
A Szemantikus verziószámozás 1.0.0 specifikáció megad egy mintapéldát [0-9A-Za-z-] reguláris kifejezésre a kiadás előtti címkékben megengedett karakterekhez, és nem támogatja a metaadat-sztringeket.
A Szemantikus Verziószám 2.0.0 specifikáció lehetővé teszi, hogy a kiadás előtti azonosítókat karakterek válasszák el egymástól (és megtiltja, hogy a numerikus azonosító nullával kezdődjön), valamint lehetővé teszi, hogy építési metaadatokat adjunk hozzá egy + után.
A csomag metaadat-erőforrásában (RegistrationsBaseUrl)azoknak az erőforrásverzióknak, amelyek a 3.6.0 alattiak, csak olyan csomagokat kell visszaadniuk, amelyek megfelelnek a .NET System.Version vagy a Szemantikus verziószámozás 1.0.0 követelményeinek.
Ez azt jelenti, hogy azok a csomagok, amelyek verziószámai csak a Szemantikus Verziószám 2.0.0-s verziójának megfelelnek, láthatatlanok ezen ügyfélverziók számára.
Hasonlóképpen a keresési lekérdezési szolgáltatás (SearchQueryService) és az automatikus kiegészítési szolgáltatás (SearchAutocompleteService) is hozzáadta &semVerLevel={version} a lekérdezési paramétereket.
Ha semVerLevel hiányzik, feltételezze az értéket 1.0.0.
A csomag metaadat-erőforrásához hasonlóan azokat a csomagokat sem lehet visszaadni, amelyek verziója csak a Szemantikus verziószám 2.0.0-s verziójával kompatibilis, ha az semVerLevel érték 2.0.0 alatt van.
Beágyazott fájlok
A csomag ikonok, licence és README fájlok beágyazhatók a csomagba, és ajánlott a beágyazásuk.
Ezeknek a fájloknak szüksége van egy URL-végpontra, amely egy statikus fájlkiszolgálóra van kicsomagolva és elhelyezve, vagy egy olyan URL-címre, amely dinamikusan kinyeri a fájlokat a .nupkg kérelemből, hogy a teljes nupkgfájl letöltése nélkül is megtekinthetők legyenek.
Ha a csomagtártár a csomagok böngészését és a csomagok részleteinek megtekintését tartalmazza, az URL-címek segítségével megjelenítheti az ügyfeleknek a webhely beágyazott tartalmát.
Végül a csomag metaadat-erőforrásának és keresési erőforrásának tartalmaznia kell a JSON-válasz , licenseUrlés/vagy readmeUrl tulajdonságainak iconUrlüzemeltetett URL-címét.
A csomagokat (.nupkg fájlokat) nem szabad módosítani, mivel az ügyfélfunkciók (a zárolási fájlok és az aláírt csomagok) észlelik a módosításokat, mivel a csomagot módosították.
Vegye figyelembe, hogy a licenc lehet SPDX-kifejezés vagy beágyazott fájl (de mindkettő nem). Azok a csomagok, amelyek licenckifejezést használnak, a keresési és csomag metaadatok eredményeiben licenckifejezésként jelenhetnek meg. Ezek URL-címmel kódolva, és az https://licenses.nuget.org/ végére fűzve lehetnek elhelyezve. Például: https://licenses.nuget.org/Apache-2.0. A NuGet.org kiszolgáló csapata további dokumentációval rendelkezik a licenses.nuget.org kapcsolatban.
Ismert biztonságirés- és elavulással kapcsolatos adatok
Csomag metaadat-erőforrása (RegistrationsBaseUrl)
A csomag metaadat erőforrás tartalmazhat elavulási és sebezhetőségi információkat. Ez lehetővé teszi, hogy a Visual Studio Csomagkezelő felhasználói felületén vagy más azonosítókban ezzel egyenértékű csomagokat böngésző ügyfelek értesüljenek a fontos biztonsági vagy karbantartási problémákról.
Ha a csomagtárház csomagokat vesz át egy másik adattárból a saját adatfolyamának tükrözése érdekében, javasoljuk, hogy rendszeresen ellenőrizze az eredeti forrást, van-e elavult vagy sebezhetőségi adat, és tükrözze ezeket a metaadatokat a saját adattárában.
Ha a csomagtárház kifejezetten a nuget.org-ról kap forrásokat, akkor a legutóbbi ellenőrzés (ún. "kurzor") állapotának megőrzésével az erőforrás Catalog segítségével hatékonyan ellenőrizheti, hogy vannak-e frissítések a tükrözött csomagokhoz anélkül, hogy nagyszámú csomag metaadat-JSON-fájlt kellene letöltenie a felső rétegbeli hírcsatornából.
A katalóguserőforrás mintakóddal való használatával kapcsolatos útmutató segít az első lépésekben.
Ismert biztonsági rések adatbázisa (VulnerabilityInfo)
Annak érdekében, hogy a csomagok visszaállítása során nagy teljesítményű biztonsági réseket lehessen ellenőrizni, a NuGet letölti az VulnerabilityInfo erőforrás ismert biztonsági réseinek teljes listáját.
Nuget.org biztonsági résadatokat biztosít a GitHub Advisories-adatbázis összes, a GitHub által áttekintett tanácsadójának, amely olyan csomagokat is tartalmaz, amelyek nem nuget.org vannak üzemeltetve.
Ha a csomagtárház saját fejlesztésű csomagokat tárol, és a saját hírcsatornát használó ügyfeleknek szeretne sebezhetőségi információkat nyújtani, de még nincs felfedett csomag sebezhetőség, egy sebezhetőségi indexet kell megadnia, amelynek tartalma egy vagy több sebezhetőségi oldal, amelyek egy üres JSON-tömböt ([]) tartalmaznak.
Ha a csomagtárházat az alkalmazások alapértelmezett adattárként kívánják használni (a nuget.org helyett), használhatja a nuget.org sebezhetőségi adatait.
Az egyik lehetőség, hogy a szolgáltatás indexében a nuget.org sérülékenységi index URL-címét használjuk.
Egy másik lehetőség, hogy rendszeresen ellenőrizze a nuget.org indexét VulnerabilityInfo , és töltse le a módosított oldalakat a helyi tükrözés érdekében.
packageTypes keresési lekérdezés
A .NET CLI lehetővé teszi a .NET-eszközcsomagok keresését a dotnet tool search paranccsal.
Ezt úgy valósítja meg, hogy hozzáad egy lekérdezési paramétert &packageTypes={value} a keresési lekérdezési erőforráshoz, amely beolvassa a csomag fájlmezőjének .nuspec<packageTypes> értékeit.
Hitelesített hírcsatornák URL-struktúrája
A NuGet API áttekintésében leírtak szerint az összes NuGet-kiszolgáló kommunikációjának kezdő URL-címe a szolgáltatásindex.
Ez a dokumentum tartalmazza a NuGet-ügyfelek által lekérdezni kívánt összes többi erőforrás URL-címét.
NuGet 6.7 (Visual Studio & MSBuild 17.7, valamint .NET SDK 7.0.400) verziótól kezdve a NuGet a
Íme néhány példa:
| URL-cím | Elő fog hitelesíteni? |
|---|---|
| https://pkgs.contoso.com/nuget/v3/feed/index.json | N/A, ez a szolgáltatásindex. |
| https://pkgs.contoso.com/nuget/v3/search | Nem, nem ugyanabban vagy egy alkönyvtárban legyen, mint a szolgáltatási index. |
| https://search.pkgs.contoso.com/nuget/v3/feed/ | Nem, nem ugyanazon a gazdagépnéven, mint a szolgáltatásindex. |
| https://pkgs.contoso.com/nuget/v3/feed/search | Igen, ugyanabban a könyvtárban, mint a szolgáltatásindex. |
| https://pkgs.contoso.com/nuget/v3/registration/ | Nem, nem a szolgáltatási index alkönyvtárában. |
| https://pkgs.contoso.com/nuget/v3/feed/registration/ | Igen, a szolgáltatásindex alkönyvtárában. |
| https://pkgs.contoso.com/nuget/v3/{guid}/registration/ | Lásd alább. |
Az utolsó példában a kiszolgálónak lehet egy canonical (ebben a példában guid) neve, és egy vagy több aliasa is lehet.
Ha a szolgáltatásindex-kérés hitelesítése nem a kanonikus URL-címen történt (példánkban a "barátságos" név, feed), akkor igen, a kanonikus URL-cím alatt található erőforrásokra irányuló kérések nem fognak megfelelni HttpClientHandler szabályainak PreAuthenticate.
Ha azonban a nem kanonikus URL egy HTTP-átirányítás a kanonikus URL-címre, https://pkgs.contoso.com/nuget/v3/{guid}/index.json, akkor ezt az URL-címet fogja használni a rendszer a HttpClientHandler hitelesítőadat-gyorsítótárában.
Ebben az esetben a szolgáltatásindexre irányuló minden kérés további késéssel fog rendelkezni az átirányítás miatt.
Bár a NuGet V3 API-ja statikus fájlkiszolgálón való munkavégzésre lett tervezve, a keresési erőforrás kivétel, amely mindig dinamikus webszolgáltatást igényel a kérések feldolgozásához.
Ha más kiszolgálókon szeretné üzemeltetni a keresési vagy bármely más NuGet API-erőforrást, és ki akarja használni a HttpClientHandler által kínált PreAuthenticate előnyöket, fordított proxyt kell használnia annak érdekében, hogy a szolgáltatásindexben található összes ügyfélelőtti URL-cím megfeleljen az "azonos vagy alkönyvtár" szabálynak.
Beágyazott README-letöltések engedélyezése
A rendszer egy új erőforrást dokumentált egy URL-cím létrehozásához, amely egy adott csomag README-jének letöltéséhez használható. Ez lehetővé teszi, hogy az ügyfél, például a VS Csomagkezelési felhasználói felülete, megjelenítse a beágyazott README-et azokhoz a csomagokhoz, amelyeket korábban nem telepített a felhasználó. Az ügyfél létrehozza ezt az URL-címet, és megkísérli letölteni a README-t a kérésre adott válasz alapján annak megállapításához, hogy elérhető-e README. Ez azt jelenti, hogy a kiszolgálóknak több kérésre kell számítaniuk a létrehozott végponthoz, miközben a felhasználók a PM felhasználói felületén navigálnak.