.nuspec-referencia

A .nuspec fájl egy csomag metaadatait tartalmazó XML-jegyzék. Ez a jegyzék mind a csomag összeállítására, mind a fogyasztók tájékoztatására szolgál. A jegyzék mindig szerepel a csomagban.

Ebben a témakörben:

• Általános forma és séma
• Csere jogkivonatok (Ha Visual Studio-projekttel használják)
• Függőségek
• Explicit szerelvényhivatkozások
• Keretrendszer-szerelvény referenciái
• Szerelvényfájlokat is beleértve
• Tartalomfájlok felvétele
• Példa nuspec-fájlokra

Projekttípus kompatibilitása

• nuget.exe pack Nem .nuspec SDK-stílusú projektekhez használhatópackages.config.

• Az .nuspecSDK-stílusú projektekhez (általában az SDK attribútumot használó .NET Core- és .NET Standard-projektekhez) nem szükséges fájl létrehozása. (Vegye figyelembe, hogy a csomag létrehozásakor létrejön egy .nuspec .)

  Ha egy csomagot a vagy msbuild pack targeta használatával dotnet.exe pack hoz létre, javasoljuk, hogy a projektfájlban .nuspec általában szereplő összes tulajdonságot vegye fel a fájlba. Ehelyett azonban választhat, hogy egy .nuspec fájlt használ-e a csomagba dotnet.exe , vagy msbuild pack target.

• A PackageReference-be.nuspec migrált packages.config projektek esetében a csomag létrehozásához nincs szükség fájlra. Ehelyett használja az msbuild -t:pack parancsot.

Általános forma és séma

Sémafájl nuspec.xsd a NuGet GitHub-adattárban található. Vegye figyelembe, hogy ez a fájl csak egy fájl legutóbbi sémáját .nuspec jelöli. Hivatalosan közzétett verziók nem léteznek, és a fájl egyik verziója sem felel meg egy adott NuGet-verziónak.

Ebben a sémában egy .nuspec fájl az alábbi általános űrlapot tartalmazza:

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <!-- Required elements-->
        <id></id>
        <version></version>
        <description></description>
        <authors></authors>

        <!-- Optional elements -->
        <!-- ... -->
    </metadata>
    <!-- Optional 'files' node -->
</package>

A séma egyértelmű vizuális megjelenítéséhez nyissa meg a sémafájlt Tervező módban a Visual Studióban, és kattintson az XML Sémakezelő hivatkozásra. Másik lehetőségként nyissa meg a fájlt kódként, kattintson a jobb gombbal a szerkesztőben, és válassza az XML-sémakezelő megjelenítése lehetőséget. Akárhogy is kap egy nézetet, mint az alábbi (ha többnyire kibontott):

A .nuspec fájl összes XML-elemneve megkülönbözteti a kis- és nagybetűket, ahogyan általában az XML esetében is. A metaadat-elem <description> használata például helyes, és <Description> nem helyes. Az egyes elemnevek megfelelő burkolatát az alábbiakban dokumentáljuk.

Fontos

Bár a .nuspec fájl egy sémára ()xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd" mutató hivatkozást tartalmaz, a NuGet-Team soha nem tett közzé olyan sémafájlt, amely használható az automatikus sémaérvényesítéshez.

Kötelező metaadat-elemek

Bár a csomagok minimális követelményei a következő elemek, érdemes megfontolni az opcionális metaadat-elemek hozzáadását, hogy a fejlesztők a csomaggal kapcsolatos általános felhasználói élményt javítsák.

Ezeknek az elemeknek egy elemen <metadata> belül kell megjelenniük.

azonosító

A kis- és nagybetűket nem megkülönböztető csomagazonosító, amelynek egyedinek kell lennie nuget.org vagy bármely gyűjteményben, amelyben a csomag található. Az azonosítók nem tartalmazhatnak URL-címhez érvénytelen szóközöket vagy karaktereket, és általában a .NET-névtérszabályokat követik. Útmutatásért lásd : Egyedi csomagazonosító kiválasztása .

Ha egy csomagot nuget.org tölt fel, a id mező legfeljebb 128 karakter hosszúságú lehet.

verzió

A csomag verziója a major.minor.patch mintát követve. A verziószámok tartalmazhatnak egy kiadás előtti utótagot a Csomag verziószámozásában leírtak szerint.

Ha egy csomagot nuget.org tölt fel, a version mező legfeljebb 64 karakter hosszúságú lehet.

leírás

A csomag leírása a felhasználói felület megjelenítéséhez.

Ha egy csomagot nuget.org tölt fel, a description mező legfeljebb 4000 karakter hosszúságú lehet.

authors

A csomagkészítők vesszővel tagolt listája. owners A authors rendszer figyelmen kívül hagyja a nuspec és az abból származó elemeket, amikor feltölti a csomagot a nuget.org. A csomag tulajdonjogának beállításáról a nuget.org a csomagtulajdonosok kezelése nuget.org című témakörben olvashat.

Választható metaadat-elemek

Tulajdonosok

Fontos

a tulajdonosok elavultak. Használjon inkább szerzőt.

A csomagtulajdonosok vesszővel tagolt listája. A owners nuspec forrását a rendszer figyelmen kívül hagyja, amikor feltölti a csomagot a nuget.org. A csomag tulajdonjogának beállításáról a nuget.org a csomagtulajdonosok kezelése nuget.org című témakörben olvashat.

projectUrl

A csomag kezdőlapjának URL-címe, amely gyakran megjelenik a felhasználói felületen, valamint nuget.org.

Ha egy csomagot nuget.org tölt fel, a projectUrl mező legfeljebb 4000 karakter hosszúságú lehet.

