Dela via

Skapa ett paket med hjälp av nuget.exe CLI

Oavsett vad ditt paket gör eller vilken kod det innehåller använder du något av CLI-verktygen, antingen nuget.exe eller dotnet.exe, för att paketera den funktionen i en komponent som kan delas med och användas av ett antal andra utvecklare. Information om hur du installerar NuGet CLI-verktyg finns i Installera NuGet-klientverktyg. Observera att Visual Studio inte automatiskt innehåller ett CLI-verktyg.

Tekniskt sett är ett NuGet-paket bara en ZIP-fil som har bytt namn med .nupkg tillägget och vars innehåll matchar vissa konventioner. Det här avsnittet beskriver den detaljerade processen med att skapa ett paket som uppfyller dessa konventioner.

Paketeringen börjar med den kompilerade koden (sammansättningar), symboler och/eller andra filer som du vill leverera som ett paket (se Översikt och arbetsflöde). Den här processen är oberoende av kompilering eller på annat sätt genererar de filer som går in i paketet, även om du kan hämta information i en projektfil för att hålla kompilerade sammansättningar och paket synkroniserade.

Viktigt!

Det här avsnittet gäller för icke-SDK-liknande projekt, vanligtvis andra projekt än .NET Core- och .NET Standard-projekt med Visual Studio 2017 och högre versioner och NuGet 4.0+.

Bestäm vilka samlingar som ska paketeras

De flesta allmänna paket innehåller en eller flera sammansättningar som andra utvecklare kan använda i sina egna projekt.

  • I allmänhet är det bäst att ha en sammansättning per NuGet-paket, förutsatt att varje sammansättning är oberoende användbar. Om du till exempel har en Utilities.dll som är beroende av Parser.dll, och Parser.dll är användbar på egen hand, skapa ett paket för varje. På så sätt kan utvecklare använda Parser.dll oberoende av Utilities.dll.

  • Om biblioteket består av flera sammansättningar som inte är oberoende användbara är det bra att kombinera dem i ett paket. Med hjälp av föregående exempel, om Parser.dll innehåller kod som endast används av Utilities.dll, är det bra att behålla Parser.dll i samma paket.

  • På samma sätt, om Utilities.dll beror på Utilities.resources.dll, där det senare inte är användbart på egen hand, placerar du båda i samma paket.

Resurser är i själva verket ett specialfall. När ett paket installeras i ett projekt lägger NuGet automatiskt till sammansättningsreferenser till paketets DLL:er, exklusive de som namnges .resources.dll eftersom de antas vara lokaliserade satellitsammansättningar (se Skapa lokaliserade paket). Undvik därför att använda .resources.dll filer som annars innehåller viktig paketkod.

Om biblioteket innehåller COM-interop-sammansättningar följer du ytterligare riktlinjerna i Skapa paket med COM-interop-sammansättningar.

Rollen och strukturen för .nuspec-filen

När du vet vilka filer du vill paketera skapar nästa steg ett paketmanifest i en .nuspec XML-fil.

Manifestet:

  1. Beskriver paketets innehåll och ingår i paketet.
  2. Kör både skapandet av paketet och instruerar NuGet om hur du installerar paketet i ett projekt. Manifestet identifierar till exempel andra paketberoenden så att NuGet också kan installera dessa beroenden när huvudpaketet installeras.
  3. Innehåller både obligatoriska och valfria egenskaper enligt beskrivningen nedan. Exakt information, inklusive andra egenskaper som inte nämns här, finns i .nuspec-referensen.

Nödvändiga egenskaper:

  • Paketidentifieraren, som måste vara unik i galleriet som är värd för paketet.
  • Ett specifikt versionsnummer i formatet Major.Minor.Patch[-Suffix] där -Suffix identifierar förhandsversioner
  • Paketrubriken som den ska visas på webbplatsen (till exempel nuget.org)
  • Information om författare och ägare.
  • En lång beskrivning av paketet.

Vanliga valfria egenskaper:

Följande är en typisk (men fiktiv) .nuspec fil med kommentarer som beskriver egenskaperna:

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

