NuGet inpakken en terugzetten als MSBuild doelstellingen

NuGet 4.0+

Met de PackageReference-indelingNuGet kan 4.0+ alle manifestmetagegevens rechtstreeks in een projectbestand opslaan in plaats van een afzonderlijk .nuspec bestand te gebruiken.

Met MSBuild 15.1+ is NuGet ook een volwaardige MSBuild met de doelen pack en restore zoals hieronder beschreven. Met deze targets kunt u werken zoals u met iedere andere NuGet taak of target zou doen. Zie Een NuGet-pakket maken met MSBuild voor instructies over het maken van een NuGet-pakket.MSBuild. (Voor NuGet 3.x en eerder gebruikt u in plaats daarvan het pakket en herstelopdrachten via de NuGet CLI.)

Doelbouwvolgorde

Omdat pack en restoreMSBuild-doelen zijn, kunt u deze openen om uw werkstroom te verbeteren. Stel dat u uw pakket wilt kopiëren naar een netwerkshare nadat u het pakket hebt verpakt. U kunt dit doen door het volgende toe te voegen aan uw projectbestand:

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

Op dezelfde manier kunt u een MSBuild taak schrijven, uw eigen doel definiëren en eigenschappen gebruiken binnen de NuGet taakMSBuild.

verpakkingsdoel

Voor .NET-projecten die de PackageReference indeling gebruiken, gebruikt u msbuild -t:pack invoer uit het projectbestand om te gebruiken bij het maken van een NuGet pakket.

Projecten zonder SDK-stijl moeten het pakket NuGet.Build.Tasks.Pack installeren wanneer u Visual Studio 2022 of eerder gebruikt. U wordt aangeraden dit pakket te verwijderen wanneer u een upgrade uitvoert naar Visual Studio 2026 om ervoor te zorgen dat uw project de nieuwste packfuncties en oplossingen voor fouten kan gebruiken.

In de volgende tabel worden de MSBuild eigenschappen beschreven die kunnen worden toegevoegd aan een projectbestand binnen het eerste <PropertyGroup> knooppunt. U kunt deze bewerkingen eenvoudig in Visual Studio 2017 en hoger maken door met de rechtermuisknop op het project te klikken en 'Bewerk {project_name}' te selecteren in het snelmenu. Voor het gemak wordt de tabel ingedeeld op basis van de equivalente eigenschap in een .nuspec bestand.

doelinvoer inpakken

packscenario's

Afhankelijkheden onderdrukken

Als u pakketafhankelijkheden van het gegenereerde NuGet pakket wilt onderdrukken, stelt u SuppressDependenciesWhenPackingtrue in op welke manier alle afhankelijkheden van het gegenereerde nupkg-bestand kunnen worden overgeslagen.

PackageIconUrl

PackageIconUrl is verouderd ten gunste van de PackageIcon eigenschap. NuGet Vanaf 5.3 en Visual Studio 2019 versie 16.3 wordt pack de NU5048-waarschuwing gegenereerd als alleen de metagegevens van het pakket worden opgegevenPackageIconUrl.

PackageIcon

Afbeeldingsbestand van een pictogram inpakken

Wanneer u een afbeeldingsbestand van een pictogram inpakt, gebruikt u de eigenschap PackageIcon om het pad naar het pictogrambestand relatief aan de hoofdmap van het pakket op te geven. Zorg er bovendien voor dat het bestand is opgenomen in het pakket. De grootte van het afbeeldingsbestand is beperkt tot 1 MB. Ondersteunde bestandsindelingen zijn JPEG en PNG. We raden een afbeeldingsresolutie van 128x128 aan.

Voorbeeld:

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

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

Voorbeeld van pakketpictogram.

Bekijk voor het nuspec equivalent een nuspec referentie voor het pictogram.

PackageReadmeFile

Ondersteund met NuGet 5.10.0 preview 2.NET / SDK 5.0.300 en hoger

Wanneer u een leesmij-bestand inpakt, moet u de PackageReadmeFile eigenschap gebruiken om het 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).

Voorbeeld:

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

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

Bekijk de referentie voor nuspec in de nuspec voor het equivalent.

Uitvoerassemblies

nuget pack kopieert uitvoerbestanden met extensies .exe, .dll, .xml, .winmd, .json en .pri. De uitvoerbestanden die worden gekopieerd, zijn afhankelijk van wat MSBuild het BuiltOutputProjectGroup doel biedt.