licenseUrl

Fontos

A licenseUrl elavult. Használjon inkább licencet.

A csomag licencének URL-címe, amely gyakran jelenik meg a felhasználói felületeken, például nuget.org.

Ha egy csomagot nuget.org tölt fel, a licenseUrl mező legfeljebb 4000 karakter hosszúságú lehet.

licenc

A NuGet 4.9.0-s és újabb verziója támogatott

SPDX-licenckifejezés vagy a csomagban lévő licencfájl elérési útja, amely gyakran jelenik meg a felhasználói felületeken, például a nuget.org. Ha a csomagot egy közös licenc ( például MIT vagy BSD-2-Clause) keretében licenceli, használja a társított SPDX-licencazonosítót. Például:

<license type="expression">MIT</license>

Megjegyzés:

NuGet.org csak a Nyílt forráskódú kezdeményezés vagy a Szabad szoftver alapítvány által jóváhagyott licenckifejezéseket fogadja el.

Ha a csomag több gyakori licenccel rendelkezik, összetett licencet adhat meg az SPDX-kifejezés szintaxisának 2.0-s verziójával. Például:

<license type="expression">BSD-2-Clause OR MIT</license>

Ha olyan egyéni licencet használ, amelyet a licenckifejezések nem támogatnak, csomagolhat egy .txt vagy .md több fájlt a licenc szövegével. Például:

<package>
  <metadata>
    ...
    <license type="file">LICENSE.txt</license>
    ...
  </metadata>
  <files>
    ...
    <file src="licenses\LICENSE.txt" target="" />
    ...
  </files>
</package>

Az MSBuild-ekvivalens esetében tekintse meg a licenckifejezések vagy licencfájlok csomagolását.

A NuGet licenckifejezéseinek pontos szintaxisát az alábbiakban ismertetjük az ABNF-ben.

license-id            = <short form license identifier from https://spdx.org/spdx-specification-21-web-version#h.luq9dgcle9mo>

license-exception-id  = <short form license exception identifier from https://spdx.org/spdx-specification-21-web-version#h.ruv3yl8g6czd>

simple-expression = license-id / license-id”+”

compound-expression =  1*1(simple-expression /
                simple-expression "WITH" license-exception-id /
                compound-expression "AND" compound-expression /
                compound-expression "OR" compound-expression ) /                
                "(" compound-expression ")" )

license-expression =  1*1(simple-expression / compound-expression / UNLICENSED)

iconUrl

Fontos

iconUrl elavult. Használja inkább az ikont.

Egy 128x128-as kép URL-címe áttetsző háttérrel, amely a csomag ikonjaként használható a felhasználói felületen. Ügyeljen arra, hogy ez az elem ne a képet tartalmazó weblap URL-címét, hanem a közvetlen kép URL-címét tartalmazza. Ha például egy GitHub-rendszerképet szeretne használni, használja a nyers fájl URL-címét, például https://github.com/<felhasználónév>/<adattár>/nyers/<ág>/<logo.png>.

Ha egy csomagot nuget.org tölt fel, a iconUrl mező legfeljebb 4000 karakter hosszúságú lehet.

icon

A NuGet 5.3.0-s és újabb verziója támogatott

Ez egy csomagon belüli képfájl elérési útja, amely gyakran jelenik meg a felhasználói felületeken, például nuget.org a csomag ikonjaként. A képfájl mérete legfeljebb 1 MB lehet. A támogatott fájlformátumok közé tartozik a JPEG és a PNG. 128x128 képfelbontást javasoljuk.

Például a következőt adhatja hozzá a nuspechez, amikor csomagot hoz létre nuget.exe:

<package>
  <metadata>
    ...
    <icon>images\icon.png</icon>
    ...
  </metadata>
  <files>
    ...
    <file src="..\icon.png" target="images\" />
    ...
  </files>
</package>

Csomag ikon nuspec minta.

Az MSBuild-ekvivalens esetében tekintse meg az ikonképfájl csomagolását.

Jótanács

Annak érdekében, hogy megőrizzék a visszamenőleges kompatibilitást olyan ügyfelekkel és forrásokkal, amelyek még nem támogatják a icon-t, adja meg mind a icon-t, mind a iconUrl-t. A Visual Studio támogatja icon a mappaalapú forrásból érkező csomagokat.

Readme

A NuGet 5.10.0 2- és újabb előzetes verziója támogatott

Olvasófájl csomagolásakor az readme elem használatával kell megadnia a csomag elérési útját a csomag gyökeréhez képest. Emellett meg kell győződnie arról, hogy a fájl szerepel a csomagban. A támogatott fájlformátumok közé csak a Markdown (.md) tartozik.

A következőt például hozzáadná a nuspechez, hogy becsomagoljon egy olvasófájlt a projektbe:

<package>
  <metadata>
    ...
    <readme>docs\readme.md</readme>
    ...
  </metadata>
  <files>
    ...
    <file src="..\readme.md" target="docs\" />
    ...
  </files>
</package>

Az MSBuild-ekvivalens esetében tekintse meg az olvasófájl csomagolását.

requireLicenseAcceptance

Logikai érték, amely meghatározza, hogy az ügyfélnek fel kell-e kérnie a fogyasztót a csomaglicencek elfogadására a csomag telepítése előtt.

developmentDependency

(2,8+) Logikai érték, amely meghatározza, hogy a csomag csak fejlesztési függőségként van-e megjelölve, ami megakadályozza, hogy a csomag függőségként szerepeljön más csomagokban. A PackageReference (NuGet 4.8+) használatával ez a jelző azt is jelenti, hogy kizárja a fordításból a fordítási időt. Lásd: A PackageReference DevelopmentDependency támogatása