Mer information om hur du deklarerar beroenden och anger versionsnummer finns ipackages.config och Paketversionshantering. Det är också möjligt att direkt visa tillgångar från beroenden i paketet genom att använda attributen include och exclude på elementet dependency. Se .nuspec-referens – beroenden.

Eftersom manifestet ingår i paketet som skapats från det kan du hitta valfritt antal ytterligare exempel genom att undersöka befintliga paket. En bra källa är mappen global-packages på datorn, vars plats returneras med följande kommando:

nuget locals -list global-packages

Gå in i valfri paket\versions-mapp, kopiera den .nupkg filen till en .zip fil, öppna sedan den .zip filen och granska innehållet i den .nuspec filen.

Anmärkning

När du skapar ett .nuspec från ett Visual Studio-projekt innehåller manifestet token som ersätts med information från projektet när paketet skapas. Se Skapa .nuspec från ett Visual Studio-projekt.

Skapa .nuspec-filen

Att skapa ett fullständigt manifest börjar vanligtvis med en grundläggande .nuspec fil som genereras via någon av följande metoder:

Sedan redigerar du filen för hand så att den beskriver exakt det innehåll du vill ha i det slutliga paketet.

Viktigt!

Genererade .nuspec filer innehåller platshållare som måste ändras innan paketet skapas med nuget pack kommandot . Kommandot misslyckas om .nuspec innehåller några platshållare.

Från en konventionsbaserad arbetskatalog

Eftersom ett NuGet-paket bara är en ZIP-fil som har bytt namn med .nupkg tillägget är det ofta enklast att skapa den mappstruktur som du vill använda i det lokala filsystemet och sedan skapa filen direkt från den .nuspec strukturen. Kommandot nuget pack lägger sedan automatiskt till alla filer i den mappstrukturen (exklusive alla mappar som börjar med ., så att du kan behålla privata filer i samma struktur).

Fördelen med den här metoden är att du inte behöver ange i manifestet vilka filer du vill inkludera i paketet (som beskrivs senare i det här avsnittet). Du kan helt enkelt låta byggprocessen skapa den exakta mappstrukturen som ingår i paketet, och du kan enkelt inkludera andra filer som kanske inte ingår i ett projekt annars:

  • Innehåll och källkod som ska matas in i målprojektet.
  • PowerShell-skript
  • Transformering till befintliga konfigurations- och källkodsfiler i ett projekt.

Mappkonventionerna är följande:

Mapp Description Åtgärd vid paketinstallation
(root) Plats för readme.txt Visual Studio visar en readme.txt fil i paketroten när paketet har installerats.
lib/{tfm} Sammansättningsfiler (.dll), dokumentationsfiler (.xml) och symbolfiler (.pdb) för angiven Target Framework Moniker (TFM) Sammansättningar läggs till som referenser för kompilering och körning. .xml och .pdb kopieras till projektmappar. Se Stöd för flera målramverk för att skapa ramverksspecifika undermappar.
ref/{tfm} Sammansättningsfiler (.dll) och symbolfiler för (.pdb) den angivna Target Framework Moniker (TFM) Sammansättningar läggs bara till som referenser för kompileringstid. Därför kopieras ingenting till mappen projektlager.
körtider Arkitekturspecifik sammansättning (.dll), symbolfiler (.pdb) och interna resursfiler (.pri) Assembly-filer läggs endast till som referenser för körning; andra filer kopieras till projektmappar. Det bör alltid finnas en motsvarande (TFM) AnyCPU specifik sammansättning under /ref/{tfm} mappen för att tillhandahålla motsvarande kompileringstidssammansättning. Se Stöd för flera målramverk.
innehåll Valfria filer Innehållet kopieras till projektroten. Tänk på innehållsmappen som roten för målprogrammet som slutligen använder paketet. Om du vill att paketet ska lägga till en bild i programmets /images-mapp placerar du den i paketets mapp för innehåll/bilder .
build (3.x+) MSBuild- och .props-filer Infogas automatiskt i projektet.
buildMultiTargeting (4.0+) MSBuild .targets och .props-filer för att rikta mot flera ramverk Infogas automatiskt i projektet.
buildTransitive (5.0+) MSBuild .targets och .props filer som flödar transitivt till alla förbrukande projekt. Se funktionssidan . Infogas automatiskt i projektet.
verktyg Powershell-skript och -program som är tillgängliga från Package Manager-konsolen Mappen tools läggs endast till i PATH-miljövariabeln för Package Manager-konsolen (specifikt inte till det som angetts för MSBuild när projektet byggs).

