NuGet packa och återställa som MSBuild mål

NuGet 4.0+

Med PackageReference-formatetNuGet kan 4.0+ lagra alla manifestmetadata direkt i en projektfil i stället för att använda en separat .nuspec fil.

Med MSBuild 15,1+ är NuGet också en förstaklassig komponent med pack och restore mål enligt beskrivningen nedan. Med de här målen kan du arbeta med NuGet på samma sätt som med andra MSBuild aktiviteter eller mål. Anvisningar för hur du skapar ett NuGet paket med hjälp av MSBuildfinns i Skapa ett NuGet paket med .MSBuild (För NuGet 3.x och tidigare använder du paket - och återställningskommandona via CLI i NuGet stället.)

Prioriterad byggordning

Eftersom pack och restore är MSBuild mål kan du komma åt dem för att förbättra arbetsflödet. Tänk dig att du vill kopiera paketet till en nätverksdelning efter att du har packat det. Du kan göra det genom att lägga till följande i projektfilen:

<Target Name="CopyPackage" AfterTargets="Pack">
  <Copy
    SourceFiles="$(OutputPath)..\$(PackageId).$(PackageVersion).nupkg"
    DestinationFolder="\\myshare\packageshare\"
    />
</Target>

På samma sätt kan du skriva en MSBuild uppgift, skriva ett eget mål och använda NuGet egenskaper i MSBuild aktiviteten.

paketmål

För .NET-projekt som använder PackageReference-formatet hämtar msbuild -t:pack indata från projektfilen för att använda denna i skapandet av ett NuGet-paket.

Icke-SDK-liknande projekt måste installera NuGet. Build.Tasks.Pack-paket när du använder Visual Studio 2022 eller tidigare. Vi rekommenderar att du avinstallerar det här paketet när du uppgraderar till Visual Studio 2026 för att säkerställa att projektet kan använda de senaste paketfunktionerna och felkorrigeringarna.

I följande tabell beskrivs de MSBuild egenskaper som kan läggas till i en projektfil inom den första <PropertyGroup> noden. Du kan enkelt göra dessa ändringar i Visual Studio 2017 och senare genom att högerklicka på projektet och välja Redigera {project_name} på snabbmenyn. För enkelhetens skull ordnas tabellen efter motsvarande egenskap i en .nuspec fil.

måldata för paket

paketscenarier

Förhindra beroenden

Om du vill förhindra paketberoenden från det genererade NuGet paketet, ställ in SuppressDependenciesWhenPacking till true vilket gör att du kan hoppa över alla beroenden från den genererade nupkg-filen.

PackageIconUrl

PackageIconUrl ersätts av egenskapen PackageIcon. Från och med NuGet 5.3 och Visual Studio 2019 version 16.3 pack genererar NU5048-varningen om paketmetadata endast anger PackageIconUrl.

PackageIcon

Packa en ikonbildfil

När du packar en ikonbildfil använder du PackageIcon egenskapen för att ange ikonfilens sökväg i förhållande till paketets rot. Kontrollera dessutom att filen ingår i paketet. Bildfilens storlek är begränsad till 1 MB. Filformat som stöds är JPEG och PNG. Vi rekommenderar en bildupplösning på 128x128.

Till exempel:

<PropertyGroup>
    ...
    <PackageIcon>icon.png</PackageIcon>
    ...
</PropertyGroup>

<ItemGroup>
    ...
    <None Include="images\icon.png" Pack="true" PackagePath="\"/>
    ...
</ItemGroup>

Exempel på paketikon.

För motsvarigheten nuspec, ta en titt på nuspec referensen för ikonen.

PackageReadmeFile

Stöds med NuGet förhandsversionen av 5.10.0 2.NET / SDK 5.0.300 och senare

När du packar en readme-fil måste du använda PackageReadmeFile egenskapen för att ange paketsökvägen i förhållande till paketets rot. Dessutom måste du se till att filen ingår i paketet. Filformat som stöds omfattar endast Markdown (.md).

Till exempel:

<PropertyGroup>
    ...
    <PackageReadmeFile>readme.md</PackageReadmeFile>
    ...
</PropertyGroup>

<ItemGroup>
    ...
    <None Include="docs\readme.md" Pack="true" PackagePath="\"/>
    ...
</ItemGroup>

För motsvarande nuspec tar du en titt på nuspec-referensen för README.

Utdatasammansättningar

nuget pack kopierar utdatafiler med tilläggen .exe, .dll, .xml, .winmd, .jsonoch .pri. Vilka utdatafiler som kopieras beror på vad MSBuild tillhandahåller från BuiltOutputProjectGroup mål.

Det finns två MSBuild egenskaper som du kan använda i projektfilen eller kommandoraden för att styra vart utdatasammansättningar ska gå:

• IncludeBuildOutput: Ett booleskt värde som avgör om kompilerade utdatasammansättningar ska ingå i paketet.
• BuildOutputTargetFolder: Anger den mapp där utdatasammansättningarna ska placeras. Utdatasammansättningarna (och andra utdatafiler) kopieras till respektive ramverksmappar.

Paketreferenser

Se Paketreferenser i Project Files.

Projekt till projektreferenser

Projekt-till-projektreferenser betraktas som standard som NuGet paketreferenser. Till exempel:

<ProjectReference Include="..\UwpLibrary2\UwpLibrary2.csproj"/>

Du kan också lägga till följande metadata i projektreferensen:

<IncludeAssets>
<ExcludeAssets>
<PrivateAssets>

Inkludera innehåll i ett paket

Om du vill inkludera innehåll lägger du till extra metadata i det befintliga <Content> objektet. Som standard ingår allt av typen "Innehåll" i paketet om du inte åsidosätter med poster som följande:

<Content Include="..\win7-x64\libuv.txt">
 <Pack>false</Pack>
</Content>

Som standardinställning läggs allt till i roten av content och contentFiles\any\<target_framework> mappen inom ett paket och bevarar den relativa mappstrukturen, såvida du inte anger en paketsökväg:

<Content Include="..\win7-x64\libuv.txt">
  <Pack>true</Pack>
  <PackagePath>content\myfiles\</PackagePath>
</Content>

Om du bara vill kopiera allt innehåll till en viss rotmapp (i stället för content och contentFiles båda) kan du använda MSBuild egenskapen ContentTargetFolders, som standard är "innehåll; contentFiles" men kan anges till andra mappnamn. Observera att om du bara anger "contentFiles" i ContentTargetFolders placeras filer under contentFiles\any\<target_framework> eller contentFiles\<language>\<target_framework> baserat på buildAction.

PackagePath kan vara en semikolonavgränsad uppsättning målsökvägar. Om en tom paketsökväg anges, skulle filen läggas till i paketets rot. Följande lägger libuv.txt till content\myfiles, content\samples och rooten för paketet:

<Content Include="..\win7-x64\libuv.txt">
  <Pack>true</Pack>
  <PackagePath>content\myfiles;content\sample;;</PackagePath>
</Content>

Det finns också en MSBuild egenskap $(IncludeContentInPack) som standard är true. Om detta är inställt false på för ett projekt inkluderas inte innehållet från det projektet i nuget-paketet.

Andra paketspecifika metadata som du kan ange för något av ovanstående objekt innehåller <PackageCopyToOutput> och <PackageFlatten> som anger CopyToOutput och Flatten värden för contentFiles posten i utdata nuspec.

InkluderaSymboler

När du använder MSBuild -t:pack -p:IncludeSymbols=truekopieras motsvarande .pdb filer tillsammans med andra utdatafiler (.dll, , .exe.winmd, .xml, .json, .pri). Observera att inställningen IncludeSymbols=true skapar ett vanligt paket och ett symbolpaket.

IncludeSource

Detta är samma som IncludeSymbols, förutom att det kopierar källfiler tillsammans med .pdb filer också. Alla filer av typen Compile kopieras över till src\<ProjectName>\, med bevarande av den relativa mappstrukturen i det resulterande paketet. Detsamma gäller för källfiler för alla ProjectReference som har TreatAsPackageReference inställd på false.

Om en fil av typen Kompilera ligger utanför projektmappen läggs den bara till src\<ProjectName>\i .

Packa ett licensuttryck eller en licensfil

Använd egenskapen PackageLicenseExpression när du använder ett licensuttryck. Ett exempel finns i Exempel på licensuttryck.

<PropertyGroup>
    <PackageLicenseExpression>MIT</PackageLicenseExpression>
</PropertyGroup>

Mer information om licensuttryck och licenser som godkänns av NuGet.org finns i licensmetadata.

När du packar en licensfil använder du PackageLicenseFile egenskapen för att ange paketsökvägen i förhållande till paketets rot. Kontrollera dessutom att filen ingår i paketet. Till exempel:

<PropertyGroup>
    <PackageLicenseFile>LICENSE.txt</PackageLicenseFile>
</PropertyGroup>

<ItemGroup>
    <None Include="licenses\LICENSE.txt" Pack="true" PackagePath=""/>
</ItemGroup>

Ett exempel finns i Exempel på licensfil.

Paketering av en fil utan tillägg

I vissa scenarier, till exempel när du packar en licensfil, kanske du vill inkludera en fil utan ett tillägg. Av historiska skäl NuGet behandlar & MSBuild sökvägar utan ett tillägg som kataloger.

  <PropertyGroup>
    <TargetFrameworks>netstandard2.0</TargetFrameworks>
    <PackageLicenseFile>LICENSE</PackageLicenseFile>
  </PropertyGroup>

  <ItemGroup>
    <None Include="LICENSE" Pack="true" PackagePath=""/>
  </ItemGroup>  