összegzés

Fontos

summary elavult. A description használható helyette.

A csomag rövid leírása a felhasználói felület megjelenítéséhez. Ha nincs megadva, a rendszer csonkolt verzióját description használja.

Ha egy csomagot nuget.org tölt fel, a summary mező legfeljebb 4000 karakter hosszúságú lehet.

releaseNotes

(1,5+) A csomag jelen kiadásában végrehajtott módosítások leírása, amelyet gyakran használnak a felhasználói felületen, például a Visual Studio Csomagkezelő Frissítések lapján a csomag leírása helyett.

Ha egy csomagot nuget.org tölt fel, a releaseNotes mező legfeljebb 35 000 karakter hosszúságú lehet.

szerzői jog

(1,5+) A csomag szerzői jogi adatai.

Ha egy csomagot nuget.org tölt fel, a copyright mező legfeljebb 4000 karakter hosszúságú lehet.

nyelv

A csomag területi azonosítója. Lásd: Honosított csomagok létrehozása.

tags

A csomagok kereséssel és szűréssel történő felderítését segítő címkék és kulcsszavak szóközzel tagolt listája.

Ha egy csomagot nuget.org tölt fel, a tags mező legfeljebb 4000 karakter hosszúságú lehet.

Javítható

(3,3+) Csak belső NuGet-használathoz.

adattár

Az adattár metaadatai négy választható attribútumból állnak: type és url(4.0+) és branchcommit(4.6+). Ezek az attribútumok lehetővé teszik, hogy leképezze az .nupkg azt tartalmazó adattárat, és így olyan részletes legyen, mint a csomagot összeállító egyedi ágnév és/vagy véglegesítési SHA-1 kivonat. Ennek nyilvánosan elérhető URL-címnek kell lennie, amelyet közvetlenül egy verzióvezérlő szoftver hívhat meg. Ez nem lehet html oldal, mivel ez a számítógép számára készült. A projektlapra mutató hivatkozáshoz használja inkább a projectUrl mezőt.

Például:

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        ...
        <repository type="git" url="https://github.com/NuGet/NuGet.Client.git" branch="dev" commit="e1c65e4524cd70ee6e22abe33e6cb6ec73938cb3" />
        ...
    </metadata>
</package>

Ha egy csomagot nuget.org tölt fel, az type attribútum legfeljebb 100 karakter hosszúságú lehet, az url attribútum pedig legfeljebb 4000 karakter lehet.

title

A csomag emberbarát címe, amelyet egyes felhasználói felületeken lehet használni. (nuget.org és a Visual Studio Csomagkezelője nem jeleníti meg a címet)

Csomag nuget.org való feltöltésekor a title mező legfeljebb 256 karakter hosszúságú lehet, de megjelenítési célokra nem használható.

Gyűjteményelemek

packageTypes

(3,5+) Nulla vagy több <packageType> elemből álló gyűjtemény, amely meghatározza a csomag típusát, ha nem hagyományos függőségi csomagról van szó. Minden packageType név- és verzióattribútummal rendelkezik. Lásd : Csomagtípus beállítása.

függőségek

Nulla vagy több <dependency> elemből álló gyűjtemény, amely meghatározza a csomag függőségeit. Minden függőség rendelkezik az azonosító, a verzió, a ( 3.x+) és a kizárás (3.x+) attribútumával. Lásd alább a függőségeket .

frameworkAssemblies

(1,2+) A csomaghoz szükséges .NET-keretrendszer-szerelvényhivatkozásokat azonosító nulla vagy több <frameworkAssembly> elemből álló gyűjtemény, amely biztosítja, hogy a csomagot használó projektek hivatkozásai hozzáadva legyenek. Minden frameworkAssembly assemblyName és targetFramework attribútumokkal rendelkezik. Lásd az alábbi GAC-ra mutató keretrendszer-szerelvény-hivatkozásokat .

references

(1,5+) Nulla vagy több <reference> elemből álló gyűjtemény, amely a csomag mappájában lib a projekthivatkozásokként hozzáadott szerelvényeket tartalmazza. Minden hivatkozáshoz tartozik egy fájlattribútum. <references>egy targetFramework attribútummal rendelkező elemet is tartalmazhat<group>, amely ezután elemeket tartalmaz<reference>. Ha nincs megadva, a rendszer az összes hivatkozást lib tartalmazza. Lásd az alábbi explicit szerelvényhivatkozások megadását .

contentFiles

(3,3+) Olyan elemek gyűjteménye <files> , amelyek azonosítják a fogyasztó projektbe belefoglalandó tartalomfájlokat. Ezek a fájlok attribútumkészlettel vannak megadva, amelyek leírják, hogyan kell őket használni a projektrendszerben. Lásd : Az alábbi csomagban felvenni kívánt fájlok megadása .

files

A <package> csomópont tartalmazhat egy csomópontot <files> testvérként <metadata>a csomaghoz és egy <contentFiles> gyermekhez <metadata>, hogy meghatározza, mely szerelvény- és tartalomfájlokat vegye fel a csomagba. A részletekért tekintse meg a szerelvényfájlok és a tartalomfájlok beleszámítva című témakör későbbi szakaszát.

metaadat-attribútumok

minClientVersion

