Sdílet prostřednictvím

Referenční informace k .nuspec

  • Článek

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:

Kompatibilita typů projektů

  • Používejte .nuspec s nuget.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 souboru msbuild pack targetv souboru projektu. Místo toho však můžete použít soubor k balení pomocí .nuspec dotnet.exe nebo msbuild 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.

Obecný formulář a schéma

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í):

Průzkumník schémat sady Visual Studio s otevřeným souborem nuspec.xsd

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.

Požadované prvky metadat

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> .

ID

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ů.

version

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ů.

description

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ů.

autoři

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.

Volitelné prvky metadat

majitelé

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.

projectUrl

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ů.

licenseUrl

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ů.

license

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)

iconUrl

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ů.

ikona

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>

Ukázka nuspec ikony balíčku

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.

readme

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.

requireLicenseAcceptance

Logická hodnota určující, zda klient musí před instalací balíčku vyzvat příjemce, aby přijal licenci balíčku.

developmentDependency

(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

Souhrn

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ů.

releaseNotes

(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ů.

jazyk

ID národního prostředí pro balíček. Viz Vytváření lokalizovaných balíčků.

značky

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ů.

užitečný

(3.3+) Pouze pro interní použití NuGetu.

úložiště

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ů.

title

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í.

Prvky kolekce

packageTypes

(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.

závislosti

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.

frameworkAssemblies

(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.

odkazy

(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.

contentFiles

(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.

files

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.

atributy metadat

minClientVersion

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>

Náhradní tokeny

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>

Dependencies – element

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.csprojsoubor .nuspec a získejte soubor .nuspec z vygenerovaného souboru .nupkg . Tento soubor .nuspec obsahuje závislosti.

Skupiny závislostí

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>

Explicitní odkazy na sestavení

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>

Referenční skupiny

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>

Odkazy na sestavení architektury

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>

Zahrnutí souborů sestavení

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.

Atributy elementu File

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 libna , content, buildnebo 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.

Příklady

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)

Zahrnutí souborů obsahu

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.

Použití elementu files pro soubory obsahu

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)

Použití elementu contentFiles pro soubory obsahu

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, Compileatd. 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.

Struktura složek balíčků

Projekt balíčku by měl strukturovat obsah pomocí následujícího vzoru:

/contentFiles/{codeLanguage}/{TxM}/{any?}
  • codeLanguagesmohou být cs, , fsvbany, 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/_._

Příklad oddílu contentFiles

<?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>

Referenční skupiny architektury

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>

Příklady souborů nuspec

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