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 (kommandoradsgränssnittet), antingen nuget.exe eller dotnet.exe, för att paketera funktionerna i en komponent som kan delas med och användas av andra utvecklare. Information om hur du installerar NuGet CLI-verktyg finns i Installera NuGet-klientverktyg. Visual Studio innehåller inte ett CLI-verktyg automatiskt.

• För icke-SDK-liknande projekt, vanligtvis .NET Framework-projekt, följer du stegen som beskrivs i den här artikeln för att skapa ett paket. En snabbstart som innehåller stegvisa instruktioner för hur du använder Visual Studio och nuget.exe CLI finns i Quickstart: Skapa och publicera ett paket med Visual Studio (.NET Framework, Windows).

• För .NET Core- och .NET Standard-projekt som använder formatet SDK och andra SDK-liknande projekt, se Skapa ett NuGet-paket med dotnet CLI.

• För projekt som migrerats från packages.config till PackageReference ska du använda kommandot msbuild -t:pack.

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

Paketeringen börjar med den kompilerade koden (sammansättningar), symboler och andra filer som du vill leverera som ett paket. En översikt över paketeringsprocessen finns i Arbetsflöde för att skapa paket. Den här processen är oberoende av kompilering eller på annat sätt genererar de filer som går in i paketet. Men du kan hämta information i en projektfil för att hålla de kompilerade sammansättningarna och paketen synkroniserade.

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. Tänk till exempel på följande fall som involverar en sammansättning som kallas Utilities.dll som är beroende av en sammansättning som heter Parser.dll:

• Om Parser.dll är användbart på egen hand skapar du ett paket för Utilities.dll och ett för Parser.dll. På så sätt kan utvecklare använda Parser.dll oberoende av Utilities.dll.

• Om Parser.dll innehåller kod som endast används av Utilities.dllär det bra att behålla Parser.dll i samma paket. Om biblioteket i allmänhet består av flera sammansättningar som inte är oberoende av varandra är det bra att kombinera dem till ett paket.

• Om Utilities.dll också är beroende avUtilities.resources.dll, och Utilities.resources.dll inte är användbar på egen hand, lägger du båda i samma paket.

Resurser, till exempel Utilities.resources.dll sammansättning i föregående exempel, är ett specialfall. När ett paket installeras i ett projekt lägger NuGet automatiskt till sammansättningsreferenser till paketets DLL:er, exklusive de som heter .resources.dll, eftersom de antas vara lokaliserade satellitsammansättningar. Mer information om lokaliserade versioner av ett bibliotek finns i Skapa lokaliserade NuGet-paket. Undvik därför att använda .resources.dll för filer som innehåller viktig paketkod.

Om biblioteket innehåller COM-interop-sammansättningar (Component Object Model) följer du de ytterligare riktlinjerna i Skapa NuGet-paket som innehåller COM-interop-sammansättningar.

Rollen och strukturen för .nuspec-filen

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

Manifestet:

• Beskriver paketets innehåll och ingår i paketet.
• Driver skapandet av paketet och talar om för NuGet 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.
• Innehåller både obligatoriska och valfria egenskaper enligt beskrivningen i resten av det här avsnittet. Detaljerad information, inklusive andra egenskaper som inte nämns här, finns i .nuspec-referens.

Följande egenskaper krävs i manifestet:

• 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
• En lång beskrivning av paketet

Följande egenskaper är vanliga valfria:

• Versionsinformation
• Upphovsrättsinformation.
• En kort beskrivning av användargränssnittet Správca balíkov i Visual Studio.
• Ett språk-ID.
• En projekt-URL.
• En licens som ett uttryck eller en fil. Egenskapen licenseUrl är inaktuell. Använd nuspec-metadataelementetlicense i stället.
• En läs-mig-fil.
• En ikonfil. Egenskapen iconUrl är inaktuell. Använd nuspec-metadataelementeticon i stället.
• Listor över beroenden och referenser.
• Taggar som hjälper till med gallerisökningar.

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

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

        <!-- A package version number that's used when resolving dependencies -->
        <version>1.8.3</version>

        <!-- A comma-separated list of package authors that sometimes appears directly on the gallery -->
        <authors>Dejana Tesic, Rajeev Dey</authors>

        <!-- A project URL that provides a link for the gallery -->
        <projectUrl>http://github.com/contoso/UsefulStuff</projectUrl>

        <!-- License information that's displayed on the gallery -->
        <license type="expression">Apache-2.0</license>
        
        <!-- The location of a read-me file that's displayed in the Visual Studio Package Manager UI -->
        <readme>readme.md</readme>

        <!-- An icon that's used in the Visual Studio Package Manager UI -->
        <icon>icon.png</icon>

        <!-- 
            A property that when true, prompts the user to accept the license when
            installing the package
        -->
        <requireLicenseAcceptance>false</requireLicenseAcceptance>

        <!-- Detailed information about a particular release -->
        <releaseNotes>Bug fixes and performance improvements</releaseNotes>

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

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

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

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

    <!-- A read-me Markdown file that's displayed in the Package Manager UI -->
    <files>
        <file src="readme.md" target="" />
        <file src="icon.png" target="" />
    </files>