Megadja a csomag telepítéséhez szükséges NuGet-ügyfél minimális verzióját, amelyet a nuget.exe és a Visual Studio Package Manager kényszerít. Ez akkor használatos, ha a csomag a .nuspec NuGet-ügyfél egy adott verziójában hozzáadott fájl adott funkcióitól függ. Az attribútumot használó csomagnak például meg kell adnia a developmentDependency "2.8" értéket a következőhöz minClientVersion: "2.8". Hasonlóképpen, az contentFiles elemet használó csomagnak (lásd a következő szakaszt) "3.3" értékre kell állítania minClientVersion . Vegye figyelembe azt is, hogy mivel a 2.5 előtti NuGet-ügyfelek nem ismerik fel ezt a jelzőt, mindig elutasítják a csomag telepítését, függetlenül attól, hogy mit minClientVersion tartalmaz.

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata minClientVersion="100.0.0.1">
        <id>dasdas</id>
        <version>2.0.0</version>
        <title />
        <authors>dsadas</authors>
        <owners />
        <requireLicenseAcceptance>false</requireLicenseAcceptance>
        <description>My package description.</description>
    </metadata>
    <files>
        <file src="content\one.txt" target="content\one.txt" />
    </files>
</package>

Csere jogkivonatok

Csomag létrehozásakor a parancs lecseréli a nuget pack fájl <metadata> $-tagolt jogkivonatait .nuspec és <files> csomópontjait egy projektfájlból vagy a pack parancs kapcsolójából -properties származó értékekre.

A parancssorban a tokenértékeket a következővel nuget pack -properties <name>=<value>;<name>=<value>adhatja meg: . Használhat például egy olyan jogkivonatot, mint $owners$ a benne és $desc$ a .nuspec csomagban, és a csomagoláskor az alábbi módon adja meg az értékeket:

nuget pack MyProject.csproj -properties
    owners=janedoe,harikm,kimo,xiaop;desc="Awesome app logger utility"

Ha egy projekt értékeit szeretné használni, adja meg az alábbi táblázatban leírt jogkivonatokat (a AssemblyInfo a fájlra Properties hivatkozik például AssemblyInfo.cs vagy AssemblyInfo.vb).

A jogkivonatok használatához futtassa nuget pack a projektfájlt ahelyett, hogy csak a .nuspec. Ha például a következő parancsot használja, a $id$ fájlban lévő .nuspec és $version$ a jogkivonatok helyébe a projekt AssemblyName és AssemblyVersion az értékek kerülnek:

nuget pack MyProject.csproj

Amikor projektje van, általában az eredetileg használt nuget spec MyProject.csproj eszközt hozza létre.nuspec, amely automatikusan tartalmazza a szabványos jogkivonatok némelyikét. Ha azonban egy projekt nem tartalmaz értékeket a szükséges .nuspec elemekhez, akkor nuget pack sikertelen lesz. Továbbá, ha módosítja a projektértékeket, a csomag létrehozása előtt mindenképpen újra kell építenie; ez a csomagparancs build kapcsolójával kényelmesen elvégezhető.

A projekt értékeit kivéve $configuration$a rendszer a parancssor ugyanazon jogkivonatához rendelt összes értéket részesíti előnyben.

Jelző	Értékforrás	Érték
$id$	Projektfájl	AssemblyName (cím) a projektfájlból
$version$	AssemblyInfo	AssemblyInformationalVersion ha van, egyébként AssemblyVersion
$author$	AssemblyInfo	AssemblyCompany
$title$	AssemblyInfo	AssemblyTitle
$description$	AssemblyInfo	AssemblyDescription
$copyright$	AssemblyInfo	AssemblyCopyright
$configuration$	Szerelvény DLL-je	A szerelvény létrehozásához használt konfiguráció, amely alapértelmezés szerint hibakeresésre szolgál. Vegye figyelembe, hogy ha kiadási konfigurációval szeretne csomagot létrehozni, mindig a parancssorban kell használnia -properties Configuration=Release .

A jogkivonatok szerelvényfájlok és tartalomfájlok hozzáadásakor is feloldhatók az elérési utak. A jogkivonatok neve megegyezik az MSBuild-tulajdonságokkal, így az aktuális buildkonfigurációtól függően kiválaszthatók a belefoglalandó fájlok. Ha például az alábbi jogkivonatokat használja a .nuspec fájlban:

<files>
    <file src="bin\$configuration$\$id$.pdb" target="lib\net40" />
</files>

És létrehoz egy szerelvényt, amelynek AssemblyNameLoggingLibrary az Release MSBuild konfigurációja van, a csomagban .nuspec lévő fájl eredményül kapott sorai a következők:

<files>
    <file src="bin\Release\LoggingLibrary.pdb" target="lib\net40" />
</files>

Függőségek elem

A <dependencies> benne lévő <metadata> elem tetszőleges számú <dependency> olyan elemet tartalmaz, amely azonosítja azokat a csomagokat, amelyektől a legfelső szintű csomag függ. Az attribútumok mindegyike <dependency> a következő:

Attribute	Description
id	(Kötelező) A függőség csomagazonosítója, például az "EntityFramework" és az "NUnit", amely annak a csomagnak a neve, nuget.org megjelenik egy csomagoldalon.
version	(Kötelező) A függőségként elfogadható verziók tartománya. A pontos szintaxisért lásd a csomagverziót . A lebegő verziók nem támogatottak.
include	A belefoglalási/kizárási címkék vesszővel tagolt listája (lásd alább), amely azt jelzi, hogy a függőség szerepel-e a végső csomagban. Az alapértelmezett érték a all.
kizárás	A belefoglalási/kizárási címkék vesszővel tagolt listája (lásd alább) a végleges csomagban kizárandó függőséget jelzi. Az alapértelmezett érték, build,analyzers amely túlírható. De content/ ContentFiles implicit módon ki vannak zárva a végső csomagból, amely nem írható túl. A exclude megadott címkék elsőbbséget élveznek a include. Például include="runtime, compile" exclude="compile" ugyanaz, mint include="runtime".

