Referenční informace k .nuspec
Soubor .nuspec
je manifest XML, který obsahuje metadata balíčku. Tento manifest se používá jak k sestavení balíčku, tak k poskytování informací příjemcům. Manifest je vždy součástí balíčku.
V tomto tématu:
- Obecný formulář a schéma
- Náhradní tokeny (při použití s projektem sady Visual Studio)
- Závislosti
- Explicitní odkazy na sestavení
- Odkazy na sestavení architektury
- Zahrnutí souborů sestavení
- Zahrnutí souborů obsahu
- Příklady souborů nuspec
Používejte
.nuspec
snuget.exe pack
projekty, které nepoužívají sadu SDK, které používajípackages.config
.Soubor
.nuspec
se nevyžaduje k vytváření balíčků pro projekty ve stylu sady SDK (obvykle projekty .NET Core a .NET Standard, které používají atribut sady SDK). (Všimněte si, že.nuspec
při vytváření balíčku se vygeneruje.)Pokud vytváříte balíček pomocí
dotnet.exe pack
nebo , doporučujeme zahrnout všechny vlastnosti, které jsou obvykle v.nuspec
souborumsbuild pack target
v souboru projektu. Místo toho však můžete použít soubor k balení pomocí.nuspec
dotnet.exe
nebomsbuild pack target
.U projektů migrovaných z
packages.config
packageReference.nuspec
se k vytvoření balíčku nevyžaduje soubor. Místo toho použijte msbuild -t:pack.
Soubor nuspec.xsd
schématu najdete v úložišti NuGet Na GitHubu.
Všimněte si, že tento soubor představuje pouze nejnovější schéma souboru .nuspec
.
Žádné oficiálně publikované verze neexistují a žádná verze tohoto souboru neodpovídá žádné konkrétní verzi NuGet.
V tomto schématu .nuspec
má soubor následující obecný formulář:
<?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>
Pokud chcete jasné vizuální znázornění schématu, otevřete soubor schématu v sadě Visual Studio v režimu návrhu a klikněte na odkaz Průzkumníka schémat XML. Případně otevřete soubor jako kód, klikněte pravým tlačítkem v editoru a vyberte Zobrazit Průzkumníka schémat XML. V obou případech získáte zobrazení jako v následujícím zobrazení (pokud se většinou rozbalí):
Všechny názvy elementů XML v souboru .nuspec rozlišují malá a velká písmena, stejně jako v případě XML obecně. Například použití elementu <description>
metadat je správné a <Description>
není správné. Správná velikost velká akmenace pro každý název elementu je zdokumentovaná níže.
Důležité
.nuspec
I když soubor obsahuje odkaz na schéma (xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd"
), tým NuGet-Team nikdy nepublikoval soubor schématu, který by se dal použít k automatickému ověření schématu.
I když jsou následující prvky minimálními požadavky na balíček, měli byste zvážit přidání volitelných prvků metadat, abyste vylepšili celkové prostředí, které s balíčkem mají vývojáři.
Tyto prvky se musí objevit v rámci elementu <metadata>
.
Identifikátor balíčku nerozlišující malá a velká písmena, který musí být jedinečný v rámci nuget.org nebo jakékoli galerie, ve které se balíček nachází. ID nemusí obsahovat mezery nebo znaky, které nejsou platné pro adresu URL, a obecně se řídí pravidly oboru názvů .NET. Pokyny najdete v tématu Volba jedinečného identifikátoru balíčku.
Při nahrávání balíčku do nuget.org id
je pole omezeno na 128 znaků.
Verze balíčku podle vzoru major.minor.patch . Čísla verzí můžou obsahovat příponu předběžné verze, jak je popsáno v tématu Správa verzí balíčků.
Při nahrávání balíčku do nuget.org version
je pole omezeno na 64 znaků.
Popis balíčku pro zobrazení uživatelského rozhraní
Při nahrávání balíčku do nuget.org description
je pole omezeno na 4 000 znaků.
Seznam autorů balíčků oddělený čárkami.
Při authors
nahrávání balíčku do nuget.org se ignorují nuspec a owners
z nuspec. Informace o nastavení vlastnictví balíčku v nuget.org najdete v tématu Správa vlastníků balíčků na nuget.org.
Důležité
vlastníci jsou zastaralí. Místo toho používejte autory.
Seznam vlastníků balíčků oddělený čárkami.
Při owners
nahrávání balíčku do nuget.org se ignoruje nuspec. Informace o nastavení vlastnictví balíčku na nuget.org najdete v tématu Správa vlastníků balíčků na nuget.org.
Adresa URL domovské stránky balíčku, často zobrazená v uživatelském rozhraní a také nuget.org.
Při nahrávání balíčku do nuget.org projectUrl
je pole omezeno na 4 000 znaků.
Důležité
licenceUrl je zastaralá. Místo toho použijte licenci.
Adresa URL licence balíčku, která se často zobrazuje v uživatelských rozhraních, jako je nuget.org.
Při nahrávání balíčku do nuget.org licenseUrl
je pole omezeno na 4 000 znaků.
Podporováno s NuGetem 4.9.0 a novějším
Výraz licence SPDX nebo cesta k souboru licence v balíčku, který se často zobrazuje v uživatelských rozhraních, jako je nuget.org. Pokud balíček licencujete pod běžnou licencí, jako je MIT nebo BSD-2-Clause, použijte přidružený identifikátor licence SPDX. Příklad:
<license type="expression">MIT</license>
Poznámka
NuGet.org přijímá pouze licenční výrazy schválené Open Source Initiative nebo Free Software Foundation.
Pokud je balíček licencovaný v rámci více běžných licencí, můžete zadat složenou licenci pomocí syntaxe výrazu SPDX verze 2.0. Příklad:
<license type="expression">BSD-2-Clause OR MIT</license>
Pokud používáte vlastní licenci, kterou výrazy licencí nepodporují, můžete zabalit .txt
nebo .md
soubor s textem licence. Příklad:
<package>
<metadata>
...
<license type="file">LICENSE.txt</license>
...
</metadata>
<files>
...
<file src="licenses\LICENSE.txt" target="" />
...
</files>
</package>
V případě ekvivalentu NÁSTROJE MSBuild se podívejte na výraz balení licenčního výrazu nebo souboru licence.
Přesná syntaxe licenčních výrazů NuGetu je popsána níže v ABNF.
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)
Důležité
ikonaUrl je zastaralá. Místo toho použijte ikonu.
Adresa URL obrázku 128x128 s pozadím průhlednosti, která se použije jako ikona balíčku v zobrazení uživatelského rozhraní. Ujistěte se, že tento prvek obsahuje přímou adresu URL obrázku, a ne adresu URL webové stránky obsahující obrázek. Pokud například chcete použít obrázek z GitHubu, použijte adresu URL nezpracovaného souboru, jako je uživatelské jméno>,< úložiště>, raw/<branch>/<logo.png>.https://github.com/<
Při nahrávání balíčku do nuget.org iconUrl
je pole omezeno na 4 000 znaků.
Podporováno s NuGetem 5.3.0 a novějším
Je to cesta k souboru obrázku v balíčku, který se často zobrazuje v uživatelských rozhraních, jako je nuget.org jako ikona balíčku. Velikost souboru obrázku je omezená na 1 MB. Mezi podporované formáty souborů patří JPEG a PNG. Doporučujeme rozlišení obrázku 128x128.
Například byste při vytváření balíčku pomocí nuget.exe přidali následující položky do souboru nuspec:
<package>
<metadata>
...
<icon>images\icon.png</icon>
...
</metadata>
<files>
...
<file src="..\icon.png" target="images\" />
...
</files>
</package>
V případě ekvivalentu nástroje MSBuild se podívejte na soubor s obrázkem Balení ikony.
Tip
Chcete-li zachovat zpětnou kompatibilitu s klienty a zdroji, které ještě nepodporují icon
, zadejte oba icon
a iconUrl
. Visual Studio podporuje icon
balíčky pocházející ze zdroje založeného na složce.
Podporováno ve verzi NuGet 5.10.0 Preview 2 a vyšší
Při balení souboru readme musíte použít readme
element k určení cesty balíčku vzhledem ke kořenovému adresáři balíčku. Kromě toho je potřeba zajistit, aby byl soubor součástí balíčku. Podporované formáty souborů zahrnují pouze Markdown (.md).
Například byste do souboru nuspec přidali následující kód, abyste do projektu zabalili soubor readme:
<package>
<metadata>
...
<readme>docs\readme.md</readme>
...
</metadata>
<files>
...
<file src="..\readme.md" target="docs\" />
...
</files>
</package>
Pro ekvivalent NÁSTROJE MSBuild se podívejte na zabalení souboru readme.
Logická hodnota určující, zda klient musí před instalací balíčku vyzvat příjemce, aby přijal licenci balíčku.
(2,8+) Logická hodnota určující, zda je balíček označen jako závislost určená pouze pro vývoj, což brání zahrnutí balíčku jako závislosti v jiných balíčcích. U PackageReference (NuGet 4.8+) tento příznak také znamená, že z kompilace vyloučí prostředky v době kompilace. Viz podpora DevelopmentDependency pro PackageReference
Důležité
summary
je zastaralá. Místo toho použijte description
.
Stručný popis balíčku pro zobrazení uživatelského rozhraní. Pokud tuto hodnotu vynecháte, použije se zkrácená verze description
.
Při nahrávání balíčku do nuget.org summary
je pole omezeno na 4 000 znaků.
(1,5+) Popis změn provedených v této verzi balíčku, často používaný v uživatelském rozhraní, jako je karta Aktualizace sady Visual Studio Správce balíčků místo popisu balíčku.
Při nahrávání balíčku do nuget.org releaseNotes
je pole omezeno na 35 000 znaků.
(1,5+) Podrobnosti o autorských právech pro balíček.
Při nahrávání balíčku do nuget.org copyright
je pole omezeno na 4 000 znaků.
ID národního prostředí pro balíček. Viz Vytváření lokalizovaných balíčků.
Seznam značek a klíčových slov oddělených mezerami, které popisují balíček a pomáhají zjistitelnost balíčků prostřednictvím vyhledávání a filtrování.
Při nahrávání balíčku do nuget.org tags
je pole omezeno na 4 000 znaků.
(3.3+) Pouze pro interní použití NuGetu.
Metadata úložiště, která se skládají ze čtyř volitelných atributů: type
a url
(4.0+) a commit
branch
(4.6+). Tyto atributy umožňují namapovat .nupkg
na úložiště, které ho vytvořilo, s potenciálem získat podrobné informace o názvu jednotlivé větve a /nebo potvrzení hodnoty hash SHA-1, která balíček vytvořila. Měla by to být veřejně dostupná adresa URL, kterou může vyvolat přímo software pro správu verzí. Neměl by to být html stránka, protože je určená pro počítač. Pro propojení se stránkou projectUrl
projektu použijte místo toho pole.
Příklad:
<?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>
Při nahrávání balíčku do nuget.org type
je atribut omezen na 100 znaků a url
atribut je omezen na 4 000 znaků.
Popisný název balíčku, který se dá použít v některých displejích uživatelského rozhraní. (nuget.org a Správce balíčků v sadě Visual Studio nezobrazují název)
Při nahrávání balíčku do nuget.org je pole omezeno na 256 znaků, title
ale nepoužívá se pro žádné účely zobrazení.
(3,5+) Kolekce nula nebo více <packageType>
prvků určující typ balíčku, pokud jiný než tradiční balíček závislostí. Každý packageType má atributy názvu a verze. Viz Nastavení typu balíčku.
Kolekce nulových nebo více <dependency>
prvků určujících závislosti balíčku. Každá závislost má atributy ID, verze, zahrnutí (3.x+) a vyloučení (3.x+). Viz závislosti níže.
(1,2+) Kolekce nulových nebo více <frameworkAssembly>
prvků identifikující odkazy na sestavení rozhraní .NET Framework, které tento balíček vyžaduje, což zajišťuje přidání odkazů do projektů, které balíček využívají. Každá frameworkAssembly má atributy assemblyName a targetFramework . Viz Určení sestavení architektury odkazuje GAC níže.
(1,5+) Kolekce nulových nebo více <reference>
prvků pojmenování sestavení ve složce balíčku lib
, které jsou přidány jako odkazy na projekt. Každý odkaz má atribut souboru . <references>
může také obsahovat <group>
prvek s atributem targetFramework , který pak obsahuje <reference>
elementy. Pokud tento parametr vynecháte, budou zahrnuty všechny odkazy lib
. Viz Určení explicitních odkazů na sestavení níže.
(3.3+) Kolekce <files>
prvků, které identifikují soubory obsahu, které se mají zahrnout do spotřebujícího projektu. Tyto soubory jsou zadány pomocí sady atributů, které popisují, jak se mají používat v rámci systému projektu. Viz Určení souborů, které se mají zahrnout do balíčku níže.
Uzel <package>
může obsahovat <files>
uzel jako na stejné úrovni <metadata>
a podřízenou pod <metadata>
položkou <contentFiles>
určit, které soubory sestavení a obsahu mají být zahrnuty do balíčku. Podrobnosti najdete v části Zahrnutí souborů sestavení a zahrnutí souborů obsahu dále v tomto tématu.
Určuje minimální verzi klienta NuGet, který může nainstalovat tento balíček vynucený nuget.exe a Správce balíčků sady Visual Studio. Používá se vždy, když balíček závisí na konkrétních funkcích .nuspec
souboru, které byly přidány v konkrétní verzi klienta NuGet. Například balíček, který používá developmentDependency
atribut, by měl zadat "2.8" pro minClientVersion
. Podobně by měl balíček používající contentFiles
prvek (viz další část) nastavit minClientVersion
na hodnotu 3.3. Všimněte si také, že vzhledem k tomu, že klienti NuGet před verzí 2.5 tento příznak nerozpoznávají, vždy odmítá instalovat balíček bez ohledu na to, co minClientVersion
obsahuje.
<?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>
Při vytváření balíčku nuget pack
nahradí příkaz tokeny s oddělovači $v .nuspec
souborech <metadata>
a <files>
uzlech hodnotami, které pocházejí ze souboru projektu nebo pack
přepínače příkazu -properties
.
Na příkazovém řádku zadáte hodnoty tokenu pomocí nuget pack -properties <name>=<value>;<name>=<value>
. Můžete například použít token, například $owners$
a v a $desc$
.nuspec
zadat hodnoty v době balení následujícím způsobem:
nuget pack MyProject.csproj -properties
owners=janedoe,harikm,kimo,xiaop;desc="Awesome app logger utility"
Pokud chcete použít hodnoty z projektu, zadejte tokeny popsané v následující tabulce (AssemblyInfo odkazuje na soubor, Properties
například AssemblyInfo.cs
nebo AssemblyInfo.vb
).
Pokud chcete tyto tokeny použít, spusťte nuget pack
soubor projektu místo jen s .nuspec
. Například při použití následujícího příkazu $id$
se tokeny $version$
v .nuspec
souboru nahradí hodnotami a AssemblyVersion
hodnotami projektuAssemblyName
:
nuget pack MyProject.csproj
Když máte projekt, obvykle vytvoříte .nuspec
počáteční použití nuget spec MyProject.csproj
, které automaticky zahrnuje některé z těchto standardních tokenů. Pokud však projekt nemá hodnoty požadovaných .nuspec
prvků, selže nuget pack
. Kromě toho, pokud změníte hodnoty projektu, nezapomeňte před vytvořením balíčku znovu sestavit; to lze provést pohodlně pomocí přepínače příkazu build
balíčku.
S výjimkou $configuration$
hodnot v projektu se používají přednost před všemi přiřazenými ke stejnému tokenu na příkazovém řádku.
Token | Zdroj hodnoty | Hodnota |
---|---|---|
$id$ | Soubor projektu | AssemblyName (title) ze souboru projektu |
$version$ | AssemblyInfo | AssemblyInformationalVersion, pokud je k dispozici, jinak AssemblyVersion |
$author$ | AssemblyInfo | AssemblyCompany |
$title$ | AssemblyInfo | AssemblyTitle |
$description$ | AssemblyInfo | Popis sestavení |
$copyright$ | AssemblyInfo | AssemblyCopyright |
$configuration$ | Knihovna DLL sestavení | Konfigurace použitá k sestavení, výchozí nastavení ladění. Mějte na paměti, že k vytvoření balíčku pomocí konfigurace vydané verze se vždy používá -properties Configuration=Release na příkazovém řádku. |
Tokeny lze také použít k překladu cest při zahrnutí souborů sestavení a souborů obsahu. Tokeny mají stejné názvy jako vlastnosti NÁSTROJE MSBuild, což umožňuje vybrat soubory, které se mají zahrnout v závislosti na aktuální konfiguraci sestavení. Pokud například v souboru použijete následující tokeny .nuspec
:
<files>
<file src="bin\$configuration$\$id$.pdb" target="lib\net40" />
</files>
A sestavíte sestavení, jehož AssemblyName
je LoggingLibrary
s Release
konfigurací v nástroji MSBuild, výsledné řádky v .nuspec
souboru v balíčku jsou následující:
<files>
<file src="bin\Release\LoggingLibrary.pdb" target="lib\net40" />
</files>
Prvek <dependencies>
uvnitř <metadata>
obsahuje libovolný počet <dependency>
prvků, které identifikují další balíčky, na kterých závisí balíček nejvyšší úrovně. Atributy pro každou z nich <dependency>
jsou následující:
Atribut | Popis |
---|---|
id |
(Povinné) ID balíčku závislosti, například EntityFramework a NUnit, což je název balíčku nuget.org se zobrazuje na stránce balíčku. |
version |
(Povinné) Rozsah verzí přijatelných jako závislost. Přesné syntaxe najdete v tématu Správa verzí balíčků. Plovoucí verze nejsou podporovány. |
include | Čárkami oddělený seznam značek include/exclude (viz níže) označující závislost, která se má zahrnout do konečného balíčku. Výchozí hodnota je all . |
vyloučení | Čárkami oddělený seznam značek include/exclude (viz níže) označující závislost, která se má vyloučit v konečném balíčku. Výchozí hodnota je build,analyzers možné přepsat. Ale content/ ContentFiles také jsou implicitně vyloučeny do konečného balíčku, který nelze přepsat. Značky zadané s exclude předností před značkami zadanými pomocí include . Například trasa include="runtime, compile" exclude="compile" je stejná jako include="runtime" . |
Při nahrávání balíčku do nuget.org je atribut každé závislosti id
omezen na 128 znaků a version
atribut je omezen na 256 znaků.
Zahrnout nebo vyloučit značku | Ovlivněné složky cíle |
---|---|
contentFiles | Content |
modul runtime | Modul runtime, prostředky a FrameworkAssemblies |
kompilovat | osvobození |
build | sestavení (props a cíle NÁSTROJE MSBuild) |
nativní | nativní |
Žádná | Žádné složky |
vše | Všechny složky |
Například následující řádky označují závislosti na PackageA
verzi 1.1.0 nebo vyšší a PackageB
verzi 1.x.
<dependencies>
<dependency id="PackageA" version="1.1.0" />
<dependency id="PackageB" version="[1,2)" />
</dependencies>
Následující řádky označují závislosti na stejných balíčcích, ale zadejte, aby zahrnovaly a složek PackageA
a vše kromě native
složek PackageB
"compile
build
contentFiles
<dependencies>
<dependency id="PackageA" version="1.1.0" include="contentFiles, build" />
<dependency id="PackageB" version="[1,2)" exclude="native, compile" />
</dependencies>
Důležité
Při vytváření .nuspec
z projektu pomocí nuget spec
, závislosti, které existují v tomto projektu, nejsou automaticky zahrnuty do výsledného .nuspec
souboru. Místo toho použijte nuget pack myproject.csproj
soubor .nuspec a získejte soubor .nuspec z vygenerovaného souboru .nupkg . Tento soubor .nuspec obsahuje závislosti.
Verze 2.0 nebo novější
Jako alternativu k jednomu plochém seznamu lze závislosti zadat podle profilu architektury cílového projektu pomocí <group>
prvků v rámci <dependencies>
.
Každá skupina má pojmenovaný targetFramework
atribut a obsahuje nula nebo více <dependency>
prvků. Tyto závislosti se nainstalují společně, když je cílová architektura kompatibilní s profilem architektury projektu.
Element <group>
bez atributu targetFramework
se používá jako výchozí nebo záložní seznam závislostí. Přesné identifikátory rozhraní najdete v cílových architekturách.
Důležité
Formát skupiny nelze intermixovat s plochým seznamem.
Poznámka
Formát rozhraní TFM (Target Framework Moniker) použitý ve lib/ref
složce se liší v porovnání s TFM použitým v dependency groups
. Pokud cílové architektury deklarované v dependencies group
souboru a lib/ref
složka .nuspec
souboru nemají přesné shody, pack
příkaz vyvolá Upozornění NuGet NU5128.
Následující příklad ukazuje různé varianty elementu <group>
:
<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>
Element <references>
je používán projekty pomocí packages.config
explicitně určit sestavení, na která má cílový projekt odkazovat při použití balíčku. Explicitní odkazy se obvykle používají pro sestavení pouze v době návrhu. Další informace naleznete na stránce o výběru sestavení odkazovaných projekty další informace.
Následující <references>
element například dává NuGet pokyn, aby přidal odkazy pouze na a xunit.dll
xunit.extensions.dll
dokonce i v případě, že balíček obsahuje další sestavení:
<references>
<reference file="xunit.dll" />
<reference file="xunit.extensions.dll" />
</references>
Jako alternativu k jednomu plochém seznamu lze odkazy zadat podle profilu architektury cílového projektu pomocí <group>
prvků v rámci <references>
.
Každá skupina má pojmenovaný targetFramework
atribut a obsahuje nula nebo více <reference>
prvků. Tyto odkazy se přidají do projektu, pokud je cílová architektura kompatibilní s profilem architektury projektu.
Prvek <group>
bez atributu targetFramework
se používá jako výchozí nebo záložní seznam odkazů. Přesné identifikátory rozhraní najdete v cílových architekturách.
Důležité
Formát skupiny nelze intermixovat s plochým seznamem.
Následující příklad ukazuje různé varianty elementu <group>
:
<references>
<group>
<reference file="a.dll" />
</group>
<group targetFramework="net45">
<reference file="b45.dll" />
</group>
<group targetFramework="netcore45">
<reference file="bcore45.dll" />
</group>
</references>
Sestavení rozhraní jsou ta, která jsou součástí rozhraní .NET Framework a již by měla být v globální mezipaměti sestavení (GAC) pro každý daný počítač. Identifikací těchto sestavení v rámci elementu <frameworkAssemblies>
může balíček zajistit, aby se požadované odkazy přidaly do projektu v případě, že projekt tyto odkazy ještě neobsahuje. Tato sestavení samozřejmě nejsou zahrnuta do balíčku přímo.
Prvek <frameworkAssemblies>
obsahuje nula nebo více <frameworkAssembly>
prvků, z nichž každý určuje následující atributy:
Atribut | Popis |
---|---|
assemblyName | (Povinné) Plně kvalifikovaný název sestavení. |
targetFramework | (Volitelné) Určuje cílovou architekturu, na kterou se tento odkaz vztahuje. Pokud tento argument vynecháte, znamená to, že odkaz platí pro všechny architektury. Přesné identifikátory rozhraní najdete v cílových architekturách. |
Následující příklad ukazuje odkaz na System.Net
všechny cílové architektury a odkaz pouze na System.ServiceModel
rozhraní .NET Framework 4.0:
<frameworkAssemblies>
<frameworkAssembly assemblyName="System.Net" />
<frameworkAssembly assemblyName="System.ServiceModel" targetFramework="net40" />
</frameworkAssemblies>
Pokud dodržujete konvence popsané v části Vytváření balíčku, nemusíte explicitně zadávat seznam souborů v .nuspec
souboru. Příkaz nuget pack
automaticky převezme potřebné soubory.
Důležité
Když je balíček nainstalován do projektu, NuGet automaticky přidá odkazy na sestavení do knihoven DLL balíčku, s výjimkou těch, které jsou pojmenovány .resources.dll
, protože se předpokládá, že jsou lokalizovaná satelitní sestavení. Z tohoto důvodu nepoužívejte .resources.dll
soubory, které jinak obsahují základní kód balíčku.
Chcete-li toto automatické chování obejít a explicitně řídit, které soubory jsou součástí balíčku, umístěte <files>
prvek jako podřízený <package>
prvek (a stejné <metadata>
úrovně ), identifikujte každý soubor samostatným <file>
prvkem. Příklad:
<files>
<file src="bin\Debug\*.dll" target="lib" />
<file src="bin\Debug\*.pdb" target="lib" />
<file src="tools\**\*.*" exclude="**\*.log" />
</files>
S NuGet 2.x a starší a projekty používající packages.config
, <files>
element se také používá k zahrnutí neměnných souborů obsahu při instalaci balíčku. U NuGetu 3.3+ a projektů PackageReference se místo <contentFiles>
toho použije prvek. Podrobnosti najdete v části Zahrnutí souborů obsahu níže.
Každý <file>
prvek určuje následující atributy:
Atribut | Popis |
---|---|
Src | Umístění souboru nebo souborů, které se mají zahrnout, s výhradou vyloučení určených atributem exclude . Cesta je relativní vzhledem k .nuspec souboru, pokud není zadána absolutní cesta. Zástupný znak je povolený a dvojitý zástupný znak * ** znamená rekurzivní hledání ve složce. |
cíl | Relativní cesta ke složce v balíčku, kde jsou umístěny zdrojové soubory, které musí začínat lib na , content , build nebo tools . Viz Vytvoření souboru .nuspec z pracovního adresáře založeného na konvenci. |
vyloučit | Seznam souborů nebo vzorů souborů oddělených středníkem, které se mají vyloučit z src umístění. Zástupný znak je povolený a dvojitý zástupný znak * ** znamená rekurzivní hledání ve složce. |
Jedno sestavení
Source file:
library.dll
.nuspec entry:
<file src="library.dll" target="lib" />
Packaged result:
lib\library.dll
Jedno sestavení specifické pro cílovou architekturu
Source file:
library.dll
.nuspec entry:
<file src="assemblies\net40\library.dll" target="lib\net40" />
Packaged result:
lib\net40\library.dll
Sada knihoven DLL pomocí zástupného znaku
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
Knihovny DLL pro různé architektury
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
Vyloučení souborů
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)
Soubory obsahu jsou neměnné soubory, které balíček musí zahrnout do projektu. Neměnné, nejsou určeny k úpravě projektem, který využívá. Mezi ukázkové soubory obsahu patří:
- Obrázky vložené jako prostředky
- Zdrojové soubory, které jsou již zkompilovány
- Skripty, které je potřeba zahrnout do výstupu sestavení projektu
- Konfigurační soubory balíčku, který je potřeba zahrnout do projektu, ale nepotřebují žádné změny specifické pro projekt
Soubory obsahu jsou součástí balíčku pomocí elementu <files>
a určují content
složku v atributu target
. Tyto soubory jsou však ignorovány, pokud je balíček nainstalován v projektu pomocí PackageReference, který místo toho používá <contentFiles>
prvek.
Kvůli maximální kompatibilitě s využíváním projektů balíček ideálně určuje soubory obsahu v obou prvech.
Pro soubory obsahu jednoduše použijte stejný formát jako pro soubory sestavení, ale jako content
základní složku v atributu target
, jak je znázorněno v následujících příkladech.
Základní soubory obsahu
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
Soubory obsahu s adresářovou strukturou
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
Soubor obsahu specifický pro cílovou architekturu
Source file:
css\cool\style.css
.nuspec entry
<file src="css\cool\style.css" target="Content" />
Packaged result:
content\style.css
Soubor obsahu zkopírovaný do složky s tečkou v názvu
V tomto případě NuGet zjistí, že rozšíření target
neodpovídá rozšíření, a src
proto považuje tuto část názvu target
za složku:
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
Soubory obsahu bez přípon
Pokud chcete zahrnout soubory bez přípony, použijte *
tyto zástupné **
cardy:
Source file:
flags\installed
.nuspec entry:
<file src="flags\**" target="flags" />
Packaged result:
flags\installed
Soubory obsahu s hlubokou cestou a hloubkovým cílem
V tomto případě se vzhledem k tomu, že přípony souborů zdrojové a cílové shody shodují, NuGet předpokládá, že cílem je název souboru, nikoli složka:
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
Přejmenování souboru obsahu v balíčku
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
Vyloučení souborů
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)
NuGet 4.0 a novější s PackageReference
Ve výchozím nastavení balíček umístí obsah do contentFiles
složky (viz níže) a nuget pack
zahrne všechny soubory do této složky pomocí výchozích atributů. V takovém případě není nutné do něj vůbec zahrnout contentFiles
uzel .nuspec
.
Chcete-li určit, které soubory jsou zahrnuty, <contentFiles>
je element určuje kolekci <files>
prvků, které identifikují přesné soubory zahrnují.
Tyto soubory se zadají pomocí sady atributů, které popisují, jak se mají používat v rámci systému projektu:
Atribut | Popis |
---|---|
include | (Povinné) Umístění souboru nebo souborů, které se mají zahrnout, s výhradou vyloučení určených atributem exclude . Cesta je relativní vzhledem ke contentFiles složce, pokud není zadána absolutní cesta. Zástupný znak je povolený a dvojitý zástupný znak * ** znamená rekurzivní hledání ve složce. |
vyloučit | Seznam souborů nebo vzorů souborů oddělených středníkem, které se mají vyloučit z src umístění. Zástupný znak je povolený a dvojitý zástupný znak * ** znamená rekurzivní hledání ve složce. |
buildAction | Akce sestavení, která se přiřadí k položce obsahu nástroje MSBuild, například Content , None , Embedded Resource , Compile atd. Výchozí hodnota je Compile . |
copyToOutput | Logická hodnota označující, jestli se mají kopírovat položky obsahu do výstupní složky sestavení (nebo publikování). Výchozí hodnotou je hodnota false. |
zploštit | Logická hodnota označující, jestli se mají kopírovat položky obsahu do jedné složky ve výstupu sestavení (true), nebo zachovat strukturu složek v balíčku (false). Tento příznak funguje jenom v případě, že je příznak copyToOutput nastavený na true. Výchozí hodnotou je hodnota false. |
Při instalaci balíčku použije NuGet podřízené prvky <contentFiles>
shora dolů. Pokud se stejný soubor shoduje s více položkami, použijí se všechny položky. Nejvyšší položka přepíše nižší položky, pokud dojde ke konfliktu pro stejný atribut.
Projekt balíčku by měl strukturovat obsah pomocí následujícího vzoru:
/contentFiles/{codeLanguage}/{TxM}/{any?}
codeLanguages
mohou býtcs
, ,fs
vb
any
, nebo malými písmeny ekvivalentní danému$(ProjectLanguage)
TxM
je libovolný moniker právního cílového rozhraní, který NuGet podporuje (viz cílové architektury).- Na konec této syntaxe může být připojena jakákoli struktura složek.
Příklad:
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
Prázdné složky můžou použít _._
k vyjádření nesouhlasu s poskytováním obsahu pro určité kombinace jazyka a TxM, například:
/contentFiles/vb/any/code.vb
/contentFiles/cs/any/_._
<?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>
Pouze verze 5.1+ wih PackageReference
Odkazy na rozhraní jsou koncept .NET Core představující sdílené architektury, jako je WPF nebo model Windows Forms. Zadáním sdílené architektury balíček zajistí, aby všechny jeho závislosti architektury byly zahrnuty do odkazujícího projektu.
Každý <group>
prvek vyžaduje targetFramework
atribut a nula nebo více <frameworkReference>
prvků.
Následující příklad ukazuje nuspec vygenerovaný pro projekt WPF .NET Core. Všimněte si, že ruční vytváření nuspecs, které obsahují odkazy na architekturu, se nedoporučuje. Zvažte místo toho použití balíčku cílů , který je automaticky odvodí z projektu.
<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>
Jednoduchý .nuspec
, který neurčoval závislosti nebo soubory
<?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
s závislostmi
<?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
with files
<?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
s sestaveními architektury
<?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>
V tomto příkladu jsou pro konkrétní cíle projektu nainstalovány následující položky:
- . NET4 –>
System.Web
,System.Net
- . Profil klienta NET4 –>
System.Net
- Silverlight 3 –>
System.Json
- WindowsPhone –>
Microsoft.Devices.Sensors