Er zijn twee MSBuild eigenschappen die u kunt gebruiken in uw projectbestand of opdrachtregel om te bepalen waar uitvoerassembly's naartoe gaan:

• IncludeBuildOutput: Een Booleaanse waarde die bepaalt of de build-uitvoerassembly's moeten worden opgenomen in het pakket.
• BuildOutputTargetFolder: Geeft de map op waarin de outputassemblies geplaatst moeten worden. De uitvoerassembly's (en andere uitvoerbestanden) worden gekopieerd naar hun overeenkomstige framework-mappen.

Softwarepakketverwijzingen

Zie Pakketverwijzingen in Project-bestanden.

Referenties tussen projecten

Project-naar-projectverwijzingen worden standaard beschouwd als NuGet pakketverwijzingen. Voorbeeld:

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

U kunt ook de volgende metagegevens toevoegen aan uw projectreferentie:

<IncludeAssets>
<ExcludeAssets>
<PrivateAssets>

Inhoud opnemen in een pakket

Als u inhoud wilt opnemen, voegt u extra metagegevens toe aan het bestaande <Content> item. Standaard wordt alles van het type 'Inhoud' opgenomen in het pakket, tenzij u overschrijft met vermeldingen als de volgende:

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

Standaard wordt alles toegevoegd aan de hoofdmap van de content en contentFiles\any\<target_framework> map in een pakket en blijft de relatieve mapstructuur behouden, tenzij u een pakketpad opgeeft:

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

Als u al uw inhoud naar alleen één specifieke hoofdmap of meerdere specifieke hoofdmappen wilt kopiëren (in plaats van naar zowel content als contentFiles), kunt u de eigenschap MSBuildContentTargetFolders gebruiken, die standaard is ingesteld op 'content;contentFiles', maar op andere mapnamen kan worden gezet. Houd er rekening mee dat door alleen 'contentFiles' op te geven in ContentTargetFolders, bestanden onder contentFiles\any\<target_framework> of contentFiles\<language>\<target_framework> worden geplaatst op basis van buildAction.

PackagePath kan een door puntkomma's gescheiden set doelpaden zijn. Als u een leeg pakketpad opgeeft, wordt het bestand toegevoegd aan de hoofdmap van het pakket. Het volgende wordt bijvoorbeeld toegevoegd libuv.txt aan content\myfiles, content\samplesen de hoofdmap van het pakket:

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

Er is ook een MSBuild eigenschap $(IncludeContentInPack), die standaard is ingesteld op true. Als dit is ingesteld false op een project, wordt de inhoud van dat project niet opgenomen in het nuget-pakket.

Andere pakketspecifieke metagegevens die u kunt instellen voor elk van de bovenstaande items omvatten <PackageCopyToOutput> en <PackageFlatten>, waarmee de waarden CopyToOutput en Flatten worden ingesteld voor de vermelding contentFiles in de uitvoer nuspec.

IncludeSymbolen

Bij gebruik MSBuild -t:pack -p:IncludeSymbols=trueworden de bijbehorende .pdb bestanden samen met andere uitvoerbestanden (.dll, .exe, .winmd, .xml, .json) .prigekopieerd. Houd er rekening mee dat met de instelling IncludeSymbols=true een normaal pakket en een symboolpakket worden gemaakt.

IncludeSource

Dit is hetzelfde als IncludeSymbols, behalve dat het bronbestanden samen met .pdb bestanden kopieert. Alle bestanden van het type Compile worden naar src\<ProjectName>\ gekopieerd, waarbij de relatieve padmapstructuur in het resulterende pakket behouden blijft. Hetzelfde gebeurt ook voor bronbestanden van elk ProjectReference met TreatAsPackageReference ingesteld op false.

Als een bestand van het type Compiler zich buiten de projectmap bevindt, wordt het net toegevoegd aan src\<ProjectName>\.

Een licentie-expressie of een licentiebestand inpakken

Wanneer u een licentie-expressie gebruikt, gebruikt u de PackageLicenseExpression eigenschap. Zie Licentie-expressie voorbeeld voor een voorbeeld.

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

Zie de NuGet voor meer informatie over licentie-expressies en licenties die door .org worden geaccepteerd.