Ha egy csomagot nuget.org tölt fel, az egyes függőségek attribútuma id legfeljebb 128 karakter hosszúságú lehet, az version attribútum pedig legfeljebb 256 karakter hosszúságú lehet.

Címke belefoglalása/kizárása	A cél érintett mappái
contentFiles	Content
runtime	Futtatókörnyezet, erőforrások és FrameworkAssemblies
fordít	Lib
build	build (MSBuild kellékek és célok)
eredeti	eredeti
none	Nincsenek mappák
all	Minden mappa

Az alábbi sorok például az 1.1.0-s vagy újabb verziótól és PackageB az 1.x-es verziótól PackageA való függőségeket jelzik.

<dependencies>
    <dependency id="PackageA" version="1.1.0" />
    <dependency id="PackageB" version="[1,2)" />
</dependencies>

Az alábbi sorok ugyanahhoz a csomaghoz tartozó függőségeket jelölik, de megadják, hogy a contentFilescompilebuildnativePackageAPackageB"

<dependencies>
    <dependency id="PackageA" version="1.1.0" include="contentFiles, build" />
    <dependency id="PackageB" version="[1,2)" exclude="native, compile" />
</dependencies>

Fontos

Amikor projektből hoz létre .nuspec egy projektet nuget spec, a projektben meglévő függőségek nem lesznek automatikusan belefoglalva az eredményként kapott .nuspec fájlba. Ehelyett használja nuget pack myproject.csproj, és kérje le a .nuspec fájlt a létrehozott .nupkg fájlból. Ez a .nuspec tartalmazza a függőségeket.

Függőségi csoportok

2.0-s vagy újabb verzió

Egy egyszerű lista alternatívájaként a függőségek a célprojekt keretrendszerprofilja szerint határozhatók meg a benne lévő <dependencies>elemek használatával<group>.

Minden csoport rendelkezik egy elnevezett targetFramework attribútummal, és nulla vagy több <dependency> elemet tartalmaz. Ezek a függőségek együtt vannak telepítve, ha a cél keretrendszer kompatibilis a projekt keretrendszerprofiljával.

Az <group> attribútum nélküli targetFramework elem a függőségek alapértelmezett vagy tartalék listája. A pontos keretrendszer-azonosítókért tekintse meg a cél-keretrendszereket .

Fontos

A csoportformátum nem keverhető össze egy sima listával.

Megjegyzés:

A mappában használt Target Framework Moniker (TFM) formátuma eltér a használt TFM-hez dependency groupsképest.lib/ref Ha a fájlban .nuspec és lib/ref mappában dependencies group deklarált cél-keretrendszerek nem rendelkeznek pontos egyezésekkel, akkor pack a parancs nuGet warning NU5128 figyelmeztetést ad.

Az alábbi példa az <group> elem különböző változatait mutatja be:

<dependencies>
    <group>
        <dependency id="RouteMagic" version="1.1.0" />
    </group>

    <group targetFramework=".NETFramework4.7.2">
        <dependency id="jQuery" version="1.6.2" />
        <dependency id="WebActivator" version="1.4.4" />
    </group>

    <group targetFramework="netcoreapp3.1">
    </group>
</dependencies>

Explicit szerelvényhivatkozások

Az <references> elemet a projektek packages.config használják a csomag használatakor a célprojekt által hivatkozott szerelvények explicit megadásával. Az explicit hivatkozásokat általában csak tervezési idejű szerelvényekhez használják. További információt a projektek által hivatkozott szerelvények kiválasztásáról szóló oldalon talál.

Az alábbi <references> elem például arra utasítja a NuGetet, hogy csak xunit.dllxunit.extensions.dll a csomagban lévő további szerelvényekre mutató hivatkozásokat adjon hozzá:

<references>
    <reference file="xunit.dll" />
    <reference file="xunit.extensions.dll" />
</references>

Referenciacsoportok

Egy egyszerű lista alternatívájaként hivatkozásokat lehet megadni a célprojekt keretrendszerprofiljának megfelelően, a benne található <references>elemek használatával<group>.

Minden csoport rendelkezik egy elnevezett targetFramework attribútummal, és nulla vagy több <reference> elemet tartalmaz. Ezek a hivatkozások akkor lesznek hozzáadva egy projekthez, ha a cél keretrendszer kompatibilis a projekt keretrendszerprofiljával.

Az <group> attribútum nélküli targetFramework elem a hivatkozások alapértelmezett vagy tartalék listája. A pontos keretrendszer-azonosítókért tekintse meg a cél-keretrendszereket .

Fontos

A csoportformátum nem keverhető össze egy sima listával.

Az alábbi példa az <group> elem különböző változatait mutatja be:

<references>
    <group>
        <reference file="a.dll" />
    </group>

    <group targetFramework="net45">
        <reference file="b45.dll" />
    </group>

    <group targetFramework="netcore45">
        <reference file="bcore45.dll" />
    </group>
</references>

Keretrendszer-szerelvény referenciái

A keretrendszer-szerelvények azok, amelyek a .NET-keretrendszer részét képezik, és már minden gép globális szerelvény-gyorsítótárában (GAC) kell lenniük. Az elemen belüli <frameworkAssemblies> szerelvények azonosításával a csomag biztosíthatja, hogy a szükséges hivatkozásokat hozzáadja egy projekthez abban az esetben, ha a projekt még nem rendelkezik ilyen hivatkozásokkal. Az ilyen szerelvények természetesen nem szerepelnek közvetlenül a csomagban.