Eftersom mappstrukturen kan innehålla valfritt antal sammansättningar för valfritt antal målramverk är den här metoden nödvändig när du skapar paket som stöder flera ramverk.

När du har önskad mappstruktur på plats kör du i alla fall följande kommando i mappen för att skapa .nuspec filen:

nuget spec

Återigen innehåller den genererade .nuspec inga explicita referenser till filer i mappstrukturen. NuGet innehåller automatiskt alla filer när paketet skapas. Du behöver dock fortfarande redigera platshållarvärden i andra delar av manifestet.

Från en assembly-DLL

I det enkla fallet med att skapa ett paket från en sammansättning kan du generera en .nuspec fil från metadata i sammansättningen med hjälp av följande kommando:

nuget spec <assembly-name>.dll

Med det här formuläret ersätts några platshållare i manifestet med specifika värden från sammansättningen. Egenskapen är till exempel <id> inställd på sammansättningsnamnet och <version> är inställd på sammansättningsversionen. Andra egenskaper i manifestet har dock inte matchande värden i sammansättningen och innehåller därför fortfarande platshållare.

Från ett Visual Studio-projekt

Det är praktiskt att skapa en .nuspec från en .csproj eller .vbproj fil eftersom paket som har installerats i projektet automatisk refereras som beroenden. Använd bara följande kommando i samma mapp som projektfilen:

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

Den resulterande <project-name>.nuspec filen innehåller token som ersätts vid paketeringstiden med värden från projektet, inklusive referenser till andra paket som redan har installerats.

Om du har paketberoenden som ska ingå i .nuspec bör du istället använda nuget pack och hämta .nuspec-filen från den genererade .nupkg-filen. Använd till exempel följande kommando.

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

En token avgränsas av $ symboler på båda sidor av projektegenskapen. Till exempel <id> visas värdet i ett manifest som genereras på det här sättet vanligtvis på följande sätt:

<id>$id$</id>

Den här token ersätts med AssemblyName värdet från projektfilen vid förpackningstillfället. Den exakta mappningen av projektvärden till .nuspec tokens finns i Ersättningstoken-referens.

Med token behöver du inte uppdatera viktiga värden som versionsnumret i .nuspec när du uppdaterar projektet. (Du kan alltid ersätta token med literalvärden om du vill).

Observera att det finns flera ytterligare paketeringsalternativ tillgängliga när du arbetar från ett Visual Studio-projekt, enligt beskrivningen i Köra nuget-paketet för att generera .nupkg-filen senare.

Paket på lösningsnivå

Endast NuGet 2.x. Inte tillgängligt i NuGet 3.0+.

NuGet 2.x har stöd för begreppet paket på lösningsnivå som installerar verktyg eller ytterligare kommandon för Package Manager-konsolen (innehållet tools i mappen), men som inte lägger till referenser, innehåll eller bygganpassningar i några projekt i lösningen. Sådana paket innehåller inga filer i dess direkta lib, content, eller build mappar, och ingen av dess beroenden har filer i sina respektive lib, contenteller build mappar.

NuGet spårar installerade paket på lösningsnivå i en packages.config fil i .nuget mappen i stället för projektets packages.config fil.

Ny fil med standardvärden

Följande kommando skapar ett standardmanifest med platshållare, vilket säkerställer att du börjar med rätt filstruktur:

nuget spec [<package-name>]

Om du utelämnar <paketnamn> är Package.nuspecden resulterande filen . Om du anger ett namn som Contoso.Utility.UsefulStuffär filen Contoso.Utility.UsefulStuff.nuspec.

Resultatet .nuspec innehåller platshållare för värden som projectUrl. Var noga med att redigera filen innan du använder den för att skapa den slutliga .nupkg filen.

