Delen via

.nuspec-verwijzing

Een .nuspec bestand is een XML-manifest dat pakketmetagegevens bevat. Dit manifest wordt zowel gebruikt om het pakket te bouwen als om gebruikers informatie te verstrekken. Het manifest is altijd opgenomen in een pakket.

In dit onderwerp:

Compatibiliteit van projecttypen

  • Gebruiken .nuspec met nuget.exe pack voor niet-SDK-projecten die gebruikmaken van packages.config.

  • Een .nuspec bestand is niet vereist voor het maken van pakketten voor SDK-projecten (meestal .NET Core- en .NET Standard-projecten die gebruikmaken van het SDK-kenmerk. (Houd er rekening mee dat er een .nuspec wordt gegenereerd wanneer u het pakket maakt.)

    Als u een pakket maakt met of dotnet.exe packmsbuild pack target, wordt u aangeraden alle eigenschappen op te nemen die zich meestal in het .nuspec bestand in het projectbestand bevinden. U kunt er echter voor kiezen om een .nuspec bestand te gebruiken dat u wilt inpakken of dotnet.exemsbuild pack target.

  • Voor projecten die van packages.config naar PackageReference zijn gemigreerd, is een .nuspec bestand niet vereist om het pakket te maken. Gebruik in plaats daarvan msbuild -t:pack.

Algemeen formulier en schema

Een nuspec.xsd schemabestand vindt u in de NuGet GitHub-opslagplaats. Houd er rekening mee dat dit bestand alleen het meest recente schema voor een .nuspec bestand vertegenwoordigt. Er bestaan geen officieel gepubliceerde versies en er komt geen versie van dat bestand overeen met een specifieke NuGet-versie.

Binnen dit schema heeft een .nuspec bestand de volgende algemene vorm:

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

Voor een duidelijke visuele weergave van het schema opent u het schemabestand in Visual Studio in de ontwerpmodus en klikt u op de koppeling XML Schema Explorer . U kunt het bestand ook openen als code, met de rechtermuisknop in de editor klikken en XML-schemaverkenner weergeven selecteren. In beide gevallen krijgt u een weergave zoals hieronder (meestal uitgevouwen):

Visual Studio Schema Explorer met nuspec.xsd geopend

Alle NAMEN van XML-elementen in het .nuspec-bestand zijn hoofdlettergevoelig, net als voor XML in het algemeen. Het gebruik van het metagegevenselement <description> is bijvoorbeeld juist en <Description> is niet juist. Hieronder vindt u de juiste behuizing voor elke elementnaam.

Belangrijk

Hoewel het .nuspec bestand een verwijzing naar een schema (xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd") bevat, heeft de NuGet-Team nog nooit een schemabestand gepubliceerd dat kan worden gebruikt voor automatische schemavalidatie.

Vereiste metagegevenselementen

Hoewel de volgende elementen de minimale vereisten voor een pakket zijn, kunt u overwegen de optionele metagegevenselementen toe te voegen om de algehele ervaring die ontwikkelaars met uw pakket hebben te verbeteren.

Deze elementen moeten in een <metadata> element worden weergegeven.

identiteitskaart

De niet-hoofdlettergevoelige pakket-id, die uniek moet zijn in nuget.org of in welke galerie het pakket zich bevindt. Id's bevatten mogelijk geen spaties of tekens die niet geldig zijn voor een URL en volgen over het algemeen de regels voor .NET-naamruimten. Zie Een unieke pakket-id kiezen voor richtlijnen.

Wanneer u een pakket uploadt naar nuget.org, is het id veld beperkt tot 128 tekens.

version

De versie van het pakket, volgens het major.minor.patch-patroon . Versienummers kunnen een pre-releaseachtervoegsel bevatten, zoals beschreven in pakketversiebeheer.

Wanneer u een pakket uploadt naar nuget.org, is het version veld beperkt tot 64 tekens.

beschrijving

Een beschrijving van het pakket voor weergave van de gebruikersinterface.

Wanneer u een pakket uploadt naar nuget.org, is het description veld beperkt tot 4000 tekens.

authors

Een door komma's gescheiden lijst met pakketauteurs. De authors en de owners van de nuspec worden genegeerd bij het uploaden van het pakket naar nuget.org. Zie Pakketeigenaren beheren op nuget.org voor informatie over het instellen van het eigendom van pakketten op nuget.org.

Optionele metagegevenselementen

Eigenaren

Belangrijk

eigenaren zijn afgeschaft. Gebruik in plaats daarvan auteurs.

Een door komma's gescheiden lijst met pakketeigenaren. De owners van de nuspec wordt genegeerd bij het uploaden van het pakket naar nuget.org. Zie Pakketeigenaren beheren op nuget.org voor informatie over het instellen van het eigendom van pakketten op nuget.org.

projectUrl

Een URL voor de startpagina van het pakket, die vaak wordt weergegeven in de gebruikersinterface en nuget.org.

Wanneer u een pakket uploadt naar nuget.org, is het projectUrl veld beperkt tot 4000 tekens.

licenseUrl

Belangrijk

licenseUrl is afgeschaft. Gebruik in plaats daarvan een licentie.

Een URL voor de licentie van het pakket, die vaak wordt weergegeven in UIs, zoals nuget.org.

Wanneer u een pakket uploadt naar nuget.org, is het licenseUrl veld beperkt tot 4000 tekens.

licentie

Ondersteund met NuGet 4.9.0 en hoger

Een SPDX-licentieexpressie of -pad naar een licentiebestand in het pakket, vaak weergegeven in UIS's zoals nuget.org. Als u het pakket in licentie geeft onder een gemeenschappelijke licentie, zoals MIT of BSD-2-Clause, gebruikt u de bijbehorende SPDX-licentie-id. Voorbeeld:

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

Opmerking

NuGet.org accepteert alleen licentie-expressies die zijn goedgekeurd door het Open Source Initiative of de Free Software Foundation.

Als uw pakket is gelicentieerd onder meerdere algemene licenties, kunt u een samengestelde licentie opgeven met behulp van de syntaxis van de SPDX-expressie versie 2.0. Voorbeeld:

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

Als u een aangepaste licentie gebruikt die niet wordt ondersteund door licentie-expressies, kunt u een .txt of .md bestand inpakken met de tekst van de licentie. Voorbeeld:

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

Bekijk voor het equivalent van MSBuild een licentie-expressie of een licentiebestand inpakken.

De exacte syntaxis van de licentie-expressies van NuGet wordt hieronder beschreven in 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

Belangrijk

iconUrl is afgeschaft. Gebruik in plaats daarvan het pictogram.

Een URL voor een afbeelding van 128x128 met transparantieachtergrond die moet worden gebruikt als pictogram voor het pakket in de ui-weergave. Zorg ervoor dat dit element de URL van de directe afbeelding bevat en niet de URL van een webpagina die de afbeelding bevat. Als u bijvoorbeeld een afbeelding van GitHub wilt gebruiken, gebruikt u de URL van het onbewerkte bestand, zoals https://github.com/<gebruikersnaam>/<opslagplaats>/raw/<branch>/<logo.png>.

Wanneer u een pakket uploadt naar nuget.org, is het iconUrl veld beperkt tot 4000 tekens.

icon

Ondersteund met NuGet 5.3.0 en hoger

Het is een pad naar een afbeeldingsbestand in het pakket, dat vaak wordt weergegeven in UIs, zoals nuget.org als het pakketpictogram. De grootte van het afbeeldingsbestand is beperkt tot 1 MB. Ondersteunde bestandsindelingen zijn JPEG en PNG. We raden een afbeeldingsresolutie van 128x128 aan.

U voegt bijvoorbeeld het volgende toe aan uw nuspec bij het maken van een pakket met behulp van nuget.exe:

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

Nuspec-voorbeeld pakketpictogram.

Voor het equivalent van MSBuild bekijkt u Het inpakken van een pictogramafbeeldingsbestand.

Aanbeveling

Als u compatibiliteit met eerdere versies wilt behouden met clients en bronnen die icon nog niet ondersteunen, geeft u zowel icon als iconUrl op. Visual Studio biedt ondersteuning icon voor pakketten die afkomstig zijn van een bron op basis van mappen.

Readme

Ondersteund met NuGet 5.10.0 preview 2 en hoger

Wanneer u een leesmij-bestand inpakt, moet u het element gebruiken om het readme pakketpad op te geven ten opzichte van de hoofdmap van het pakket. Daarnaast moet u ervoor zorgen dat het bestand is opgenomen in het pakket. Ondersteunde bestandsindelingen bevatten alleen Markdown (.md).

U voegt bijvoorbeeld het volgende toe aan uw nuspec om een leesmij-bestand in te pakken met uw project:

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

Voor het equivalent van MSBuild bekijkt u het inpakken van een leesmij-bestand.

requireLicenseAcceptance

Een Booleaanse waarde die aangeeft of de client de consument moet vragen de pakketlicentie te accepteren voordat het pakket wordt geïnstalleerd.

developmentDependency

(2,8+) Een Booleaanse waarde die aangeeft of het pakket wordt gemarkeerd als een afhankelijkheid met alleen ontwikkeling, waardoor het pakket niet kan worden opgenomen als een afhankelijkheid in andere pakketten. Met PackageReference (NuGet 4.8+) betekent deze vlag ook dat compileertijdassets worden uitgesloten van compilatie. Zie DevelopmentDependency-ondersteuning voor PackageReference

summary

Belangrijk

summary wordt afgeschaft. Gebruik in plaats daarvan description.

Een korte beschrijving van het pakket voor weergave van de gebruikersinterface. Als u dit weglaat, wordt er een afgekapte versie van description gebruikt.

Wanneer u een pakket uploadt naar nuget.org, is het summary veld beperkt tot 4000 tekens.

releaseNotes

(1,5+) Een beschrijving van de wijzigingen die in deze versie van het pakket zijn aangebracht, die vaak worden gebruikt in de gebruikersinterface, zoals het tabblad Updates van Visual Studio Package Manager in plaats van de pakketbeschrijving.

Wanneer u een pakket uploadt naar nuget.org, is het releaseNotes veld beperkt tot 35.000 tekens.

(1,5+) Copyrightgegevens voor het pakket.

Wanneer u een pakket uploadt naar nuget.org, is het copyright veld beperkt tot 4000 tekens.

language

De landinstellings-id voor het pakket. Zie Gelokaliseerde pakketten maken.

tags

Een door spaties gescheiden lijst met tags en trefwoorden waarmee het pakket wordt beschreven en de vindbaarheid van pakketten wordt beschreven door middel van zoeken en filteren.

Wanneer u een pakket uploadt naar nuget.org, is het tags veld beperkt tot 4000 tekens.

Bruikbaar

(3.3+) Alleen voor intern NuGet-gebruik.

bewaarplaats

Metagegevens van opslagplaatsen, bestaande uit vier optionele kenmerken: type en url(4.0+) en branch (commit4,6+). Met deze kenmerken kunt u de .nupkg map toewijzen aan de opslagplaats die deze heeft gebouwd, met het potentieel om zo gedetailleerd mogelijk te worden als de naam van de afzonderlijke vertakking en/of sha-1-hash die het pakket heeft gebouwd. Dit moet een openbaar beschikbare URL zijn die rechtstreeks kan worden aangeroepen door een versiebeheersoftware. Het mag geen HTML-pagina zijn, omdat dit is bedoeld voor de computer. Als u een koppeling naar de projectpagina wilt maken, gebruikt u in plaats daarvan het projectUrl veld.

Voorbeeld:

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

Wanneer u een pakket uploadt naar nuget.org, is het type kenmerk beperkt tot 100 tekens en is het url kenmerk beperkt tot 4000 tekens.

title

Een mensvriendelijke titel van het pakket dat in sommige ui-weergaven kan worden gebruikt. (nuget.org en Package Manager in Visual Studio geven geen titel weer)

Wanneer u een pakket uploadt naar nuget.org, is het title veld beperkt tot 256 tekens, maar wordt het niet gebruikt voor weergavedoeleinden.

Verzamelingselementen

packageTypes

(3,5+) Een verzameling van nul of meer <packageType> elementen die het type van het pakket aangeven, indien anders dan een traditioneel afhankelijkheidspakket. Elk packageType heeft kenmerken van de naam en versie. Zie Een pakkettype instellen.

afhankelijkheden

Een verzameling van nul of meer <dependency> elementen die de afhankelijkheden voor het pakket opgeven. Elke afhankelijkheid heeft kenmerken van id, versie, include (3.x+) en exclude (3.x+). Zie de onderstaande afhankelijkheden .

frameworkAssemblies

(1,2+) Een verzameling van nul of meer <frameworkAssembly> elementen die .NET Framework-assemblyverwijzingen identificeren die voor dit pakket nodig zijn, waardoor verwijzingen worden toegevoegd aan projecten die het pakket gebruiken. Elk frameworkAssembly heeft assemblyName - en targetFramework-kenmerken . Zie Het opgeven van framework assembly verwijzingen GAC hieronder.

references

(1,5+) Een verzameling van nul of meer <reference> elementen die assembly's benoemen in de map van lib het pakket die als projectverwijzingen worden toegevoegd. Elke verwijzing heeft een bestandskenmerk . <references> kan ook een <group> element met een targetFramework-kenmerk bevatten dat vervolgens elementen bevat <reference> . Als u dit weglaat, worden alle verwijzingen opgenomen lib . Zie Hieronder expliciete assemblyverwijzingen opgeven .

contentFiles

(3.3+) Een verzameling <files> elementen die inhoudsbestanden identificeren die moeten worden opgenomen in het verbruikende project. Deze bestanden worden opgegeven met een set kenmerken die beschrijven hoe ze moeten worden gebruikt in het projectsysteem. Zie Bestanden opgeven die in het onderstaande pakket moeten worden opgenomen .

files

Het <package> knooppunt kan een <files> knooppunt bevatten als een knooppunt op hetzelfde niveau <metadata>en een <contentFiles> onderliggend <metadata>knooppunt om op te geven welke assembly- en inhoudsbestanden in het pakket moeten worden opgenomen. Zie Assemblybestanden opnemen en Inhoudsbestanden later in dit onderwerp opnemen voor meer informatie.

metagegevenskenmerken

minClientVersion

Hiermee geeft u de minimale versie van de NuGet-client op die dit pakket kan installeren, afgedwongen door nuget.exe en Visual Studio Package Manager. Dit wordt gebruikt wanneer het pakket afhankelijk is van specifieke functies van het .nuspec bestand dat is toegevoegd in een bepaalde versie van de NuGet-client. Een pakket met het developmentDependency kenmerk moet bijvoorbeeld '2.8' voor minClientVersionopgeven. Op dezelfde manier moet een pakket met behulp van het contentFiles element (zie de volgende sectie) zijn ingesteld minClientVersion op '3.3'. Houd er ook rekening mee dat omdat NuGet-clients vóór 2.5 deze vlag niet herkennen, ze altijd weigeren het pakket te installeren, ongeacht wat minClientVersion het bevat.

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

Vervangingstokens

Bij het maken van een pakket vervangt de nuget pack opdracht tokens met $-scheidingstekens in de .nuspec bestanden <metadata> en <files> knooppunten door waarden die afkomstig zijn van een projectbestand of de schakeloptie van -properties de pack opdracht.

Op de opdrachtregel geeft u tokenwaarden op met nuget pack -properties <name>=<value>;<name>=<value>. U kunt bijvoorbeeld een token zoals $owners$ en $desc$ in de .nuspec token gebruiken en de waarden op het tijdstip van de verpakking als volgt opgeven:

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

Als u waarden uit een project wilt gebruiken, geeft u de tokens op die worden beschreven in de onderstaande tabel (AssemblyInfo verwijst naar het bestand in Properties bijvoorbeeld AssemblyInfo.cs of AssemblyInfo.vb).

Als u deze tokens wilt gebruiken, voert nuget pack u het uit met het projectbestand in plaats van alleen de .nuspec. Wanneer u bijvoorbeeld de volgende opdracht gebruikt, worden de $id$ en $version$ tokens in een .nuspec bestand vervangen door de waarden en AssemblyVersion waarden van AssemblyName het project:

nuget pack MyProject.csproj

Wanneer u een project hebt, maakt u meestal de .nuspec eerste keer dat nuget spec MyProject.csproj u deze standaardtokens automatisch gebruikt. Als een project echter geen waarden voor vereiste .nuspec elementen bevat, mislukt het nuget pack . Als u projectwaarden wijzigt, moet u bovendien opnieuw bouwen voordat u het pakket maakt; Dit kan handig worden gedaan met de schakeloptie van build de packopdracht.

Met uitzondering van $configuration$, waarden in het project worden gebruikt in voorkeur voor elke toegewezen aan hetzelfde token op de opdrachtregel.

Teken Waardebron Waarde
$id$ Projectbestand AssemblyName (titel) uit het projectbestand
$version$ AssemblyInfo AssemblyInformationalVersion indien aanwezig, anders AssemblyVersion
$author$ AssemblyInfo AssemblyCompany
$title$ AssemblyInfo AssemblyTitle
$description$ AssemblyInfo AssemblyDescription
$copyright$ AssemblyInfo AssemblyCopyright
$configuration$ Assembly-DLL De configuratie die wordt gebruikt voor het bouwen van de assembly, standaard ingesteld op Foutopsporing. Als u een pakket wilt maken met behulp van een releaseconfiguratie, gebruikt -properties Configuration=Release u altijd op de opdrachtregel.

Tokens kunnen ook worden gebruikt om paden op te lossen wanneer u assemblybestanden en inhoudsbestanden opneemt. De tokens hebben dezelfde namen als de MSBuild-eigenschappen, waardoor het mogelijk is om bestanden te selecteren die moeten worden opgenomen, afhankelijk van de huidige buildconfiguratie. Als u bijvoorbeeld de volgende tokens in het .nuspec bestand gebruikt:

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

En u bouwt een assembly waarvan AssemblyNameLoggingLibrary de Release configuratie in MSBuild is, de resulterende regels in het .nuspec bestand in het pakket is als volgt:

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

Het element Afhankelijkheden

Het <dependencies> element binnen <metadata> bevat een willekeurig aantal <dependency> elementen waarmee andere pakketten worden geïdentificeerd waarvan het pakket op het hoogste niveau afhankelijk is. De kenmerken voor elk <dependency> zijn als volgt:

Attribute Description
id (Vereist) De pakket-id van de afhankelijkheid, zoals EntityFramework en NUnit. Dit is de naam van het pakket nuget.org wordt weergegeven op een pakketpagina.
version (Vereist) Het bereik van versies dat acceptabel is als een afhankelijkheid. Zie Pakketversiebeheer voor de exacte syntaxis. Zwevende versies worden niet ondersteund.
include Een door komma's gescheiden lijst met labels voor opnemen/uitsluiten (zie hieronder) die aangeven welke afhankelijkheid moet worden opgenomen in het uiteindelijke pakket. De standaardwaarde is all.
exclude Een door komma's gescheiden lijst met labels voor opnemen/uitsluiten (zie hieronder) die aangeven welke afhankelijkheid moet worden uitgesloten in het uiteindelijke pakket. De standaardwaarde is build,analyzers die te veel kan worden geschreven. Maar content/ ContentFiles worden ook impliciet uitgesloten in het uiteindelijke pakket dat niet te veel kan worden geschreven. Tags die zijn opgegeven met exclude voorrang hebben op de tags die zijn opgegeven met include. include="runtime, compile" exclude="compile" is bijvoorbeeld hetzelfde als include="runtime".

Wanneer u een pakket uploadt naar nuget.org, is het kenmerk van id elke afhankelijkheid beperkt tot 128 tekens en is het version kenmerk beperkt tot 256 tekens.

Tag opnemen/uitsluiten Betrokken mappen van het doel
contentFiles Content
runtime Runtime, resources en FrameworkAssemblies
compile Lib
build build (MSBuild props en doelen)
inheems inheems
none Geen mappen
all Alle mappen

De volgende regels geven bijvoorbeeld afhankelijkheden aan van PackageA versie 1.1.0 of hoger en PackageB versie 1.x.

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

De volgende regels geven afhankelijkheden van dezelfde pakketten aan, maar geef op dat de contentFiles en mappen van PackageA en alles behalve de native en compile mappen van PackageBbuild "

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

Belangrijk

Wanneer u een .nuspec project maakt met behulp van nuget spec, worden afhankelijkheden in dat project niet automatisch opgenomen in het resulterende .nuspec bestand. Gebruik in plaats daarvan nuget pack myproject.csprojhet .nuspec-bestand in het gegenereerde .nupkg-bestand . Deze .nuspec bevat de afhankelijkheden.

Afhankelijkheidsgroepen

Versie 2.0+

Als alternatief voor één platte lijst kunnen afhankelijkheden worden opgegeven volgens het frameworkprofiel van het doelproject met behulp van <group> elementen binnen <dependencies>.

Elke groep heeft een kenmerk met de naam targetFramework en bevat nul of meer <dependency> elementen. Deze afhankelijkheden worden samen geïnstalleerd wanneer het doelframework compatibel is met het frameworkprofiel van het project.

Het <group> element zonder kenmerk targetFramework wordt gebruikt als de standaard- of terugvallijst met afhankelijkheden. Zie Doelframeworks voor de exacte framework-id's.

Belangrijk

De groepsindeling kan niet worden gemengd met een platte lijst.

Opmerking

De indeling van Target Framework Moniker (TFM) die in lib/ref de map wordt gebruikt, verschilt in vergelijking met de TFM die wordt gebruikt in dependency groups. Als de doelframeworks die zijn gedeclareerd in de dependencies group map van .nuspec het lib/ref bestand, geen exacte overeenkomsten hebben, pack zal de opdracht NuGet-waarschuwing NU5128 genereren.

In het volgende voorbeeld ziet u verschillende variaties van het <group> element:

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

Expliciete assemblyverwijzingen

Het <references> element wordt door projecten packages.config gebruikt om expliciet de assembly's op te geven waarnaar het doelproject moet verwijzen wanneer het pakket wordt gebruikt. Expliciete verwijzingen worden doorgaans gebruikt voor assembly's met alleen ontwerptijd. Zie de pagina over het selecteren van assembly's waarnaar wordt verwezen door projecten voor meer informatie.

Met het volgende <references> element wordt bijvoorbeeld NuGet geïnstrueerd om alleen xunit.dll verwijzingen toe te voegen aan en xunit.extensions.dll zelfs als er extra assembly's in het pakket zijn:

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

Referentiegroepen

Als alternatief voor één platte lijst kunnen verwijzingen worden opgegeven volgens het frameworkprofiel van het doelproject met behulp van <group> elementen binnen <references>.

Elke groep heeft een kenmerk met de naam targetFramework en bevat nul of meer <reference> elementen. Deze verwijzingen worden toegevoegd aan een project wanneer het doelframework compatibel is met het frameworkprofiel van het project.

Het <group> element zonder kenmerk targetFramework wordt gebruikt als de standaard- of terugvallijst met verwijzingen. Zie Doelframeworks voor de exacte framework-id's.

Belangrijk

De groepsindeling kan niet worden gemengd met een platte lijst.

In het volgende voorbeeld ziet u verschillende variaties van het <group> element:

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

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

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

Frameworkassemblyverwijzingen

Frameworkassembly's zijn assembly's die deel uitmaken van het .NET Framework en die zich al in de algemene assemblycache (GAC) voor een bepaalde computer bevinden. Door deze assembly's in het <frameworkAssemblies> element te identificeren, kan een pakket ervoor zorgen dat de vereiste verwijzingen worden toegevoegd aan een project in het geval dat het project nog geen dergelijke verwijzingen heeft. Dergelijke assembly's zijn natuurlijk niet rechtstreeks in een pakket opgenomen.

Het <frameworkAssemblies> element bevat nul of meer <frameworkAssembly> elementen, die elk de volgende kenmerken specificeert:

Attribute Description
assemblyName (Vereist) De volledig gekwalificeerde assemblynaam.
targetFramework (Optioneel) Hiermee geeft u het doelframework waarop deze verwijzing van toepassing is. Als u dit weglaat, geeft u aan dat de verwijzing van toepassing is op alle frameworks. Zie Doelframeworks voor de exacte framework-id's.

In het volgende voorbeeld ziet u een verwijzing naar System.Net alle doelframeworks en alleen naar System.ServiceModel .NET Framework 4.0:

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

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

Assemblybestanden opnemen

Als u de conventies volgt die worden beschreven in Een pakket maken, hoeft u niet expliciet een lijst met bestanden in het .nuspec bestand op te geven. Met nuget pack de opdracht worden automatisch de benodigde bestanden opgehaald.

Belangrijk

Wanneer een pakket in een project wordt geïnstalleerd, voegt NuGet automatisch assemblyverwijzingen toe aan de DLL's van het pakket, met uitzondering van de dll's die een naam .resources.dll hebben, omdat wordt aangenomen dat ze gelokaliseerde satellietassembly's zijn. Vermijd daarom het gebruik .resources.dll van bestanden die anders essentiële pakketcode bevatten.

Als u dit automatische gedrag wilt omzeilen en expliciet wilt bepalen welke bestanden in een pakket zijn opgenomen, plaatst u een <files> element als een onderliggend element <package> van (en een hetzelfde niveau) <metadata>waarmee elk bestand met een afzonderlijk <file> element wordt geïdentificeerd. Voorbeeld:

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

Met NuGet 2.x en eerder en projecten die worden packages.configgebruikt, wordt het <files> element ook gebruikt om onveranderbare inhoudsbestanden op te nemen wanneer een pakket wordt geïnstalleerd. Met NuGet 3.3+ en projecten PackageReference wordt het <contentFiles> element gebruikt. Zie Inclusief inhoudsbestanden hieronder voor meer informatie.

Kenmerken van bestandselementen

Elk <file> element geeft de volgende kenmerken op:

Attribute Description
Src De locatie van het bestand of de bestanden die moeten worden opgenomen, afhankelijk van uitsluitingen die zijn opgegeven door het exclude kenmerk. Het pad is relatief ten opzichte van het .nuspec bestand, tenzij er een absoluut pad is opgegeven. Het jokerteken * is toegestaan en het dubbele jokerteken ** impliceert een recursieve mapzoekopdracht.
doeldoel Het relatieve pad naar de map in het pakket waarin de bronbestanden worden geplaatst, die moeten beginnen met lib, contentof buildtools. Zie Een .nuspec maken op basis van een op conventie gebaseerde werkmap.
Uitsluiten Een door puntkomma's gescheiden lijst met bestanden of bestandspatronen die moeten worden uitgesloten van de src locatie. Het jokerteken * is toegestaan en het dubbele jokerteken ** impliceert een recursieve mapzoekopdracht.

Voorbeelden

Eén assembly

Source file:
    library.dll

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

Packaged result:
    lib\library.dll

Eén assembly specifiek voor een doelframework

Source file:
    library.dll

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

Packaged result:
    lib\net40\library.dll

Set DLL's met behulp van een jokerteken

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's voor verschillende frameworks

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

Bestanden uitsluiten

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)

Inhoudsbestanden opnemen

Inhoudsbestanden zijn onveranderbare bestanden die een pakket in een project moet opnemen. Onveranderbaar zijn, zijn ze niet bedoeld om te worden gewijzigd door het verbruikende project. Voorbeelden van inhoudsbestanden zijn:

  • Afbeeldingen die zijn ingesloten als resources
  • Bronbestanden die al zijn gecompileerd
  • Scripts die moeten worden opgenomen in de build-uitvoer van het project
  • Configuratiebestanden voor het pakket dat moet worden opgenomen in het project, maar waarvoor geen projectspecifieke wijzigingen nodig zijn

Inhoudsbestanden worden opgenomen in een pakket met behulp van het <files> element, waarbij de content map in het target kenmerk wordt opgegeven. Dergelijke bestanden worden echter genegeerd wanneer het pakket wordt geïnstalleerd in een project met behulp van PackageReference, dat in plaats daarvan het <contentFiles> element gebruikt.

Voor maximale compatibiliteit met het verbruiken van projecten geeft een pakket idealiter de inhoudsbestanden in beide elementen op.

Het bestandselement voor inhoudsbestanden gebruiken

Voor inhoudsbestanden gebruikt u gewoon dezelfde indeling als voor assemblybestanden, maar geeft u content op als de basismap in het target kenmerk, zoals wordt weergegeven in de volgende voorbeelden.

Basisinhoudsbestanden

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

Inhoudsbestanden met mapstructuur

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

Inhoudsbestand dat specifiek is voor een doelframework

Source file:
    css\cool\style.css

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

Packaged result:
    content\style.css

Inhoudsbestand gekopieerd naar een map met punt in naam

In dit geval ziet NuGet dat de extensie niet overeenkomt met de extensie target in src en behandelt dat deel van de naam target dus als een map:

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

Inhoudsbestanden zonder extensies

Als u bestanden zonder extensie wilt opnemen, gebruikt u de * of ** jokertekens:

Source file:
    flags\installed

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

Packaged result:
    flags\installed

Inhoudsbestanden met diep pad en diep doel

Omdat de bestandsextensies van de bron en het doel overeenkomen, gaat NuGet ervan uit dat het doel een bestandsnaam is en geen map:

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

De naam van een inhoudsbestand in het pakket wijzigen

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

Bestanden uitsluiten

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)