Az <frameworkAssemblies> elem nulla vagy több <frameworkAssembly> elemet tartalmaz, amelyek mindegyike a következő attribútumokat adja meg:

Attribute	Description
assemblyName	(Kötelező) A teljes szerelvénynév.
targetFramework	(Nem kötelező) Meghatározza a cél keretrendszert, amelyre a hivatkozás vonatkozik. Ha nincs megadva, azt jelzi, hogy a hivatkozás az összes keretrendszerre vonatkozik. A pontos keretrendszer-azonosítókért tekintse meg a cél-keretrendszereket .

Az alábbi példában az összes cél keretrendszerre mutató hivatkozás System.Net látható, és System.ServiceModel csak a .NET-keretrendszer 4.0-s verziója:

<frameworkAssemblies>
    <frameworkAssembly assemblyName="System.Net"  />

    <frameworkAssembly assemblyName="System.ServiceModel" targetFramework="net40" />
</frameworkAssemblies>

Szerelvényfájlokat is beleértve

Ha a Csomag létrehozása című cikkben leírt konvenciók szerint jár el, nem kell explicit módon megadnia a .nuspec fájlban lévő fájlok listáját. A nuget pack parancs automatikusan felveszi a szükséges fájlokat.

Fontos

Amikor egy csomag telepítve van egy projektben, a NuGet automatikusan szerelvényhivatkozásokat ad hozzá a csomag DLL-jeihez, kivéve azokat, amelyek neve azért van elnevezve .resources.dll , mert feltételezzük, hogy honosított műholdas szerelvények. Ezért kerülje az olyan fájlok használatát .resources.dll , amelyek egyébként alapvető csomagkódot tartalmaznak.

Ha meg szeretné kerülni ezt az automatikus viselkedést, és explicit módon szabályozni szeretné, hogy mely fájlok szerepeljenek a csomagban, helyezzen el egy <files> elemet gyermekként (és annak testvéreként <package><metadata>), és azonosítsa az egyes fájlokat külön <file> elemekkel. Például:

<files>
    <file src="bin\Debug\*.dll" target="lib" />
    <file src="bin\Debug\*.pdb" target="lib" />
    <file src="tools\**\*.*" exclude="**\*.log" />
</files>

A NuGet 2.x és korábbi verzióiban, valamint az azt használó projektekben packages.configaz <files> elem nem módosítható tartalomfájlokat is tartalmaz egy csomag telepítésekor. A NuGet 3.3+ és a PackageReference projektek esetében a rendszer inkább az <contentFiles> elemet használja. Részletekért lásd: Tartalomfájlok felvétele alább.

Fájlelem-attribútumok

Minden <file> elem a következő attribútumokat adja meg:

Attribute	Description
Src	A belefoglalandó fájl vagy fájlok helye, az attribútum által exclude meghatározott kivételekre is figyelemmel. Az elérési út a .nuspec fájlhoz viszonyítva van, hacsak nincs megadva abszolút elérési út. A helyettesítő karakter * engedélyezett, a kettős helyettesítő karakter ** pedig rekurzív mappakeresést jelent.
cél	Annak a csomagnak a relatív elérési útja, amelyben a forrásfájlok vannak elhelyezve, amelynek a következővel libkell kezdődnie: , content, buildvagy tools. Lásd: .nuspec létrehozása konvencióalapú munkakönyvtárból.
Kizárása	Pontosvesszővel tagolt fájlok vagy fájlminták listája, amelyet ki szeretne zárni a src helyről. A helyettesítő karakter * engedélyezett, a kettős helyettesítő karakter ** pedig rekurzív mappakeresést jelent.

Példák

Egyetlen szerelvény

Source file:
    library.dll

.nuspec entry:
    <file src="library.dll" target="lib" />

Packaged result:
    lib\library.dll

Cél-keretrendszerhez tartozó önálló szerelvény

Source file:
    library.dll

.nuspec entry:
    <file src="assemblies\net40\library.dll" target="lib\net40" />

Packaged result:
    lib\net40\library.dll

DLL-ek készlete helyettesítő karakterrel

Source files:
    bin\release\libraryA.dll
    bin\release\libraryB.dll

.nuspec entry:
    <file src="bin\release\*.dll" target="lib" />

Packaged result:
    lib\libraryA.dll
    lib\libraryB.dll

DLL-ek különböző keretrendszerekhez

Source files:
    lib\net40\library.dll
    lib\net20\library.dll

.nuspec entry (using ** recursive search):
    <file src="lib\**" target="lib" />

Packaged result:
    lib\net40\library.dll
    lib\net20\library.dll

Fájlok kizárása

Source files:
    \tools\fileA.bak
    \tools\fileB.bak
    \tools\fileA.log
    \tools\build\fileB.log

.nuspec entries:
    <file src="tools\*.*" target="tools" exclude="tools\*.bak" />
    <file src="tools\**\*.*" target="tools" exclude="**\*.log" />

Package result:
    (no files)

Tartalomfájlok felvétele

A tartalomfájlok nem módosítható fájlok, amelyeket egy csomagnak tartalmaznia kell egy projektben. Mivel nem módosíthatók, azokat nem a fogyasztó projektnek kell módosítania. Példa tartalomfájlokra:

• Erőforrásokként beágyazott képek
• Már lefordított forrásfájlok
• Szkriptek, amelyeket hozzá kell adni a projekt buildkimenetéhez
• A csomag konfigurációs fájljai, amelyeknek szerepelnie kell a projektben, de nincs szükségük projektspecifikus módosításokra