Välj en unik paketidentifierare och ange versionsnumret

Paketidentifieraren (<id> elementet) och versionsnumret (<version> elementet) är de två viktigaste värdena i manifestet eftersom de unikt identifierar den exakta kod som finns i paketet.

Metodtips för paketidentifieraren:

  • Unikhet: Identifieraren måste vara unik i nuget.org eller det galleri som är värd för paketet. Innan du bestämmer dig för en identifierare söker du i det tillämpliga galleriet för att kontrollera om namnet redan används. För att undvika konflikter är ett bra mönster att använda företagets namn som den första delen av identifieraren, till exempel Contoso..
  • Namnområdesliknande namn: Följ ett mönster som liknar namnrymder i .NET, med hjälp av punkt notation i stället för bindestreck. Använd till exempel Contoso.Utility.UsefulStuff i stället Contoso-Utility-UsefulStuff för eller Contoso_Utility_UsefulStuff. Konsumenterna tycker också att det är användbart när paketidentifieraren matchar de namnområden som används i koden.
  • Exempelpaket: Om du skapar ett paket med exempelkod som visar hur du använder ett annat paket bifogar .Sample du som ett suffix till identifieraren, som i Contoso.Utility.UsefulStuff.Sample. (Exempelpaketet skulle naturligtvis ha ett beroende av det andra paketet.) När du skapar ett exempelpaket använder du den konventionsbaserade arbetskatalogmetoden som beskrevs tidigare. I mappen content ordnar du exempelkoden i en mapp som heter \Samples\<identifier> som i \Samples\Contoso.Utility.UsefulStuff.Sample.

Metodtips för paketversionen:

  • I allmänhet anger du vilken version av paketet som ska matcha biblioteket, men detta är inte absolut nödvändigt. Det här är en enkel sak när du begränsar ett paket till en enda sammansättning, enligt beskrivningen tidigare i Bestämma vilka sammansättningar som ska paketeras. Kom ihåg att NuGet själv hanterar paketversioner när du löser beroenden, inte sammansättningsversioner.
  • När du använder ett icke-standardversionsschema bör du överväga NuGet-versionsreglerna enligt beskrivningen i Paketversionshantering.

Följande serie korta blogginlägg är också användbara för att förstå versionshantering:

Lägga till ett readme och andra filer

Om du vill ange filer som ska inkluderas direkt i paketet använder du <files> noden i .nuspec filen, som följer taggen <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>

Tips/Råd

När du använder den konventionsbaserade arbetskatalogmetoden kan du placera readme.txt i paketroten och annat innehåll i content mappen. Inga <file> element krävs i manifestet.

När du tar med en fil med namnet readme.txt i paketroten visar Visual Studio innehållet i filen som oformaterad text direkt efter att paketet har installerats direkt. (Readme-filer visas inte för paket som installerats som beroenden). Här är till exempel hur readme för HtmlAgilityPack-paketet visas:

Visningen av en readme-fil för ett NuGet-paket vid installationen

Anmärkning

Om du inkluderar en tom <files> nod i .nuspec filen innehåller NuGet inte något annat innehåll i paketet än det som finns i lib mappen.

Inkludera MSBuild-rekvisita och mål i ett paket

I vissa fall kanske du vill lägga till anpassade byggmål eller egenskaper i projekt som använder ditt paket, till exempel att köra ett anpassat verktyg eller en process under bygget. Du kan lära dig mer om MSBuild-rekvisita och mål i NuGet-paket

Skapa <package_id>.targets eller <package_id>.props (till exempel Contoso.Utility.UsefulStuff.targets) i projektets byggmappar.

Se till att i .nuspec-filen referera till dessa filer i <files>-noden.

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

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

När paket läggs till i ett projekt inkluderar NuGet automatiskt dessa rekvisita och mål.

Kör nuget-paketet för att generera .nupkg-filen

När du använder en sammansättning eller den konventionsbaserade arbetskatalogen skapar du ett paket genom att köra nuget pack med din .nuspec-fil och genom att ersätta <project-name> med ditt specifika filnamn.