Het element contentFiles gebruiken voor inhoudsbestanden

NuGet 4.0+ met PackageReference

Standaard plaatst een pakket inhoud in een contentFiles map (zie hieronder) en nuget pack bevat alle bestanden in die map met behulp van standaardkenmerken. In dit geval hoeft u helemaal geen knooppunt op .nuspec te nemencontentFiles.

Als u wilt bepalen welke bestanden worden opgenomen, geeft het <contentFiles> element een verzameling <files> elementen op waarmee de exacte bestanden worden geïdentificeerd.

Deze bestanden worden opgegeven met een set kenmerken die beschrijven hoe ze moeten worden gebruikt in het projectsysteem:

Attribute Description
omvatten (Vereist) De locatie van het bestand of de bestanden die moeten worden opgenomen, afhankelijk van uitsluitingen die zijn opgegeven door het exclude kenmerk. Het pad is relatief ten opzichte van de contentFiles map, tenzij er een absoluut pad is opgegeven. Het jokerteken * is toegestaan en het dubbele jokerteken ** impliceert een recursieve mapzoekopdracht.
Uitsluiten Een door puntkomma's gescheiden lijst met bestanden of bestandspatronen die moeten worden uitgesloten van de src locatie. Het jokerteken * is toegestaan en het dubbele jokerteken ** impliceert een recursieve mapzoekopdracht.
buildAction De buildactie die moet worden toegewezen aan het inhoudsitem voor MSBuild, zoals Content, NoneEmbedded Resource, Compile, , enzovoort. De standaardwaarde is Compile.
copyToOutput Een Booleaanse waarde die aangeeft of inhoudsitems moeten worden gekopieerd naar de uitvoermap van de build (of publiceren). De standaardwaarde is onwaar.
afvlakken Een Booleaanse waarde die aangeeft of inhoudsitems moeten worden gekopieerd naar één map in de build-uitvoer (true) of om de mapstructuur in het pakket (onwaar) te behouden. Deze vlag werkt alleen wanneer de copyToOutput-vlag is ingesteld op true. De standaardwaarde is onwaar.