</package>

Detaljerad information om hur du deklarerar beroenden och anger versionsnummer finns ipackages.config och Paketversioner. Du kan också använda attributen include och exclude för -elementet dependency för att ange de beroende tillgångar som du vill inkludera eller exkludera i paketet. Mer information finns i .nuspec Reference – Dependencies-element.

Eftersom manifestet ingår i paketet som skapats från det kan du hitta exempel genom att undersöka befintliga paket. En bra källa är mappen global-packages på datorn. Använd följande kommando för att hitta platsen:

nuget locals -list global-packages

När du vet platsen för mappen global-packages gör du följande för att hitta en manifestfil:

1. Gå till mappen global-packages .
2. I den mappen går du till undermappen för alla paket och går sedan till en undermapp för alla versioner av paketet.
3. I undermappen version gör du en kopia av .nupkg-filen och ändrar kopians tillägg till zip.
4. Öppna filen.zip och granska .nuspec-filen i den.

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:

• En konventionsbaserad arbetskatalog
• En sammansättnings-DLL
• En Visual Studio projekt
• En ny fil med standardvärden

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

Från en konventionsbaserad arbetskatalog

Eftersom ett NuGet-paket är en ZIP-fil som har bytt namn till .nupkg-tillägget är det ofta enklast att skapa den mappstruktur som du vill använda i det lokala filsystemet och sedan skapa .nuspec-filen direkt från den strukturen. Kommandot nuget pack lägger sedan automatiskt till alla filer i den mappstrukturen, men det exkluderar alla mappar som börjar med en punkt, 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. I stället kan du låta byggprocessen skapa den exakta mappstrukturen som går in i paketet. Du kan också 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

Mapparna överensstämmer med följande konventioner:

Eftersom mappstrukturen kan innehålla sammansättningar för många 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 följande kommando i mappen för att skapa .nuspec-filen :

nuget spec

Den genererade .nuspec-filen innehåller 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

När du skapar 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. Dessa egenskaper innehåller fortfarande platshållare när du har kört kommandot.

Från ett Visual Studio projekt

Det är praktiskt att skapa en .nuspec-fil från en .csproj - eller .vbproj-fil , eftersom andra paket som är installerade i projektet automatiskt refereras till som beroenden. Om du vill skapa ett manifest från en projektfil använder du följande kommando i mappen som innehåller projektfilen:

# Use in a folder that contains a project file, such as <project-name>.csproj or <project-name>.vbproj.
nuget spec

Den resulterande <filen project-name.nuspec> 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 använder du nuget packi stället . Hämta sedan .nuspec-filen från den genererade .nupkg-filen . Använd till exempel följande kommando:

# Use in a folder that contains a project file, such as <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> ser värdet i ett manifest som genereras på det här sättet vanligtvis ut som följande rad:

<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-filens token kan ses i Ersättningstoken.

Med token behöver du inte uppdatera viktiga värden som versionsnumret i .nuspec-filen när du uppdaterar projektet. Men du kan också ersätta token med literalvärden.

Det finns flera extra paketeringsalternativ när du arbetar från ett Visual Studio projekt, enligt beskrivningen i Kör nuget pack för att generera .nupkg-filen senare i den här artikeln.

Paket på lösningsnivå

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

NuGet 2.x stöder begreppet paket på lösningsnivå som installerar verktyg eller extra kommandon för Správca balíkov-konsolen (innehållet i mappen tools), men lägger inte till referenser, innehåll eller bygganpassningar i några projekt i lösningen. Sådana paket innehåller inga filer i sina direkta lib-, innehålls- eller byggmappar , och ingen av deras beroenden har filer i sina respektive lib-, innehålls- eller byggmappar .

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

Från en ny fil med standardvärden

Följande kommando skapar ett standardmanifest med platshållare, vilket hjälper dig att börja med rätt filstruktur:

nuget spec [<package-name>]

Om du utelämnar <package-name>får den resulterande filen namnet Package.nuspec. Om du anger ett namn som Contoso.Utility.UsefulStuffheter filen Contoso.Utility.UsefulStuff.nuspec.

Den resulterande .nuspec-filen innehåller platshållare för värden som projectUrl. Innan du använder filen för att skapa den sista .nupkg-filen ersätter du platshållarna med lämpliga värden.

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 galleriet som är värd för paketet, till exempel nuget.org. 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.
• Namespace-liknande namn: Följ ett mönster som liknar namnområden i .NET, med 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. Ett exempelpaket av den här typen har ett beroende av paketet som visar hur du använder det. När du skapar ett exempelpaket använder du den konventionsbaserade arbetskatalogmetoden som beskrevs tidigare. I innehållsmappen ordnar du exempelkoden i en mapp med namnet \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. Den här vägledningen rekommenderas men krävs inte strikt. Den här metoden är enkel när du begränsar ett paket till en enda sammansättning, enligt beskrivningen tidigare i Bestäm vilka sammansättningar som ska paketeras. I allmänhet bör du komma 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.