nuget pack <project-name>.nuspec

När du använder ett Visual Studio-projekt kör du nuget pack med din projektfil, vilket automatiskt laddar projektets .nuspec-fil och ersätter eventuella token i den med värden i projektfilen.

nuget pack <project-name>.csproj

Anmärkning

Att använda projektfilen direkt är nödvändigt för tokenbyte eftersom projektet är källan till tokenvärdena. Tokenbyte sker inte om du använder nuget pack med en .nuspec fil.

I samtliga fall nuget pack exkluderar mappar som börjar med en punkt, till exempel .git eller .hg.

NuGet anger om det finns några fel i .nuspec filen som behöver korrigeras, till exempel att glömma att ändra platshållarvärden i manifestet.

När det är nuget pack klart har du en .nupkg fil som du kan publicera till ett lämpligt galleri enligt beskrivningen i Publicera ett paket.

Tips/Råd

Ett användbart sätt att undersöka ett paket när du har skapat det är att öppna det i package explorer-verktyget . Detta ger dig en grafisk vy över paketinnehållet och dess manifest. Du kan också byta namn på den resulterande .nupkg filen till en .zip fil och utforska dess innehåll direkt.

Ytterligare alternativ

Du kan använda olika kommandoradsväxlar med nuget pack för att exkludera filer, åsidosätta versionsnumret i manifestet och ändra utdatamappen, bland andra funktioner. En fullständig lista finns i kommandoreferensen för paketet.

Följande alternativ är några som är vanliga med Visual Studio-projekt:

  • Refererade projekt: Om projektet refererar till andra projekt kan du lägga till de refererade projekten som en del av paketet, eller som beroenden, med hjälp -IncludeReferencedProjects av alternativet:

    nuget pack MyProject.csproj -IncludeReferencedProjects

    Den här inkluderingsprocessen är rekursiv, så om MyProject.csproj refererar till projekt B och C, och dessa projekt refererar till D, E och F, inkluderas filer från B, C, D, E och F i paketet.

    Om ett refererat projekt innehåller en .nuspec egen fil lägger NuGet till det refererade projektet som ett beroende i stället. Du måste paketera och publicera projektet separat.

  • Byggkonfiguration: Som standard använder NuGet standardkonfigurationsuppsättningen för bygget i projektfilen, vanligtvis Felsökning. Om du vill packa filer från en annan byggkonfiguration, till exempel Release, använder du -properties alternativet med konfigurationen:

    nuget pack MyProject.csproj -properties Configuration=Release

  • Symboler: Om du vill inkludera symboler som gör det möjligt för konsumenter att gå igenom din paketkod i felsökningsprogrammet använder du alternativet -Symbols :

    nuget pack MyProject.csproj -symbols

Testpaketinstallation

Innan du publicerar ett paket vill du vanligtvis testa processen med att installera ett paket i ett projekt. Testerna ser till att filerna nödvändigtvis hamnar på rätt platser i projektet.

Du kan testa installationer manuellt i Visual Studio eller på kommandoraden med hjälp av de normala installationsstegen för paket.

För automatiserad testning är den grundläggande processen följande:

  1. .nupkg Kopiera filen till en lokal mapp.
  2. Lägg till mappen i dina paketkällor med kommandot nuget sources add -name <name> -source <path> (se nuget-källor). Observera att du bara behöver ange den här lokala källan en gång på en viss dator.
  3. Installera paketet från den källan med nuget install <packageID> -source <name>, där <name> matchar namnet på din källa som har angivits till nuget sources. Om du anger källan ser du till att paketet installeras enbart från den källan.
  4. Granska filsystemet för att kontrollera att filerna är korrekt installerade.

Nästa steg

När du har skapat ett paket, som är en .nupkg fil, kan du publicera det till det galleri som du väljer enligt beskrivningen i Publicera ett paket.

Du kanske också vill utöka funktionerna i ditt paket eller på annat sätt stödja andra scenarier enligt beskrivningen i följande avsnitt:

Slutligen finns det ytterligare pakettyper att känna till:

  • Last updated on