A tartalomfájlok az elem használatával kerülnek bele a <files> csomagba, és megadják az content attribútumban lévő target mappát. Az ilyen fájlok azonban figyelmen kívül lesznek hagyva, ha a csomag a PackageReference használatával van telepítve egy projektben, amely ehelyett az <contentFiles> elemet használja.

A projektek használatával való maximális kompatibilitás érdekében a csomagok ideális esetben mindkét elem tartalomfájljait határozzák meg.

A tartalomfájlok fájlelemének használata

Tartalomfájlok esetén egyszerűen használja ugyanazt a formátumot, mint a szerelvényfájlok esetében, de adja meg content az attribútum alapmappájaként az target alábbi példákban látható módon.

Alapszintű tartalomfájlok

Source files:
    css\mobile\style1.css
    css\mobile\style2.css

.nuspec entry:
    <file src="css\mobile\*.css" target="content\css\mobile" />

Packaged result:
    content\css\mobile\style1.css
    content\css\mobile\style2.css

Tartalomfájlok címtárstruktúrával

Source files:
    css\mobile\style.css
    css\mobile\wp7\style.css
    css\browser\style.css

.nuspec entry:
    <file src="css\**\*.css" target="content\css" />

Packaged result:
    content\css\mobile\style.css
    content\css\mobile\wp7\style.css
    content\css\browser\style.css

Cél-keretrendszerre jellemző tartalomfájl

Source file:
    css\cool\style.css

.nuspec entry
    <file src="css\cool\style.css" target="Content" />

Packaged result:
    content\style.css

Névvel ellátott mappába másolt tartalomfájl

Ebben az esetben a NuGet azt látja, hogy a benne lévő target bővítmény nem egyezik meg a bővítményben src , ezért a név target ezen részét mappaként kezeli:

Source file:
    images\picture.png

.nuspec entry:
    <file src="images\picture.png" target="Content\images\package.icons" />

Packaged result:
    content\images\package.icons\picture.png

Tartalomfájlok bővítmények nélkül

Ha bővítmény nélküli fájlokat szeretne felvenni, használja a * helyettesítő karaktereket ** :

Source file:
    flags\installed

.nuspec entry:
    <file src="flags\**" target="flags" />

Packaged result:
    flags\installed

Tartalomfájlok mély elérési úttal és mély célokkal

Ebben az esetben, mivel a forrás és a cél fájlkiterjesztései egyeznek, a NuGet feltételezi, hogy a cél egy fájlnév, nem pedig mappa:

Source file:
    css\cool\style.css

.nuspec entry:
    <file src="css\cool\style.css" target="Content\css\cool" />
    or:
    <file src="css\cool\style.css" target="Content\css\cool\style.css" />

Packaged result:
    content\css\cool\style.css

Tartalomfájl átnevezése a csomagban

Source file:
    ie\css\style.css

.nuspec entry:
    <file src="ie\css\style.css" target="Content\css\ie.css" />

Packaged result:
    content\css\ie.css

Fájlok kizárása

Source file:
    docs\*.txt (multiple files)

.nuspec entry:
    <file src="docs\*.txt" target="content\docs" exclude="docs\admin.txt" />
    or
    <file src="*.txt" target="content\docs" exclude="admin.txt;log.txt" />

Packaged result:
    All .txt files from docs except admin.txt (first example)
    All .txt files from docs except admin.txt and log.txt (second example)

A contentFiles elem használata tartalomfájlokhoz

NuGet 4.0+ packageReference használatával

A csomagok alapértelmezés szerint egy contentFiles mappába helyezik a tartalmat (lásd alább), és nuget pack az alapértelmezett attribútumok használatával belefoglalják a mappába az összes fájlt. Ebben az esetben egyáltalán nem szükséges csomópontot contentFiles.nuspec belefoglalni.

Annak szabályozásához, hogy mely fájlok legyenek belefoglalva, az <contentFiles> elem meghatározza az elemek gyűjteményét <files> , amelyek pontosan azonosítják a fájlokat is.

Ezek a fájlok olyan attribútumkészlettel vannak megadva, amely leírja, hogyan kell őket használni a projektrendszerben:

Attribute	Description
tartalmaz	(Kötelező) A belefoglalandó fájl vagy fájlok helye, az attribútum által exclude meghatározott kivételekre is figyelemmel. Az elérési út a contentFiles mappához viszonyítva van, hacsak nincs megadva abszolút elérési út. A helyettesítő karakter * engedélyezett, a kettős helyettesítő karakter ** pedig rekurzív mappakeresést jelent.
Kizárása	Pontosvesszővel tagolt fájlok vagy fájlminták listája, amelyet ki szeretne zárni a src helyről. A helyettesítő karakter * engedélyezett, a kettős helyettesítő karakter ** pedig rekurzív mappakeresést jelent.
buildAction	Az MSBuild tartalomeleméhez rendelendő buildművelet, példáulContent, , NoneEmbedded Resource, Compilestb. Az alapértelmezett érték a következőCompile: .
copyToOutput	Logikai érték, amely jelzi, hogy a tartalomelemeket a buildelési (vagy közzétételi) kimeneti mappába szeretné-e másolni. Az alapértelmezett érték hamis.
lapos	Logikai érték, amely azt jelzi, hogy a tartalomelemeket egyetlen mappába szeretné-e másolni a build kimenetében (igaz), vagy meg szeretné-e őrizni a csomag mappastruktúráját (hamis). Ez a jelző csak akkor működik, ha a copyToOutput jelző értéke igaz. Az alapértelmezett érték hamis.