Andra resurser som är användbara för att förstå versionshantering finns i följande serie med korta blogginlägg:

• Del 1: Bekämpa DLL Hell
• Del 2: Kärnalgoritmen
• Del 3: Sammanslagning via bindningsomdirigeringar

Lägga till en read-me-fil 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/2013/05/nuspec.xsd">
    <metadata>
        <!-- ... -->
    </metadata>
    <files>
        <!-- Add files from an arbitrary folder that's not necessarily in the project. -->
        <file src="..\..\SomeRoot\**\*.*" target="" />
    </files>
</package>

Om du vill inkludera en read-me-fil i paketet använder du readme metadataelementet för att ange målsökvägen till filen read-me. Använd också ett file metadataelement för att ange källsökvägen och målmappen för filen read-me. Mer information finns i readme.

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
    <metadata>
        <!-- ... -->
        <readme>docs\readme.md</readme>
        <!-- ... -->
    </metadata>
    <files>
        <!-- Add a read-me file. -->
        <file src="..\readme.md" target="docs\" />
    </files>
</package>

Visual Studio visar innehållet i filen read-me i Správca balíkov användargränssnittet. Följande skärmbild visar till exempel filen read-me för HtmlAgilityPack paketet:

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. Mer information om anpassade byggmål och egenskaper finns i MSBuild .props och .targets i ett paket.

Skapa <paket-id.targets>- eller <package-id.props-filer>, till exempel Contoso.Utility.UsefulStuff.targets, i projektets byggmappar.

Sedan hänvisar du i .nuspec-filen till dessa filer i <files> noden:

<?xml version="1.0"?>
<package >
    <metadata minClientVersion="2.5">
    <!-- ... -->
    </metadata>
    <files>
        <!-- In the package build folder, include everything that's in the local build folder. -->
        <file src="build\**" target="build" />

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

När paket läggs till i ett projekt innehåller NuGet automatiskt dessa egenskaper 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 .nuspec-filen . I följande kommando ersätter du <project-name> med namnet på projektet:

nuget pack <project-name>.nuspec

När du använder ett Visual Studio projekt kör du nuget pack med projektfilen. Det här kommandot läser automatiskt in projektets .nuspec-fil och ersätter eventuella token i den med motsvarande värden i projektfilen:

nuget pack <project-name>.csproj

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 platshållarvärden i manifestet som måste uppdateras.

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

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 paketkommandot (NuGet CLI).

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. Om Till exempel MyProject.csproj refererar till projekt B och C, och projekten 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 egen .nuspec-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 standardkonfigurationen som anges i projektfilen, vanligtvis Debug. 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 -Symbols alternativen och -SymbolPackageFormat . För alternativet -SymbolPackageFormat anger du formatet snupkg:

  nuget pack MyProject.csproj -symbols -SymbolPackageFormat snupkg
  

Testpaketinstallation

Innan du publicerar ett paket vill du vanligtvis testa processen med att installera paketet i ett projekt. Ett test hjälper till att säkerställa att alla nödvändiga filer hamnar på rätt plats i projektet.

Du kan testa installationer manuellt i Visual Studio eller på kommandoraden med hjälp av standardinstallationsstegen package.

För automatiserad testning kan du använda följande grundläggande process:

1. Kopiera .nupkg-filen till en lokal mapp.
2. Lägg till mappen i paketkällorna med hjälp nuget sources add -name <name> -source <path> av kommandot . Mer information finns i kommandot sources (NuGet CLI). Du behöver bara ange den här lokala källan en gång på en viss dator.
3. Installera paketet från den källan med hjälp av nuget install <package-ID> -source <name>. I det här kommandot <name> ska matcha namnet på den källa som du använder i nuget sources kommandot. Om du anger källan uppmanas NuGet att installera paketet enbart från den källan.
4. Granska filsystemet för att kontrollera att filerna är korrekt installerade.

Relaterat innehåll

När du har skapat ett paket, som är en .nupkg-fil , kan du publicera det i valfri galleri. Mer information finns i Publicera NuGet-paket.

Du kan också utöka funktionerna i ditt paket eller stödja andra scenarier. Mer information finns i följande artiklar:

• Paketversionshantering
• Stöd flera .NET-versioner
• Transformera källkods- och konfigurationsfiler
• Skapa lokaliserade NuGet-paket
• Skapa förhandsversionspaket
• Ställ in en NuGet-pakettyp
• Skapa NuGet-paket som innehåller COM-interop-sammansättningar

Information om andra pakettyper finns i följande artiklar:

• Skapa interna paket
• Skapa symbolpaket (.snupkg)