Een pakket maken met behulp van de nuget.exe CLI

Ongeacht wat uw pakket doet of welke code het bevat, gebruikt u een van de CLI-hulpprogramma's of nuget.exedotnet.exe, om die functionaliteit te verpakken in een onderdeel dat kan worden gedeeld en gebruikt door een willekeurig aantal andere ontwikkelaars. Zie NuGet-clienthulpprogramma's installeren om NuGet CLI-hulpprogramma's te verkrijgen. Visual Studio bevat niet automatisch een CLI-hulpprogramma.

• Voor niet-SDK-projecten, meestal .NET Framework-projecten, volgt u de stappen die in dit artikel worden beschreven om een pakket te maken. Zie nuget.exe voor stapsgewijze instructies met Behulp van Visual Studio en de CLI.

• Zie Een NuGet-pakket maken met behulp van de dotnet CLI voor .NET Core- en .NET Standard-projecten die gebruikmaken van de SDK-indeling en eventuele andere SDK-projecten.

• Gebruik packages.config voor projecten die zijn gemigreerd van naar PackageReference.

Technisch gesproken is een NuGet-pakket slechts een ZIP-bestand dat is hernoemd met de extensie en waarvan de .nupkg inhoud overeenkomt met bepaalde conventies. In dit onderwerp wordt het gedetailleerde proces beschreven voor het maken van een pakket dat voldoet aan deze conventies.