Bij het installeren van een pakket past NuGet de onderliggende elementen van <contentFiles> van boven naar beneden toe. Als meerdere vermeldingen overeenkomen met hetzelfde bestand, worden alle vermeldingen toegepast. De bovenste vermelding overschrijft de lagere vermeldingen als er een conflict is voor hetzelfde kenmerk.

Pakketmapstructuur

Het pakketproject moet inhoud structuren met behulp van het volgende patroon:

/contentFiles/{codeLanguage}/{TxM}/{any?}
  • codeLanguages kan het equivalent van cseen gegeven zijn, vb, , fsof anyhet kleine lettersequivalent van een gegeven $(ProjectLanguage)
  • TxM is een juridisch doelframework dat NuGet ondersteunt (zie Doelframeworks).
  • Elke mapstructuur kan worden toegevoegd aan het einde van deze syntaxis.

Voorbeeld:

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

Lege mappen kunnen worden gebruikt _._ om af te zien van het leveren van inhoud voor bepaalde combinaties van taal en TxM, bijvoorbeeld:

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

Voorbeeld van de sectie 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>

Framework-referentiegroepen

Alleen versie 5.1+ wih PackageReference

Frameworkverwijzingen zijn een .NET Core-concept dat gedeelde frameworks vertegenwoordigt, zoals WPF of Windows Forms. Door een gedeeld framework op te geven, zorgt het pakket ervoor dat alle frameworkafhankelijkheden ervan zijn opgenomen in het verwijzende project.

Elk <group> element vereist een targetFramework kenmerk en nul of meer <frameworkReference> elementen.

In het volgende voorbeeld ziet u een nuspec die is gegenereerd voor een .NET Core WPF-project. Houd er rekening mee dat handcreatie nuspecs die frameworkverwijzingen bevatten, niet wordt aanbevolen. Overweeg in plaats daarvan het doelenpakket te gebruiken, waardoor ze automatisch worden afgeleid van het project.

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

Voorbeeld van nuspec-bestanden

Een eenvoudige .nuspec die geen afhankelijkheden of bestanden opgeeft

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

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

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

Een .nuspec met frameworkassembly's

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

In dit voorbeeld zijn de volgende geïnstalleerd voor specifieke projectdoelen:

  • . NET4 ->System.Web, System.Net
  • . NET4-clientprofiel ->System.Net
  • Silverlight 3 ->System.Json
  • WindowsPhone ->Microsoft.Devices.Sensors
  • Last updated on