Fil utan tilläggsexempel.

IsTool

När du använder MSBuild -t:pack -p:IsTool=truekopieras alla utdatafiler som anges i scenariot Utdatasammansättningar till tools mappen i stället för mappen lib . Observera att detta skiljer sig från ett DotNetCliTool som anges genom att ange PackageType i .csproj -filen.

Paketering med hjälp av en .nuspec fil

Även om vi rekommenderar att du inkluderar alla egenskaper som vanligtvis finns i .nuspec filen i projektfilen i stället, kan du välja att använda en .nuspec fil för att packa projektet. Du måste fortfarande återställa projektet innan du kan packa en nuspec fil. (Ett SDK-projekt innehåller paketmålen som standard.)

Målramverket för projektfilen är irrelevant och används inte när du packar en nuspec. Följande tre MSBuild egenskaper är relevanta för packning med hjälp av en .nuspec:

1. NuspecFile: relativ eller absolut sökväg till filen .nuspec som används för packning.
2. NuspecProperties: en semikolonavgränsad lista över key=value-par. På grund av hur MSBuild kommandoradsparsing fungerar måste flera egenskaper anges på följande sätt: -p:NuspecProperties="key1=value1;key2=value2".
3. NuspecBasePath: Bassökväg för .nuspec filen.

Om du använder dotnet.exe för att packa projektet använder du ett kommando som liknar följande:

dotnet pack <path to .csproj file> -p:NuspecFile=<path to nuspec file> -p:NuspecProperties=<> -p:NuspecBasePath=<Base path> 

Om du använder MSBuild för att packa projektet använder du ett kommando som liknar följande:

msbuild -t:pack <path to .csproj file> -p:NuspecFile=<path to nuspec file> -p:NuspecProperties=<> -p:NuspecBasePath=<Base path> 

Observera att om du packar en nuspec med hjälp av dotnet.exe eller msbuild leder det också till att projektet byggs som standard. Detta kan undvikas genom att skicka --no-build egenskapen till dotnet.exe, vilket motsvarar inställningen <NoBuild>true</NoBuild> i projektfilen, tillsammans med inställningen <IncludeBuildOutput>false</IncludeBuildOutput> i projektfilen.

Ett exempel på en .csproj-fil för att packa en nuspec fil är:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <NoBuild>true</NoBuild>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <NuspecFile>PATH_TO_NUSPEC_FILE</NuspecFile>
    <NuspecProperties>add nuspec properties here</NuspecProperties>
    <NuspecBasePath>optional to provide</NuspecBasePath>
  </PropertyGroup>
</Project>

Avancerade tilläggspunkter för att skapa ett anpassat paket

Målet pack innehåller två tilläggspunkter som körs i den inre målramverkets specifika version. Tilläggspunkterna stöder att innefatta innehåll och assemblys specifikt för målramverket i ett paket.

• TargetsForTfmSpecificBuildOutput target: Använd för filer i lib mappen eller en mapp som har angetts med hjälp av BuildOutputTargetFolder.
• TargetsForTfmSpecificContentInPackage target: Används för filer utanför BuildOutputTargetFolder.

TargetsForTfmSpecificBuildOutput

Skriv ett anpassat mål och ange det som värdet för $(TargetsForTfmSpecificBuildOutput) egenskapen. För filer som behöver gå in i BuildOutputTargetFolder (lib som standard) ska målet skriva filerna till ItemGroup BuildOutputInPackage och ange följande två metadatavärden:

• FinalOutputPath: Filens absoluta sökväg; Om den inte anges används identiteten för att utvärdera källsökvägen.
• TargetPath: (Valfritt) Ange när filen behöver gå in i en undermapp i lib\<TargetFramework> , till exempel satellitsammansättningar som går under respektive kulturmapp. Defaultvärdet är filens namn.

Exempel:

<PropertyGroup>
  <TargetsForTfmSpecificBuildOutput>$(TargetsForTfmSpecificBuildOutput);GetMyPackageFiles</TargetsForTfmSpecificBuildOutput>
</PropertyGroup>

<Target Name="GetMyPackageFiles">
  <ItemGroup>
    <BuildOutputInPackage Include="$(OutputPath)cs\$(AssemblyName).resources.dll">
        <TargetPath>cs</TargetPath>
    </BuildOutputInPackage>
  </ItemGroup>
</Target>

TargetsForTfmSpecificContentInPackage

Skriv ett anpassat mål och ange det som värdet för $(TargetsForTfmSpecificContentInPackage) egenskapen. För alla filer som ska inkluderas i paketet bör målet skriva dessa filer till ItemGroup TfmSpecificPackageFile och ange följande valfria metadata:

• PackagePath: Sökväg där filen ska matas ut i paketet. NuGet utfärdar en varning om fler än en fil läggs till i samma paketsökväg.
• BuildAction: Byggåtgärden som ska tilldelas till filen krävs endast om paketsökvägen finns i contentFiles mappen. Standardvärdet är "Ingen".

Ett exempel:

<PropertyGroup>
  <TargetsForTfmSpecificContentInPackage>$(TargetsForTfmSpecificContentInPackage);CustomContentTarget</TargetsForTfmSpecificContentInPackage>
</PropertyGroup>

<Target Name="CustomContentTarget">
  <ItemGroup>
    <TfmSpecificPackageFile Include="abc.txt">
      <PackagePath>mycontent/$(TargetFramework)</PackagePath>
    </TfmSpecificPackageFile>
    <TfmSpecificPackageFile Include="Extensions/ext.txt" Condition="'$(TargetFramework)' == 'net46'">
      <PackagePath>net46content</PackagePath>
    </TfmSpecificPackageFile>  
  </ItemGroup>
</Target>  

återställ måltillstånd

MSBuild -t:restore (som nuget restore och dotnet restore använder med .NET Core-projekt), återställer paket som refereras i projektfilen enligt följande:

1. Läs alla projekt-till-projekt-referenser
2. Läs projektegenskaperna för att hitta den mellanliggande mappen och målramverken
3. Skicka MSBuild data till NuGet.Build.Tasks.dll
4. Utför återställning
5. Ladda ned paket
6. Skriv assets-fil, target-filer och props-filer

Målet restore fungerar för projekt med formatet PackageReference. MSBuild 16.5+ har även opt-in-support för packages.config formatet.

Återställa egenskaper

Ytterligare återställningsinställningar kan komma från MSBuild egenskaper i projektfilen. Värden kan också anges från kommandoraden med växeln -p: (se Exempel nedan).

Egenskapen ExcludeRestorePackageImports är en intern egenskap som används av NuGet. Den bör inte ändras eller anges i några MSBuild filer.

Examples

Kommandorad:

msbuild -t:restore -p:RestoreConfigFile=<path>

Projektfil:

<PropertyGroup>
    <RestoreIgnoreFailedSources>true</RestoreIgnoreFailedSources>
</PropertyGroup>

Återställa utdata

Återställning skapar följande filer i byggmappen obj :

Återställ och bygg med ett MSBuild kommando

På grund av det faktum att NuGet kan återställa paket som tar ner MSBuild mål och rekvisita, körs återställnings- och byggutvärderingarna med olika globala egenskaper. Det innebär att följande kommer att ha ett oförutsägbart och ofta felaktigt beteende.

msbuild -t:restore,build

Den rekommenderade metoden är i stället:

msbuild -t:build -restore

Samma logik gäller för andra mål som liknar build.

Återställa PackageReference- och packages.config-projekt med MSBuild

Med MSBuild 16,5+ stöds packages.config också för msbuild -t:restore.

msbuild -t:restore -p:RestorePackagesConfig=true

Återställning med MSBuild statisk granskning av grafer

msbuild -t:restore -p:RestoreUseStaticGraphEvaluation=true

Du kan också aktivera den genom att ange egenskapen i en Directory.Build.Props.

<Project>
  <PropertyGroup>
    <RestoreUseStaticGraphEvaluation>true</RestoreUseStaticGraphEvaluation>
  </PropertyGroup>
</Project>

Återställning av en statisk graf förändrar den del av msbuild som tillhör återställningen, projektläsningen och utvärderingen, men inte återställningsalgoritmen! Återställningsalgoritmen är densamma för alla NuGet verktyg (NuGet.exe, MSBuild.exe, dotnet.exe och Visual Studio).

I mycket få scenarier kan återställning av statiska diagram fungera annorlunda än den aktuella återställningen och vissa deklarerade PackageReferences eller ProjectReferences kanske saknas.

För att underlätta för dig kan du som en engångskontroll, när du migrerar till återställning av statiska diagram, överväga att köra:

msbuild.exe -t:restore -p:RestoreUseStaticGraphEvaluation=true
msbuild.exe -t:restore

NuGet bör inte rapportera några ändringar. Om du ser en avvikelse anger du ett problem på NuGet/Home.

Ersätta ett bibliotek från ett återställningsdiagram

Om en återställning ger fel sammansättning är det möjligt att undanta standardalternativet för paket och ersätta det med ditt eget val. Först med en toppnivå PackageReferenceexkluderar du alla tillgångar:

<PackageReference Include="Newtonsoft.Json" Version="9.0.1">
  <ExcludeAssets>All</ExcludeAssets>
</PackageReference>

Lägg sedan till din egen referens till lämplig lokal kopia av DLL:en:

<Reference Include="Newtonsoft.Json.dll" />