Wanneer u een licentiebestand inpakt, gebruikt u de PackageLicenseFile-eigenschap om het pakketpad op te geven ten opzichte van de hoofdmap van het pakket. Zorg er bovendien voor dat het bestand is opgenomen in het pakket. Voorbeeld:

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

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

Zie Voorbeeld van licentiebestand voor een voorbeeld.

Een bestand inpakken zonder extensie

In sommige scenario's, zoals bij het inpakken van een licentiebestand, wilt u mogelijk een bestand zonder extensie opnemen. Om historische redenen NuGet behandelt & MSBuild paden zonder extensie als mappen.

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

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

Bestand zonder extensievoorbeeld.

IsTool

Wanneer u MSBuild -t:pack -p:IsTool=truealle uitvoerbestanden gebruikt, zoals opgegeven in het scenario Uitvoerassembly's , worden gekopieerd naar de tools map in plaats van de lib map. Houd er rekening mee dat dit verschilt van een DotNetCliTool waarde die wordt opgegeven door het in te stellen in PackageType het .csproj bestand.

Verpakken met behulp van een .nuspec bestand

Hoewel het raadzaam is om alle eigenschappen op te nemen die zich meestal in het .nuspec bestand in het projectbestand bevinden, kunt u ervoor kiezen om een .nuspec bestand te gebruiken om uw project in te pakken. U moet het project nog steeds herstellen voordat u een nuspec bestand kunt inpakken. (Een SDK-project bevat standaard de pakketdoelen.)

Het doelframework van het projectbestand is irrelevant en wordt niet gebruikt bij het inpakken van een nuspec. De volgende drie MSBuild eigenschappen zijn relevant voor verpakking met behulp van:.nuspec

1. NuspecFile: relatief of absoluut pad naar het .nuspec bestand dat wordt gebruikt voor verpakking.
2. NuspecProperties: een door puntkomma's gescheiden lijst met sleutel-waardeparen. Vanwege de manier waarop MSBuild opdrachtregelparsering werkt, moeten meerdere eigenschappen als volgt worden opgegeven: -p:NuspecProperties="key1=value1;key2=value2".
3. NuspecBasePath: basispad voor het .nuspec bestand.

Als u dotnet.exe uw project wilt verpakken, gebruik dan een opdracht als het volgende:

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

Als u MSBuild uw project wilt verpakken, gebruik dan een opdracht als het volgende:

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

Houd er rekening mee dat het inpakken van een nuspec met dotnet.exe of msbuild standaard leidt tot het bouwen van het project. Dit kan worden vermeden door de eigenschap door te geven --no-build aan dotnet.exe, wat het equivalent is van de instelling <NoBuild>true</NoBuild> in uw projectbestand, samen met de instelling <IncludeBuildOutput>false</IncludeBuildOutput> in het projectbestand.

Een voorbeeld van een .csproj-bestand voor het inpakken van een nuspec bestand is:

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

Geavanceerde uitbreidingspunten voor het maken van aangepast pakket

Het pack doel biedt twee uitbreidingspunten die worden uitgevoerd in de interne, doelframeworkspecifieke build. De extensiepunten ondersteunen onder andere specifieke inhoud en assembly's van het doelframework in een pakket:

• TargetsForTfmSpecificBuildOutput doel: Gebruiken voor bestanden in de lib map of een map die is opgegeven met behulp van BuildOutputTargetFolder.
• TargetsForTfmSpecificContentInPackage doel: Gebruiken voor bestanden buiten de BuildOutputTargetFolder.

TargetsForTfmSpecificBuildOutput

Schrijf een aangepast doel en geef het op als de waarde van de $(TargetsForTfmSpecificBuildOutput) eigenschap. Voor bestanden die standaard naar de BuildOutputTargetFolder (lib) moeten gaan, moet het doel deze bestanden naar de ItemGroup BuildOutputInPackage schrijven en de volgende twee metagegevenswaarden instellen:

• FinalOutputPath: het absolute pad van het bestand; indien niet opgegeven, wordt de identiteit gebruikt om het bronpad te evalueren.
• TargetPath: (Optioneel) Stel in wanneer het bestand in een submap lib\<TargetFramework> moet worden geplaatst, zoals satellietassembly's die onder hun respectieve cultuurmappen vallen. De standaardwaarde is de naam van het bestand.

Voorbeeld:

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

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

TargetsForTfmSpecificContentInPackage