Pakketten beginnen met de gecompileerde code (assembly's), symbolen en/of andere bestanden die u als pakket wilt leveren (zie Overzicht en werkstroom). Dit proces is onafhankelijk van het compileren of anderszins genereren van de bestanden die naar het pakket gaan, hoewel u kunt tekenen uit informatie in een projectbestand om de gecompileerde assembly's en pakketten gesynchroniseerd te houden.

Bepaal welke assemblages moeten worden gepackaged

De meeste algemene pakketten bevatten een of meer assembly's die andere ontwikkelaars in hun eigen projecten kunnen gebruiken.

• Over het algemeen is het raadzaam om één assembly per NuGet-pakket te hebben, mits elke assembly onafhankelijk nuttig is. Als u bijvoorbeeld een Utilities.dll hebt dat afhankelijk is van Parser.dll, en Parser.dll op zichzelf nuttig is, maak dan één pakket voor elk. Hierdoor kunnen ontwikkelaars Parser.dll onafhankelijk van Utilities.dll.

• Als uw bibliotheek bestaat uit meerdere assembly's die niet onafhankelijk nuttig zijn, kunt u ze in één pakket combineren. Als het vorige voorbeeld Parser.dll code bevat die alleen wordt gebruikt door Utilities.dll, is het prima om in hetzelfde pakket te blijven Parser.dll .

• En als Utilities.dll afhankelijk is van Utilities.resources.dll, waarbij de laatste op zichzelf niet nuttig is, plaats dan beide in hetzelfde pakket.

Resources zijn in feite een speciaal geval. 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 met de naam .resources.dll , omdat wordt aangenomen dat ze gelokaliseerde satellietassembly's zijn (zie Gelokaliseerde pakketten maken). Vermijd daarom het gebruik .resources.dll van bestanden die anders essentiële pakketcode bevatten.

Als uw bibliotheek COM-interopsassembly's bevat, volg dan de richtlijnen in Pakketten maken met COM-interopsassembly's.

De rol en structuur van het .nuspec-bestand

Zodra u weet welke bestanden u wilt verpakken, maakt u in de volgende stap een pakketmanifest in een .nuspec XML-bestand.

Het manifest:

1. Beschrijft de inhoud van het pakket en is zelf opgenomen in het pakket.
2. Beheert zowel de creatie van het pakket als instrueert NuGet voor het installeren van het pakket in een project. Het manifest identificeert bijvoorbeeld andere pakketafhankelijkheden, zodat NuGet deze afhankelijkheden ook kan installeren wanneer het hoofdpakket is geïnstalleerd.
3. Bevat zowel vereiste als optionele eigenschappen, zoals hieronder wordt beschreven. Zie de verwijzing .nuspec voor meer informatie, inclusief andere eigenschappen die hier niet worden vermeld.

Vereiste eigenschappen:

• De pakket-id, die uniek moet zijn in de galerie die als host fungeert voor het pakket.
• Een specifiek versienummer in de vorm Major.Minor.Patch[-Suffix] waarbij -Suffixpre-release versies identificeert
• De pakkettitel zoals deze moet worden weergegeven op de host (zoals nuget.org)
• Informatie over auteur en eigenaar.
• Een lange beschrijving van het pakket.

Algemene optionele eigenschappen:

• Opmerkingen bij de uitgave
• Copyright-informatie
• Een korte beschrijving voor de gebruikersinterface van Package Manager in Visual Studio
• Een locale-ID
• Project-URL
• Licentie als een expressie of bestand (licenseUrl wordt afgeschaft, gebruik license in plaats daarvan het nuspec-metagegevenselement )
• Een pictogrambestand (iconUrl is afgeschaft, gebruikt icon in plaats daarvan het element nuspec metadata )
• Lijsten met afhankelijkheden en verwijzingen
• Tags die helpen bij zoekopdrachten in de galerie

Hier volgt een typisch (maar fictief) .nuspec bestand, met opmerkingen die de eigenschappen beschrijven:

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <!-- Identifier that must be unique within the hosting gallery -->
        <id>Contoso.Utility.UsefulStuff</id>

        <!-- Package version number that is used when resolving dependencies -->
        <version>1.8.3</version>

        <!-- Authors contain text that appears directly on the gallery -->
        <authors>Dejana Tesic, Rajeev Dey</authors>

        <!-- 
            Owners are typically nuget.org identities that allow gallery
            users to easily find other packages by the same owners.  
        -->
        <owners>dejanatc, rjdey</owners>
        
         <!-- Project URL provides a link for the gallery -->
        <projectUrl>http://github.com/contoso/UsefulStuff</projectUrl>

         <!-- License information is displayed on the gallery -->
        <license type="expression">Apache-2.0</license>
        

        <!-- Icon is used in Visual Studio's package manager UI -->
        <icon>icon.png</icon>

        <!-- 
            If true, this value prompts the user to accept the license when
            installing the package. 
        -->
        <requireLicenseAcceptance>false</requireLicenseAcceptance>

        <!-- Any details about this particular release -->
        <releaseNotes>Bug fixes and performance improvements</releaseNotes>

        <!-- 
            The description can be used in package manager UI. Note that the
            nuget.org gallery uses information you add in the portal. 
        -->
        <description>Core utility functions for web applications</description>

        <!-- Copyright information -->
        <copyright>Copyright ©2016 Contoso Corporation</copyright>

        <!-- Tags appear in the gallery and can be used for tag searches -->
        <tags>web utility http json url parsing</tags>

        <!-- Dependencies are automatically installed when the package is installed -->
        <dependencies>
            <dependency id="Newtonsoft.Json" version="9.0" />
        </dependencies>
    </metadata>

    <!-- A readme.txt to display when the package is installed -->
    <files>
        <file src="readme.txt" target="" />
        <file src="icon.png" target="" />
    </files>
</package>

Zie packages.config en pakketversiebeheer voor meer informatie over het declareren van afhankelijkheden en het opgeven van versienummers. Het is ook mogelijk om assets uit afhankelijkheden rechtstreeks in het pakket weer te geven door gebruik te maken van de include en exclude attributen van het dependency element. Zie .nuspec Reference - Afhankelijkheden.

Omdat het manifest is opgenomen in het pakket dat ermee is gemaakt, kunt u een willekeurig aantal extra voorbeelden vinden door bestaande pakketten te onderzoeken. Een goede bron is de map global-packages op uw computer, waarvan de locatie wordt geretourneerd door de volgende opdracht:

nuget locals -list global-packages

Ga naar de map package\version, kopieer het .nupkg bestand naar een .zip bestand, open dat .zip bestand en bekijk het .nuspec erin.

Het .nuspec-bestand maken

Het maken van een volledig manifest begint meestal met een basisbestand .nuspec dat op een van de volgende manieren wordt gegenereerd:

• Een op conventie gebaseerde werkmap
• Een assembly-DLL
• Een Visual Studio-project
• Nieuw bestand met standaardwaarden

Vervolgens bewerkt u het bestand handmatig om de exacte inhoud te specificeren die u in het uiteindelijke pakket wilt opnemen.

Vanuit een conventiegebaseerde werkmap

Omdat een NuGet-pakket slechts een ZIP-bestand is dat is hernoemd met de .nupkg extensie, is het vaak het eenvoudigst om de gewenste mapstructuur te maken op uw lokale bestandssysteem en vervolgens het .nuspec bestand rechtstreeks vanuit die structuur te maken. Met de nuget pack opdracht worden vervolgens automatisch alle bestanden in die mapstructuur toegevoegd (met uitzondering van mappen die beginnen met ., zodat u privébestanden in dezelfde structuur kunt bewaren).

Het voordeel van deze aanpak is dat u niet hoeft op te geven in het manifest welke bestanden u in het pakket wilt opnemen (zoals verderop in dit onderwerp wordt uitgelegd). U kunt gewoon uw buildproces de exacte mapstructuur laten produceren die in het pakket wordt geplaatst en u kunt eenvoudig andere bestanden opnemen die mogelijk geen deel uitmaken van een project, anders:

• Inhoud en broncode die in het doelproject moeten worden geïnjecteerd.
• PowerShell-scripten
• Transformaties naar bestaande configuratie- en broncodebestanden in een project.

De mappenconventies zijn als volgt:

Omdat uw mapstructuur een willekeurig aantal assembly's voor een willekeurig aantal doelframeworks kan bevatten, is deze methode nodig bij het maken van pakketten die ondersteuning bieden voor meerdere frameworks.

Als u de gewenste mapstructuur hebt, voert u in ieder geval de volgende opdracht uit in die map om het .nuspec bestand te maken:

nuget spec

Opnieuw bevat de gegenereerde geen expliciete .nuspec verwijzingen naar bestanden in de mapstructuur. NuGet bevat automatisch alle bestanden wanneer het pakket wordt gemaakt. U moet de tijdelijke aanduidingen voor waarden in andere delen van het manifest echter nog bewerken.

Vanuit een assembly-DLL

In het eenvoudige geval van het maken van een pakket vanuit een assembly kunt u een .nuspec bestand genereren op basis van de metagegevens in de assembly met behulp van de volgende opdracht:

nuget spec <assembly-name>.dll

Met dit formulier worden enkele plaatsaanduidingen in het manifest vervangen door specifieke waarden uit de assembly. De eigenschap is bijvoorbeeld ingesteld op <id> de assemblynaam, en <version> is ingesteld op de assemblyversie. Andere eigenschappen in het manifest hebben echter geen overeenkomende waarden in de assembly en bevatten dus nog steeds tijdelijke aanduidingen.

Vanuit een Visual Studio-project

Het maken van een .nuspec-bestand vanuit een .csproj- of .vbproj-bestand is handig omdat andere pakketten die in dat project zijn geïnstalleerd, automatisch als afhankelijkheden worden vermeld. Gebruik gewoon de volgende opdracht in dezelfde map als het projectbestand:

# Use in a folder containing a project file <project-name>.csproj or <project-name>.vbproj
nuget spec

Het resulterende <project-name>.nuspec bestand bevat tokens die tijdens de verpakking worden vervangen door waarden uit het project, inclusief verwijzingen naar andere pakketten die al zijn geïnstalleerd.

Als u pakketafhankelijkheden hebt die moeten worden opgenomen in de .nuspec, gebruikt u nuget pack in plaats daarvan, en verkrijg het .nuspec-bestand van binnenuit het gegenereerde .nupkg-bestand. Gebruik bijvoorbeeld de volgende opdracht.

# Use in a folder containing a project file <project-name>.csproj or <project-name>.vbproj
nuget pack myproject.csproj

Een token wordt begrensd door $ symbolen aan weerszijden van het projectkenmerk. De waarde in een manifest die op deze manier wordt gegenereerd, <id> wordt bijvoorbeeld meestal als volgt weergegeven:

<id>$id$</id>

Dit token wordt vervangen door de AssemblyName waarde uit het projectbestand tijdens het inpakken. Zie de .nuspec voor de exacte toewijzing van projectwaarden aan tokens.

Met tokens hoeft u geen cruciale waarden bij te werken, zoals het versienummer in het .nuspec project wanneer u het project bijwerkt. (U kunt de tokens altijd vervangen door letterlijke waarden, indien gewenst).

Houd er rekening mee dat er verschillende extra verpakkingsopties beschikbaar zijn wanneer u vanuit een Visual Studio-project werkt, zoals beschreven in Nuget-pakket uitvoeren om het .nupkg-bestand later te genereren .

Pakketten op oplossingsniveau

Alleen NuGet 2.x. Niet beschikbaar in NuGet 3.0+.

NuGet 2.x ondersteunt het idee van een pakket op oplossingsniveau waarmee hulpprogramma's of extra opdrachten voor de Package Manager-console (de inhoud van de tools map) worden geïnstalleerd, maar geen verwijzingen, inhoud of aanpassingen worden toegevoegd aan projecten in de oplossing. Dergelijke pakketten bevatten geen bestanden in de directe lib, contentof build mappen, en geen van de afhankelijkheden hebben bestanden in hun respectieve lib, contentof build mappen.

NuGet houdt geïnstalleerde pakketten op oplossingsniveau bij in een packages.config bestand in de .nuget map in plaats van packages.config het projectbestand.

Nieuw bestand met standaardwaarden

Met de volgende opdracht maakt u een standaardmanifest met tijdelijke aanduidingen, zodat u begint met de juiste bestandsstructuur:

nuget spec [<package-name>]

Het resulterende bestand is Package.nuspecals u de pakketnaam< weglaat>. Als u een naam opgeeft zoals Contoso.Utility.UsefulStuff, is Contoso.Utility.UsefulStuff.nuspechet bestand .

Het resultaat .nuspec bevat tijdelijke aanduidingen voor waarden zoals de projectUrl. Zorg ervoor dat u het bestand bewerkt voordat u het gebruikt om het uiteindelijke .nupkg bestand te maken.

Kies een unieke pakket-id en stel het versienummer in

De pakket-id (<id> element) en het versienummer (<version> element) zijn de twee belangrijkste waarden in het manifest, omdat ze de exacte code in het pakket uniek identificeren.

Aanbevolen procedures voor de pakket-id:

• Uniekheid: de id moet uniek zijn in nuget.org of welke galerie het pakket host. Voordat u een id kiest, zoekt u in de betreffende galerie om te controleren of de naam al in gebruik is. Om conflicten te voorkomen, is het een goed patroon om uw bedrijfsnaam te gebruiken als het eerste deel van de id, zoals Contoso..
• Naamruimteachtige namen: volg een patroon dat lijkt op naamruimten in .NET, met behulp van punt notatie in plaats van afbreekstreepjes. Gebruik bijvoorbeeld Contoso.Utility.UsefulStuff in plaats Contoso-Utility-UsefulStuff van of Contoso_Utility_UsefulStuff. Consumenten vinden het ook handig wanneer de pakket-id overeenkomt met de naamruimten die in de code worden gebruikt.
• Voorbeeldpakketten: Als u een pakket met voorbeeldcode produceert dat laat zien hoe u een ander pakket gebruikt, voegt .Sample u als achtervoegsel toe aan de id, zoals in Contoso.Utility.UsefulStuff.Sample. (Het voorbeeldpakket heeft natuurlijk een afhankelijkheid van het andere pakket.) Wanneer u een voorbeeldpakket maakt, gebruikt u de op conventie gebaseerde werkmapmethode die eerder is beschreven. Rangschik in de content map de voorbeeldcode in een map met de naam \Samples\<identifier> in \Samples\Contoso.Utility.UsefulStuff.Sample.

Aanbevolen procedures voor de pakketversie:

• Stel in het algemeen de versie van het pakket in op overeenstemming met de bibliotheek, maar dit is niet strikt vereist. Dit is een eenvoudige kwestie wanneer u een pakket beperkt tot één assembly, zoals eerder beschreven in Bepalen welke assembly's moeten worden verpakt. Over het algemeen moet u er rekening mee houden dat NuGet zelf te maken heeft met pakketversies bij het oplossen van afhankelijkheden, niet met assemblyversies.
• Wanneer u een niet-standaardversieschema gebruikt, moet u rekening houden met de NuGet-versiebeheerregels, zoals uitgelegd in pakketversiebeheer.

De volgende reeks korte blogberichten zijn ook handig om inzicht te krijgen in versiebeheer:

• Deel 1: Het aanpakken van DLL-ellende
• Deel 2: Het kernalgoritmen
• Deel 3: Eenwording via bindingsomleidingen

Een leesmij-bestand en andere bestanden toevoegen

Als u rechtstreeks bestanden wilt opgeven die in het pakket moeten worden opgenomen, gebruikt u het <files> knooppunt in het .nuspec bestand, dat de tag <metadata>:

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
    <!-- ... -->
    </metadata>
    <files>
        <!-- Add a readme -->
        <file src="readme.txt" target="" />

        <!-- Add files from an arbitrary folder that's not necessarily in the project -->
        <file src="..\..\SomeRoot\**\*.*" target="" />
    </files>
</package>

Wanneer u een bestand met de naam readme.txt in de hoofdmap van het pakket opneemt, wordt in Visual Studio de inhoud van dat bestand weergegeven als tekst zonder opmaak direct na de installatie van het pakket. (Leesmijbestanden worden niet weergegeven voor pakketten die als afhankelijkheid zijn geïnstalleerd). Hier ziet u bijvoorbeeld hoe het readme-bestand voor het HtmlAgilityPack-pakket eruitziet:

MSBuild props en doelen opnemen in een pakket

In sommige gevallen wilt u misschien aangepaste builddoelen of eigenschappen toevoegen aan projecten die uw pakket gebruiken, zoals het uitvoeren van een aangepast hulpprogramma of proces tijdens de build. Meer informatie over MSBuild props en doelen vindt u in NuGet-pakketten

Maak <package_id>.targets of <package_id>.props (zoals Contoso.Utility.UsefulStuff.targets) in de buildmappen van het project.

Zorg er vervolgens voor dat u in het .nuspec bestand naar deze bestanden in het <files> knooppunt verwijst:

<?xml version="1.0"?>
<package >
    <metadata minClientVersion="2.5">
    <!-- ... -->
    </metadata>
    <files>
        <!-- Include everything in \build -->
        <file src="build\**" target="build" />

        <!-- Other files -->
        <!-- ... -->
    </files>
</package>

Wanneer pakketten worden toegevoegd aan een project, worden deze props en doelen automatisch opgenomen in NuGet.

Nuget-pack uitvoeren om het .nupkg-bestand te genereren

Wanneer u een assembly of de werkmap die op conventies is gebaseerd gebruikt, maakt u een pakket door het nuget pack bestand uit te voeren .nuspec, waarbij u <project-name> vervangt met uw specifieke bestandsnaam.

nuget pack <project-name>.nuspec

Wanneer u een Visual Studio-project gebruikt, voert u nuget pack uit met uw projectbestand, waarmee het projectbestand .nuspec automatisch wordt geladen en alle tokens daarin worden vervangen door waarden uit het projectbestand:

nuget pack <project-name>.csproj

Sluit nuget pack in alle gevallen mappen uit die beginnen met een punt, zoals .git of .hg.

NuGet geeft aan of er fouten zijn in het .nuspec bestand dat moet worden gecorrigeerd, zoals het vergeten om waarden van tijdelijke aanduidingen in het manifest te wijzigen.

Als nuget pack het lukt, hebt u een .nupkg bestand dat u kunt publiceren naar een geschikte galerie, zoals beschreven in Het publiceren van een pakket.

Aanvullende opties

U kunt verschillende opdrachtregelopties nuget pack gebruiken om bestanden uit te sluiten, het versienummer in het manifest te overschrijven en de uitvoermap te wijzigen, onder andere functies. Raadpleeg de opdrachtverwijzing voor het pakket voor een volledige lijst.

De volgende opties zijn enkele die gebruikelijk zijn voor Visual Studio-projecten:

• Projecten waarnaar wordt verwezen: als het project verwijst naar andere projecten, kunt u de projecten waarnaar wordt verwezen toevoegen als onderdeel van het pakket of als afhankelijkheden, met behulp van de -IncludeReferencedProjects optie:

  nuget pack MyProject.csproj -IncludeReferencedProjects
  

  Dit opnameproces is recursief, dus als MyProject.csproj verwijst naar projecten B en C, en deze projecten verwijzen naar D, E en F, dan worden bestanden van B, C, D, E en F in het pakket opgenomen.

  Als een project waarnaar wordt verwezen een .nuspec eigen bestand bevat, voegt NuGet dat project toe als een afhankelijkheid. U moet dat project afzonderlijk verpakken en publiceren.

• Buildconfiguratie: NuGet maakt standaard gebruik van de standaard buildconfiguratieset in het projectbestand, meestal foutopsporing. Als u bestanden uit een andere buildconfiguratie wilt inpakken, zoals Release, gebruikt u de -properties optie met de configuratie:

  nuget pack MyProject.csproj -properties Configuration=Release
  

• Symbolen: als u symbolen wilt opnemen waarmee consumenten uw pakketcode in het foutopsporingsprogramma kunnen doorlopen, gebruikt u de -Symbols optie:

  nuget pack MyProject.csproj -symbols
  

Installatie van het testpakket

Voordat u een pakket publiceert, wilt u meestal het proces van het installeren van een pakket in een project testen. De tests zorgen ervoor dat de bestanden allemaal op de juiste plaatsen in het project terechtkomen.

U kunt installaties handmatig testen in Visual Studio of op de opdrachtregel met behulp van de normale installatiestappen voor pakketten.

Voor geautomatiseerde tests is het basisproces als volgt:

1. Kopieer het .nupkg bestand naar een lokale map.
2. Voeg de map toe aan uw pakketbronnen met behulp van de nuget sources add -name <name> -source <path> opdracht (zie nuget-bronnen). Houd er rekening mee dat u deze lokale bron slechts eenmaal op een bepaalde computer hoeft in te stellen.
3. Installeer het pakket van die bron met behulp van nuget install <packageID> -source <name> waar <name> overeenkomt met de naam zoals opgegeven door nuget sources. Als u de bron opgeeft, zorgt u ervoor dat het pakket alleen vanuit die bron wordt geïnstalleerd.
4. Controleer uw bestandssysteem om te controleren of bestanden correct zijn geïnstalleerd.

Volgende stappen

Nadat u een pakket hebt gemaakt, dat een .nupkg bestand is, kunt u het publiceren naar de galerie van uw keuze, zoals beschreven in het publiceren van een pakket.

Mogelijk wilt u ook de mogelijkheden van uw pakket uitbreiden of andere scenario's ondersteunen, zoals beschreven in de volgende onderwerpen:

• Pakketversiebeheer
• Ondersteuning voor meerdere doelframeworks
• Transformaties van bron- en configuratiebestanden
• Lokalisatie
• Pre-release versies
• Pakkettype instellen
• Pakketten maken met COM-interop-assemblies

Ten slotte zijn er extra pakkettypen om rekening mee te houden:

• Systeemeigen pakketten
• Symbolenpakketten