Csomag telepítésekor a NuGet felülről lefelé alkalmazza a gyermekelemeket <contentFiles> . Ha több bejegyzés egyezik ugyanahhoz a fájlhoz, a rendszer minden bejegyzést alkalmaz. A legfelső szintű bejegyzés felülbírálja az alacsonyabb bejegyzéseket, ha ugyanahhoz az attribútumhoz ütközik.

Csomagmappa-struktúra

A csomagprojektnek a következő mintával kell strukturálnia a tartalmat:

/contentFiles/{codeLanguage}/{TxM}/{any?}

• codeLanguages lehet cs, vb, fs, anyvagy egy adott $(ProjectLanguage)
• TxM a NuGet által támogatott jogi célkeret-moniker (lásd : Target frameworks).
• Bármely mappaszerkezet hozzáfűzhető a szintaxis végéhez.

Például:

Language- and framework-agnostic:
    /contentFiles/any/any/config.xml

net45 content for all languages
    /contentFiles/any/net45/config.xml

C#-specific content for net45 and up
    /contentFiles/cs/net45/sample.cs

Az üres mappák lehetővé _._ tehetik, hogy bizonyos nyelvi és TxM-kombinációk esetében ne adjanak meg tartalmakat, például:

/contentFiles/vb/any/code.vb
/contentFiles/cs/any/_._

Példa contentFiles szakaszra

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        ...
        <contentFiles>
            <!-- Embed image resources -->
            <files include="any/any/images/dnf.png" buildAction="EmbeddedResource" />
            <files include="any/any/images/ui.png" buildAction="EmbeddedResource" />

            <!-- Embed all image resources under contentFiles/cs/ -->
            <files include="cs/**/*.png" buildAction="EmbeddedResource" />

            <!-- Copy config.xml to the root of the output folder -->
            <files include="cs/uap/config/config.xml" buildAction="None" copyToOutput="true" flatten="true" />

            <!-- Copy run.cmd to the output folder and keep the directory structure -->
            <files include="cs/commands/run.cmd" buildAction="None" copyToOutput="true" flatten="false" />

            <!-- Include everything in the scripts folder except exe files -->
            <files include="cs/net45/scripts/*" exclude="**/*.exe"  buildAction="None" copyToOutput="true" />
        </contentFiles>
        </metadata>
</package>

Keretrendszer referenciacsoportjai

Csak 5.1-es verziójú wih PackageReference

A keretrendszerhivatkozások egy .NET Core-fogalom, amely olyan megosztott keretrendszereket jelöl, mint a WPF vagy a Windows Forms. Egy megosztott keretrendszer megadásával a csomag biztosítja, hogy az összes keretrendszerfüggősége szerepeljön a hivatkozási projektben.

Minden <group> elemhez attribútum targetFramework és nulla vagy több <frameworkReference> elem szükséges.

Az alábbi példában egy .NET Core WPF-projekthez létrehozott nuspec látható. Vegye figyelembe, hogy a keretrendszerhivatkozásokat tartalmazó nuspecs kézi írása nem ajánlott. Fontolja meg inkább a célcsomag használatát, amely automatikusan kikövetkezeli őket a projektből.

<package xmlns="http://schemas.microsoft.com/packaging/2012/06/nuspec.xsd">
  <metadata>
    <dependencies>
      <group targetFramework=".NETCoreApp3.1" />
    </dependencies>
    <frameworkReferences>
      <group targetFramework=".NETCoreApp3.1">
        <frameworkReference name="Microsoft.WindowsDesktop.App.WPF" />
      </group>
    </frameworkReferences>
  </metadata>
</package>

Példa nuspec-fájlokra

Olyan egyszerű .nuspec , amely nem határoz meg függőségeket vagy fájlokat

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>sample</id>
        <version>1.2.3</version>
        <authors>Kim Abercrombie, Franck Halmaert</authors>
        <description>Sample exists only to show a sample .nuspec file.</description>
        <language>en-US</language>
        <projectUrl>http://xunit.codeplex.com/</projectUrl>
        <license type="expression">MIT</license>
    </metadata>
</package>

A .nuspec függőségekkel

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>sample</id>
        <version>1.0.0</version>
        <authors>Microsoft</authors>
        <dependencies>
            <dependency id="another-package" version="3.0.0" />
            <dependency id="yet-another-package" version="1.0.0" />
        </dependencies>
    </metadata>
</package>

A .nuspec fájlokkal

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>routedebugger</id>
        <version>1.0.0</version>
        <authors>Jay Hamlin</authors>
        <requireLicenseAcceptance>false</requireLicenseAcceptance>
        <description>Route Debugger is a little utility I wrote...</description>
    </metadata>
    <files>
        <file src="bin\Debug\*.dll" target="lib" />
    </files>
</package>

A .nuspec keretrendszer-szerelvényekkel

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>PackageWithGacReferences</id>
        <version>1.0</version>
        <authors>Author here</authors>
        <requireLicenseAcceptance>false</requireLicenseAcceptance>
        <description>
            A package that has framework assemblyReferences depending
            on the target framework.
        </description>
        <frameworkAssemblies>
            <frameworkAssembly assemblyName="System.Web" targetFramework="net40" />
            <frameworkAssembly assemblyName="System.Net" targetFramework="net40-client, net40" />
            <frameworkAssembly assemblyName="Microsoft.Devices.Sensors" targetFramework="sl4-wp" />
            <frameworkAssembly assemblyName="System.Json" targetFramework="sl3" />
        </frameworkAssemblies>
    </metadata>
</package>

Ebben a példában a következők vannak telepítve adott projektcélokhoz:

• . NET4 ->System.Web, System.Net
• . NET4 ügyfélprofil –>System.Net
• Silverlight 3 ->System.Json
• WindowsPhone ->Microsoft.Devices.Sensors