Schrijf een aangepast doel en geef het op als de waarde van de $(TargetsForTfmSpecificContentInPackage) eigenschap. Als u bestanden in het pakket wilt opnemen, moet het doel deze bestanden naar de ItemGroup TfmSpecificPackageFile schrijven en de volgende optionele metagegevens instellen:

• PackagePath: Pad waar het bestand moet worden weergegeven in het pakket. NuGet geeft een waarschuwing als er meer dan één bestand wordt toegevoegd aan hetzelfde pakketpad.
• BuildAction: De buildactie die moet worden toegewezen aan het bestand, is alleen vereist als het pakketpad zich in de contentFiles map bevindt. De standaardwaarde is 'Geen'.

Een voorbeeld:

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

hersteldoel

MSBuild -t:restore (welke nuget restore en dotnet restore gebruikt met .NET Core-projecten), herstelt pakketten waarnaar wordt verwezen in het projectbestand als volgt:

1. Alle project-naar-projectverwijzingen lezen
2. Lees de projecteigenschappen om de tussenliggende map en doelplatforms te vinden
3. Gegevens doorsturen MSBuild naar NuGet.Build.Tasks.dll
4. Herstel uitvoeren
5. Pakketten downloaden
6. Assetsbestand, doelen en props schrijven

Het restore target werkt voor projecten die de PackageReference-indeling gebruiken. MSBuild 16.5+ biedt ook opt-in-ondersteuning voor de packages.config indeling.

Eigenschappen herstellen

Aanvullende herstelinstellingen kunnen afkomstig zijn van MSBuild eigenschappen in het projectbestand. Waarden kunnen ook worden ingesteld vanaf de opdrachtregel met behulp van de -p: schakeloptie (zie voorbeelden hieronder).

De ExcludeRestorePackageImports eigenschap is een interne eigenschap die wordt gebruikt door NuGet. Het mag niet worden gewijzigd of ingesteld in bestanden MSBuild .

Voorbeelden

Opdrachtregel:

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

Projectbestand:

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

Uitvoer herstellen

Door Herstellen worden de volgende bestanden aan de map obj build toegevoegd:

Herstellen en bouwen met één MSBuild opdracht

Vanwege het feit dat NuGet pakketten kan herstellen die MSBuild doelen en props verstoren, worden de herstel- en build-evaluaties uitgevoerd met diverse globale eigenschappen. Dit betekent dat het volgende zich onvoorspelbaar en vaak onjuist zal gedragen.

msbuild -t:restore,build

In plaats daarvan is de aanbevolen benadering:

msbuild -t:build -restore

Dezelfde logica is van toepassing op andere doelen die vergelijkbaar zijn met build.

PackageReference en packages.config projecten herstellen met MSBuild

Met MSBuild 16,5+ worden packages.config ook ondersteund voor msbuild -t:restore.

msbuild -t:restore -p:RestorePackagesConfig=true

Herstellen met MSBuild statische grafiekevaluatie

msbuild -t:restore -p:RestoreUseStaticGraphEvaluation=true

U kunt deze ook inschakelen door de eigenschap in te stellen in een Directory.Build.Props.

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

Statische grafiekherstel wijzigt het msbuild-onderdeel van herstel, het lezen en evalueren van het project, maar niet het herstelalgoritmen. Het herstelalgoritme is hetzelfde voor alle NuGet hulpprogramma's (NuGet.exe, MSBuild.exe, dotnet.exe en Visual Studio).

In zeer weinig scenario's kan het herstellen van een statische grafiek zich anders gedragen dan het huidige herstelproces. Bepaalde gedeclareerde PackageReferences of ProjectReferences kunnen ontbreken.

Als u uw gedachten wilt vereenvoudigen, kunt u, als eenmalige controle, overwegen om tijdens de migratie naar statische grafiekherstel het volgende uit te voeren:

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

NuGet mag geen wijzigingen rapporteren. Als u een discrepantie ziet, kunt u een probleem indienen bij NuGet/Home.

Eén bibliotheek vervangen binnen een herstelgrafiek

Als een herstelbewerking de verkeerde assembly bevat, is het mogelijk om die standaardkeuze voor pakketten uit te sluiten en te vervangen door uw eigen keuze. Begin met een hoogste niveau PackageReference en sluit alle assets uit:

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

Voeg vervolgens uw eigen verwijzing toe aan de juiste lokale kopie van het DLL-bestand:

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