NuGet pack e ripristino come MSBuild destinazioni

NuGet 4.0+

Con il formato PackageReference , NuGet 4.0+ può archiviare tutti i metadati del manifesto direttamente all'interno di un file di progetto anziché usare un file separato .nuspec .

Con MSBuild 15.1+, NuGet è anche un cittadino di prima classe MSBuild con gli pack obiettivi e restore come descritto di seguito. Queste destinazioni consentono di usare NuGet come si farebbe con qualsiasi altra MSBuild attività o destinazione. Per istruzioni sulla creazione di un pacchetto con MSBuild, vedere Creare un NuGet pacchetto con MSBuild.NuGet (Per NuGet 3.x e versioni precedenti, si usano invece i comandi pack e restore tramite l'interfaccia della NuGet riga di comando.

Ordine di compilazione delle destinazioni

Poiché pack e restore sono MSBuild destinazioni, è possibile accedervi per migliorare il flusso di lavoro. Si supponga, ad esempio, di voler copiare il pacchetto in una condivisione di rete dopo averlo creato. È possibile farlo aggiungendo quanto segue nel file di progetto:

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

Analogamente, è possibile scrivere un'attività MSBuild , scrivere la propria destinazione e utilizzare NuGet le proprietà nell'attività MSBuild .

Nota

$(OutputPath) è relativo e prevede di eseguire il comando dalla radice del progetto.

Destinazione pack

Per i progetti .NET che usano il PackageReference formato , utilizzando msbuild -t:pack disegna input dal file di progetto da usare per la creazione di un NuGet pacchetto.

Nella tabella seguente vengono descritte le MSBuild proprietà che è possibile aggiungere a un file di progetto all'interno del primo <PropertyGroup> nodo. È possibile apportare facilmente queste modifiche in Visual Studio 2017 e versioni successive facendo clic con il pulsante destro del mouse sul progetto e scegliendo Modifica {nome_progetto} dal menu di scelta rapida. Per praticità, la tabella è organizzata in base alla proprietà equivalente in un .nuspec file.

Nota

Owners le proprietà e Summary da .nuspec non sono supportate con MSBuild.

Attributo/nuspec Valore Proprietà diMSBuild Default Note
Id PackageId $(AssemblyName) $(AssemblyName) da MSBuild
Version PackageVersion Versione Si tratta di semver compatibile, ad esempio 1.0.0, 1.0.0-betao 1.0.0-beta-00345. L'impostazione predefinita è Version se non impostata.
VersionPrefix VersionPrefix empty Impostazione PackageVersion delle sovrascrizioni VersionPrefix
VersionSuffix VersionSuffix empty Impostazione PackageVersion delle sovrascrizioni VersionSuffix
Authors Authors Nome utente dell'utente corrente Elenco delimitato da punto e virgola di autori di pacchetti, che corrispondono ai nomi dei profili in nuget.org. Questi vengono visualizzati nella raccolta in NuGet nuget.org e vengono usati per fare riferimento incrociato ai pacchetti degli stessi autori.
Owners N/D Non presente in nuspec
Title Title $(PackageId) Titolo del pacchetto facilmente comprensibile per l'utente, usato di solito per la visualizzazione dell'interfaccia utente, ad esempio in nuget.org e in Gestione pacchetti in Visual Studio.
Description Description "Descrizione del pacchetto" Descrizione lunga per l'assembly. Se PackageDescription non viene specificato, questa proprietà viene utilizzata anche come descrizione del pacchetto.
Copyright Copyright empty Informazioni sul copyright per il pacchetto.
RequireLicenseAcceptance PackageRequireLicenseAcceptance false Valore booleano che specifica se il client deve richiedere al consumer di accettare la licenza del pacchetto prima di installarlo.
license PackageLicenseExpression empty Corrisponde a <license type="expression">. Vedere Compressione di un'espressione di licenza o di un file di licenza.
license PackageLicenseFile empty Percorso di un file di licenza all'interno del pacchetto se si usa una licenza personalizzata o una licenza a cui non è stato assegnato un identificatore SPDX. È necessario comprimere in modo esplicito il file di licenza a cui si fa riferimento. Corrisponde a <license type="file">. Vedere Compressione di un'espressione di licenza o di un file di licenza.
LicenseUrl PackageLicenseUrl empty PackageLicenseUrl è stato deprecato. In sostituzione utilizzare PackageLicenseExpression o PackageLicenseFile.
ProjectUrl PackageProjectUrl empty
Icon PackageIcon empty Percorso di un'immagine nel pacchetto da usare come icona del pacchetto. È necessario comprimere in modo esplicito il file di immagine dell'icona a cui si fa riferimento. Per altre informazioni, vedere Compressione di un file di immagine icona e icon metadati.
IconUrl PackageIconUrl empty PackageIconUrl è deprecato a favore di PackageIcon. Tuttavia, per un'esperienza di livello inferiore ottimale, è necessario specificare PackageIconUrl oltre a PackageIcon.
Readme PackageReadmeFile empty È necessario comprimere in modo esplicito il file leggimi a cui si fa riferimento.
Tags PackageTags empty Elenco di tag con valori delimitati da punto e virgola che designa il pacchetto.
ReleaseNotes PackageReleaseNotes empty Note sulla versione per il pacchetto.
Repository/Url RepositoryUrl empty URL del repository usato per clonare o recuperare il codice sorgente. Esempio: https://github.com/NuGethttps://github.com/NuGet/NuGet.Client.git.
Repository/Type RepositoryType empty Tipo di repository. Esempi: git (impostazione predefinita), tfs.
Repository/Branch RepositoryBranch empty Informazioni facoltative sul ramo del repository. RepositoryUrl deve essere specificato anche per includere questa proprietà. Esempio: master (NuGet 4.7.0+).
Repository/Commit RepositoryCommit empty Commit o set di modifiche del repository facoltativo per indicare l'origine in cui è stato compilato il pacchetto. RepositoryUrl deve essere specificato anche per includere questa proprietà. Esempio: 0e4d1b598f350b3dc675018d539114d1328189ef (NuGet 4.7.0+).
PackageType <PackageType>CustomType1, 1.0.0.0;CustomType2</PackageType> Indica l'uso previsto del pacchetto. I tipi di pacchetto usano lo stesso formato degli ID pacchetto e sono delimitati da ;. I tipi di pacchetto possono essere con versione aggiungendo un , oggetto e una Version stringa. Vedere Impostare un NuGet tipo di pacchetto (NuGet 3.5.0+).
Summary Non supportato

Input destinazione pack

Proprietà Descrizione
IsPackable Valore booleano che specifica se dal progetto può essere creato un pacchetto. Il valore predefinito è true.
SuppressDependenciesWhenPacking Impostare su true per eliminare le dipendenze dei pacchetti dal pacchetto generato NuGet .
PackageVersion Specifica la versione che avrà il pacchetto risultante. Accetta tutte le forme di stringa di NuGet versione. Il valore predefinito corrisponde al valore di $(Version), vale a dire della proprietà Version nel progetto.
PackageId Specifica il nome del pacchetto risultante. Se non specificato, l'impostazione predefinita per l'operazione pack corrisponde all'uso di AssemblyName o del nome della directory come nome del pacchetto.
PackageDescription Descrizione lunga del pacchetto per la visualizzazione dell'interfaccia utente.
Authors Elenco delimitato da punto e virgola di autori di pacchetti, che corrispondono ai nomi dei profili in nuget.org. Questi vengono visualizzati nella raccolta in NuGet nuget.org e vengono usati per fare riferimento incrociato ai pacchetti degli stessi autori.
Description Descrizione lunga per l'assembly. Se PackageDescription non viene specificato, questa proprietà viene utilizzata anche come descrizione del pacchetto.
Copyright Informazioni sul copyright per il pacchetto.
PackageRequireLicenseAcceptance Valore booleano che specifica se il client deve richiedere al consumer di accettare la licenza del pacchetto prima di installarlo. Il valore predefinito è false.
DevelopmentDependency Valore booleano che specifica se il pacchetto è contrassegnato come dipendenza di sola sviluppo, che impedisce l'inclusione del pacchetto come dipendenza in altri pacchetti. Con PackageReference (NuGet 4.8+), questo flag significa anche che gli asset in fase di compilazione vengono esclusi dalla compilazione. Per altre informazioni, vedere Supporto di DevelopmentDependency per PackageReference.
PackageLicenseExpression Identificatore o espressione di licenza SPDX, Apache-2.0ad esempio . Per altre informazioni, vedere Compressione di un'espressione di licenza o di un file di licenza.
PackageLicenseFile Percorso di un file di licenza all'interno del pacchetto se si usa una licenza personalizzata o una licenza a cui non è stato assegnato un identificatore SPDX.
PackageLicenseUrl PackageLicenseUrl è stato deprecato. In sostituzione utilizzare PackageLicenseExpression o PackageLicenseFile.
PackageProjectUrl
PackageIcon Specifica il percorso dell'icona del pacchetto, relativo alla radice del pacchetto. Per altre informazioni, vedere Creazione di un file di immagine icona.
PackageReleaseNotes Note sulla versione per il pacchetto.
PackageReadmeFile File Leggimi per il pacchetto.
PackageTags Elenco di tag con valori delimitati da punto e virgola che designa il pacchetto.
PackageOutputPath Determina il percorso di output in cui verrà rilasciato il pacchetto creato. Il valore predefinito è $(OutputPath).
IncludeSymbols Valore booleano che indica se al momento della creazione del pacchetto deve essere creato un pacchetto aggiuntivo di simboli. Il formato del pacchetto di simboli è controllato dalla proprietà SymbolPackageFormat. Per altre informazioni, vedere IncludeSymbols.
IncludeSource Valore booleano che indica se il processo di creazione del pacchetto deve creare un pacchetto di origine. Il pacchetto di origine contiene il codice sorgente della libreria, nonché i file PDB. I file di origine vengono posizionati nella directory src/ProjectName del file del pacchetto risultante. Per altre informazioni, vedere IncludeSource.
PackageType
IsTool Specifica se tutti i file di output devono essere copiati nella cartella tools anziché nella cartella lib. Per altre informazioni, vedere IsTool.
RepositoryUrl URL del repository usato per clonare o recuperare il codice sorgente. Esempio: https://github.com/NuGethttps://github.com/NuGet/NuGet.Client.git.
RepositoryType Tipo di repository. Esempi: git (impostazione predefinita), tfs.
RepositoryBranch Informazioni facoltative sul ramo del repository. RepositoryUrl deve essere specificato anche per includere questa proprietà. Esempio: master (NuGet 4.7.0+).
RepositoryCommit Commit o set di modifiche del repository facoltativo per indicare l'origine in cui è stato compilato il pacchetto. RepositoryUrl deve essere specificato anche per includere questa proprietà. Esempio: 0e4d1b598f350b3dc675018d539114d1328189ef (NuGet 4.7.0+).
SymbolPackageFormat Specifica il formato del pacchetto di simboli. Se "symbols.nupkg", viene creato un pacchetto di simboli legacy con estensione symbols.nupkg contenente FILE PDF, DLL e altri file di output. Se "snupkg", viene creato un pacchetto di simboli snupkg contenente i PDB portatili. Il valore predefinito è "symbols.nupkg".
NoPackageAnalysis Specifica che pack non deve eseguire l'analisi dei pacchetti dopo la compilazione del pacchetto.
MinClientVersion Specifica la versione minima del client in grado di NuGet installare il pacchetto, applicato da nuget.exe e da Visual Studio Gestione pacchetti.
IncludeBuildOutput Questo valore booleano specifica se gli assembly di output di compilazione devono essere compressi nel file con estensione nupkg .
IncludeContentInPack Questo valore booleano specifica se gli elementi con un tipo di Content vengono inclusi automaticamente nel pacchetto risultante. Il valore predefinito è true.
BuildOutputTargetFolder Specifica la cartella in cui inserire gli assembly di output. Gli assembly di output (e altri file di output) vengono copiati nelle rispettive cartelle per framework. Per altre informazioni, vedere Assembly di output.
ContentTargetFolders Specifica il percorso predefinito in cui devono essere specificati tutti i file di contenuto se PackagePath non vengono specificati. Il valore predefinito è "content;contentFiles". Per altre informazioni, vedere Including content in a package (Includere contenuto in un pacchetto).
NuspecFile Percorso relativo o assoluto del file utilizzato per la .nuspec compressione. Se specificato, viene usato esclusivamente per i pacchetti di informazioni e le informazioni nei progetti non vengono usate. Per altre informazioni, vedere Packaging using a .nuspec.
NuspecBasePath Percorso di base per il .nuspec file. Per altre informazioni, vedere Packaging using a .nuspec.
NuspecProperties Elenco con valori delimitati da punto e virgola di coppie chiave=valore. Per altre informazioni, vedere Packaging using a .nuspec.

Scenari pack

Eliminazione delle dipendenze

Per eliminare le dipendenze dei pacchetti dal pacchetto generato NuGet , impostare su SuppressDependenciesWhenPackingtrue che consentirà di ignorare tutte le dipendenze dal file nupkg generato.

PackageIconUrl

PackageIconUrl è deprecato a favore della PackageIcon proprietà . NuGet A partire dalla versione 5.3 e Visual Studio 2019 versione 16.3, pack genera l'avviso NU5048 se i metadati del pacchetto specificano PackageIconUrlsolo .

PackageIcon

Suggerimento

Per mantenere la compatibilità con le versioni precedenti con client e origini che non supportano PackageIconancora , specificare sia PackageIcon che PackageIconUrl. Visual Studio supporta PackageIcon i pacchetti provenienti da un'origine basata su cartelle.

Compressione di un file di immagine icona

Quando si crea il pacchetto di un file di immagine icona, usare PackageIcon la proprietà per specificare il percorso del file icona, relativo alla radice del pacchetto. Assicurarsi inoltre che il file sia incluso nel pacchetto. Le dimensioni del file di immagine sono limitate a 1 MB. I formati di file supportati includono JPEG e PNG. È consigliabile una risoluzione dell'immagine di 128x128.

Ad esempio:

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

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

Esempio di icona del pacchetto.

Per l'equivalente nuspec , vedere riferimento per nuspec l'icona.

PackageReadmeFile

Supportato con NuGet 5.10.0 preview 2.NET / SDK 5.0.300 e versioni successive

Quando si esegue la compressione di un file readme, è necessario usare la PackageReadmeFile proprietà per specificare il percorso del pacchetto, rispetto alla radice del pacchetto. Oltre a questo, è necessario assicurarsi che il file sia incluso nel pacchetto. I formati di file supportati includono solo Markdown (.md).

Ad esempio:

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

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

Per l'equivalente nuspec , vedere il nuspec riferimento per readme.

Assembly di output

nuget pack copia i file di output con le estensioni .exe, .dll, .xml, .winmd, .json e .pri. I file di output copiati dipendono da ciò che MSBuild fornisce dalla BuiltOutputProjectGroup destinazione.

Esistono due MSBuild proprietà che è possibile usare nel file di progetto o nella riga di comando per controllare dove vanno gli assembly di output:

  • IncludeBuildOutput: valore booleano che determina se gli assembly di output della compilazione devono essere inclusi nel pacchetto.
  • BuildOutputTargetFolder: specifica la cartella in cui devono essere posizionati gli assembly di output. Gli assembly di output (e altri file di output) vengono copiati nelle rispettive cartelle per framework.

Riferimenti ai pacchetti

Vedere Riferimenti ai pacchetti nei file di progetto.

Riferimenti da progetto a progetto

I riferimenti da progetto a progetto vengono considerati per impostazione predefinita come NuGet riferimenti al pacchetto. Ad esempio:

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

È anche possibile aggiungere i metadati seguenti ai riferimenti del progetto:

<IncludeAssets>
<ExcludeAssets>
<PrivateAssets>

Inclusione di contenuto in un pacchetto

Per includere il contenuto, aggiungere altri metadati all'elemento <Content> esistente. Per impostazione predefinita tutti gli elementi di tipo"Content" vengono inclusi nel pacchetto, a meno che non si esegua l'override con voci simili al codice seguente:

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

Per impostazione predefinita, tutti gli elementi vengono aggiunti alla radice di content e della cartella contentFiles\any\<target_framework> all'interno di un pacchetto e viene mantenuta la struttura di cartelle relative, a meno che non si specifichi un percorso di pacchetto:

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

Se si desidera copiare tutto il contenuto in una o più cartelle radice specifiche (anziché content e contentFiles entrambe), è possibile usare la MSBuild proprietà ContentTargetFolders, che per impostazione predefinita è "content; contentFiles" ma può essere impostato su qualsiasi altro nome di cartella. Si noti che se si specifica solo "contentFiles" in ContentTargetFolders, i file vengono posizionati in contentFiles\any\<target_framework> o contentFiles\<language>\<target_framework> in base a buildAction.

PackagePath può essere un set di percorsi di destinazione delimitati da punto e virgola. Se si specifica un percorso di pacchetto vuoto, il file viene aggiunto alla radice del pacchetto. Ad esempio, il codice seguente aggiunge libuv.txt a content\myfiles, content\samples e nella radice del pacchetto:

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

Esiste anche una MSBuild proprietà $(IncludeContentInPack), che per impostazione predefinita è true. Se questa proprietà viene impostata su false in qualsiasi progetto, il contenuto da tale progetto non viene incluso nel pacchetto NuGet.

Altri metadati specifici del pacchetto che è possibile impostare su uno degli elementi precedenti includono e quali impostano CopyToOutput e Flatten i valori nella contentFiles voce nell'output nuspec.<PackageFlatten><PackageCopyToOutput>

Nota

Oltre agli elementi Content, i metadati <Pack> e <PackagePath> possono anche essere impostati nei file con l'azione di compilazione Compile, EmbeddedResource, ApplicationDefinition, Page, Resource, SplashScreen, DesignData, DesignDataWithDesignTimeCreateableTypes, CodeAnalysisDictionary, AndroidAsset, AndroidResource, BundleResource o None.

Per fare in modo che il comando pack aggiunga il nome del file al percorso del pacchetto quando si usano modelli con caratteri jolly (glob), il percorso del pacchetto deve terminare con il carattere separatore di cartella. In caso contrario, il percorso del pacchetto viene interpretato come percorso completo, incluso il nome del file.

IncludeSymbols

Quando si usa MSBuild -t:pack -p:IncludeSymbols=true, i file .pdb corrispondenti vengono copiati insieme agli altri file di output (.dll, .exe, .winmd, .xml, .json, .pri). Si noti che l'impostazione IncludeSymbols=true crea un pacchetto regolare e un pacchetto di simboli.

IncludeSource

Equivale a IncludeSymbols, ma insieme ai file .pdb vengono copiati anche i file di origine. Tutti i file di tipo Compile vengono copiati in src\<ProjectName>\ conservando la struttura di cartelle del percorso relativo nel pacchetto risultante. Lo stesso accade anche per i file di origine di qualsiasi ProjectReference con TreatAsPackageReference impostato su false.

Se un file di tipo Compile è all'esterno della cartella di progetto, viene semplicemente aggiunto a src\<ProjectName>\.

Compressione di un'espressione di licenza o di un file di licenza

Quando si usa un'espressione di licenza, usare la PackageLicenseExpression proprietà . Per un esempio, vedere Esempio di espressione di licenza.

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

Per altre informazioni sulle espressioni di licenza e sulle licenze accettate da NuGet.org, vedere metadati delle licenze.

Quando si crea il pacchetto di un file di licenza, usare PackageLicenseFile la proprietà per specificare il percorso del pacchetto, relativo alla radice del pacchetto. Assicurarsi inoltre che il file sia incluso nel pacchetto. Ad esempio:

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

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

Per un esempio, vedere Esempio di file di licenza.

Nota

È possibile specificare solo uno di PackageLicenseExpression, PackageLicenseFilee PackageLicenseUrl alla volta.

Compressione di un file senza estensione

In alcuni scenari, ad esempio durante la compressione di un file di licenza, potrebbe essere necessario includere un file senza estensione. Per motivi cronologici, NuGet e MSBuild trattare i percorsi senza estensione come directory.

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

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

File senza un esempio di estensione.

IsTool

Quando si usa MSBuild -t:pack -p:IsTool=true, tutti i file, come specificato nello scenario Assembly di output, vengono copiati nella cartella tools invece che nella cartella lib. Si noti che questo comportamento è diverso da DotNetCliTool, che viene specificato impostando PackageType nel file .csproj.

Compressione con un .nuspec file

Sebbene sia consigliabile includere tutte le proprietà in genere presenti nel .nuspec file di progetto, è possibile scegliere di usare un .nuspec file per comprimere il progetto. Per un progetto non in stile SDK che usa PackageReference, è necessario importare NuGet.Build.Tasks.Pack.targets in modo che l'attività pack possa essere eseguita. È comunque necessario ripristinare il progetto prima di poter comprimere un nuspec file. Per impostazione predefinita, un progetto in stile SDK include le destinazioni pack.

Il framework di destinazione del file di progetto è irrilevante e non viene usato per la compressione di un oggetto nuspec. Le tre MSBuild proprietà seguenti sono rilevanti per la compressione tramite un oggetto .nuspec:

  1. NuspecFile: percorso relativo o assoluto per il file .nuspec usato per la creazione del pacchetto.
  2. NuspecProperties: elenco con valori delimitati da punto e virgola di coppie chiave=valore. A causa del funzionamento MSBuild dell'analisi della riga di comando, è necessario specificare più proprietà nel modo seguente: -p:NuspecProperties="key1=value1;key2=value2".
  3. NuspecBasePath: percorso di base per il file .nuspec.

Se si usa dotnet.exe per creare il pacchetto del progetto, usare un comando simile al seguente:

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

Se si usa MSBuild per creare il pacchetto del progetto, usare un comando simile al seguente:

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

Si noti che per impostazione predefinita la creazione di un nuspec oggetto using dotnet.exe o msbuild comporta anche la compilazione del progetto. Ciò può essere evitato passando la --no-build proprietà a dotnet.exe, che è l'equivalente dell'impostazione <NoBuild>true</NoBuild> nel file di progetto, insieme all'impostazione <IncludeBuildOutput>false</IncludeBuildOutput> nel file di progetto.

Un esempio di file con estensione csproj per comprimere un nuspec file è:

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

Punti di estensione avanzati per creare un pacchetto personalizzato

La pack destinazione fornisce due punti di estensione eseguiti nella build specifica del framework di destinazione interno. I punti di estensione supportano l'inclusione di contenuto e assembly specifici del framework di destinazione in un pacchetto:

  • TargetsForTfmSpecificBuildOutput target: usare per i file all'interno della lib cartella o di una cartella specificata tramite BuildOutputTargetFolder.
  • TargetsForTfmSpecificContentInPackage target: usare per i file all'esterno di BuildOutputTargetFolder.

TargetsForTfmSpecificBuildOutput

Scrivere una destinazione personalizzata e specificarla come valore della $(TargetsForTfmSpecificBuildOutput) proprietà . Per tutti i file che devono essere inseriti in BuildOutputTargetFolder (lib per impostazione predefinita), la destinazione deve scrivere tali file in ItemGroup BuildOutputInPackage e impostare i due valori di metadati seguenti:

  • FinalOutputPath: percorso assoluto del file; se non specificato, l'identità viene usata per valutare il percorso di origine.
  • TargetPath: (Facoltativo) Impostare quando il file deve entrare in una sottocartella all'interno lib\<TargetFramework> di , ad esempio gli assembly satellite che si trovano nelle rispettive cartelle delle impostazioni cultura. Il valore predefinito è il nome del file.

Esempio:

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

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

TargetsForTfmSpecificContentInPackage

Scrivere una destinazione personalizzata e specificarla come valore della $(TargetsForTfmSpecificContentInPackage) proprietà . Per includere i file nel pacchetto, la destinazione deve scrivere tali file in ItemGroup TfmSpecificPackageFile e impostare i metadati facoltativi seguenti:

  • PackagePath: percorso in cui deve essere restituito il file nel pacchetto. NuGet genera un avviso se più file vengono aggiunti allo stesso percorso del pacchetto.
  • BuildAction: azione di compilazione da assegnare al file, obbligatoria solo se il percorso del pacchetto si trova nella contentFiles cartella . Il valore predefinito è "Nessuno".

Ad esempio,

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

Destinazione restore

MSBuild -t:restore (usato da nuget restore e dotnet restore con progetti .NET Core) consente di ripristinare i pacchetti a cui si fa riferimento nel file di progetto, come segue:

  1. Lettura di tutti i riferimenti da progetto a progetto
  2. Lettura delle proprietà del progetto per trovare la cartella intermedia e i framework di destinazione
  3. Passare MSBuild i dati a NuGet. Build.Tasks.dll
  4. Esecuzione di restore
  5. Download dei pacchetti
  6. Scrittura dei file di asset, delle destinazioni e delle proprietà

La restore destinazione funziona per i progetti usando il formato PackageReference. MSBuild 16.5+ ha anche il supporto esplicito per il packages.config formato.

Nota

La restore destinazione non deve essere eseguita in combinazione con la build destinazione.

Ripristino delle proprietà

Le impostazioni di ripristino aggiuntive possono provenire da MSBuild proprietà nel file di progetto. I valori possono essere impostati anche dalla riga di comando tramite l'opzione -p: (vedere gli esempi riportati di seguito).

Proprietà Descrizione
RestoreSources Elenco delimitato da punto e virgola delle origini di pacchetti.
RestorePackagesPath Percorso della cartella dei pacchetti dell'utente.
RestoreDisableParallel Consente di limitare i download a uno alla volta.
RestoreConfigFile Percorso per un file Nuget.Config da applicare.
RestoreNoHttpCache Se true, evita l'uso di pacchetti memorizzati nella cache HTTP. Vedere Gestione dei pacchetti globali e delle cartelle della cache.
RestoreIgnoreFailedSources Se true, ignora le origini di pacchetti in errore o mancanti.
RestoreFallbackFolders Le cartelle di fallback, usate nello stesso modo in cui viene usata la cartella dei pacchetti utente.
RestoreAdditionalProjectSources Origini aggiuntive da usare durante il ripristino.
RestoreAdditionalProjectFallbackFolders Cartelle di fallback aggiuntive da usare durante il ripristino.
RestoreAdditionalProjectFallbackFoldersExcludes Esclude le cartelle di fallback specificate in RestoreAdditionalProjectFallbackFolders
RestoreTaskAssemblyFile Percorso di NuGet.Build.Tasks.dll.
RestoreGraphProjectInput Elenco delimitato da punto e virgola dei progetti da ripristinare, che deve contenere percorsi assoluti.
RestoreUseSkipNonexistentTargets Quando i progetti vengono raccolti tramite MSBuild , determina se vengono raccolti usando l'ottimizzazione SkipNonexistentTargets . Se non è impostato, il valore predefinito è true. La conseguenza è un comportamento di errore rapido quando non è possibile importare le destinazioni di un progetto.
MSBuildProjectExtensionsPath Cartella di output, impostazione predefinita BaseIntermediateOutputPath e obj cartella.
RestoreForce Nei progetti basati su PackageReference forza la risoluzione di tutte le dipendenze anche se l'ultimo ripristino è riuscito. Specificare questo flag è simile all'eliminazione del project.assets.json file. Ciò non ignora la cache http.
RestorePackagesWithLockFile Acconsente esplicitamente all'utilizzo di un file di blocco.
RestoreLockedMode Eseguire il ripristino in modalità bloccata. Ciò significa che il ripristino non rivaluta le dipendenze.
NuGetLockFilePath Percorso personalizzato per il file di blocco. Il percorso predefinito è accanto al progetto ed è denominato packages.lock.json.
RestoreForceEvaluate Forza il ripristino per ricompilare le dipendenze e aggiornare il file di blocco senza alcun avviso.
RestorePackagesConfig Opzione di consenso esplicito che ripristina i progetti con packages.config. Supporto solo con MSBuild -t:restore .
RestoreRepositoryPath solo packages.config. Specifica la directory dei pacchetti in cui devono essere ripristinati i pacchetti. SolutionDirectory verrà utilizzato se non specificato.
RestoreUseStaticGraphEvaluation Opzione di consenso esplicito per usare la valutazione statica del grafo MSBuild anziché la valutazione standard. La valutazione statica del grafico è una funzionalità sperimentale notevolmente più veloce per repository e soluzioni di grandi dimensioni.

La ExcludeRestorePackageImports proprietà è una proprietà interna utilizzata da NuGet. Non deve essere modificato o impostato in alcun MSBuild file.

Esempi

Riga di comando:

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

File di progetto:

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

Output del ripristino

Il ripristino crea i file seguenti nella cartella obj di compilazione:

File Descrizione
project.assets.json Contiene il grafico delle dipendenze di tutti i riferimenti al pacchetto.
{projectName}.projectFileExtension.nuget.g.props Riferimenti alle MSBuild proprietà contenute nei pacchetti
{projectName}.projectFileExtension.nuget.g.targets Riferimenti alle MSBuild destinazioni contenute nei pacchetti

Ripristino e compilazione con un MSBuild unico comando

A causa del fatto che NuGet è possibile ripristinare i pacchetti che causano MSBuild destinazioni e proprietà, le valutazioni di ripristino e compilazione vengono eseguite con proprietà globali diverse. Ciò significa che quanto segue avrà un comportamento imprevedibile e spesso errato.

msbuild -t:restore,build

L'approccio consigliato è invece:

msbuild -t:build -restore

La stessa logica si applica ad altre destinazioni simili a build.

Ripristino di progetti PackageReference e packages.config con MSBuild

Con MSBuild la versione 16.5+, packages.config è supportato anche per msbuild -t:restore.

msbuild -t:restore -p:RestorePackagesConfig=true

Nota

packages.config il ripristino è disponibile solo con MSBuild 16.5+e non con dotnet.exe

Ripristino con MSBuild valutazione del grafo statico

Nota

Con MSBuild la versione 16.6+, NuGet è stata aggiunta una funzionalità sperimentale per usare la valutazione statica del grafo dalla riga di comando che migliora significativamente il tempo di ripristino per i repository di grandi dimensioni.

msbuild -t:restore -p:RestoreUseStaticGraphEvaluation=true

In alternativa, è possibile abilitarla impostando la proprietà in un oggetto Directory.Build.Props.

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

Nota

A partire da Visual Studio 2019.x e NuGet 5.x, questa funzionalità viene considerata sperimentale e accettata esplicitamente. Per informazioni dettagliate su quando questa funzionalità verrà abilitata per impostazione predefinita, seguire NuGet/Home#9803 .

Il ripristino statico del grafo modifica la parte msbuild del ripristino, la lettura e la valutazione del progetto, ma non l'algoritmo di ripristino. L'algoritmo di ripristino è lo stesso in tutti gli NuGet strumenti (NuGet.exe, MSBuild.exe, dotnet.exe e Visual Studio).

In pochissimi scenari, il ripristino statico del grafico può comportarsi in modo diverso rispetto al ripristino corrente e alcuni packageReference dichiarati o ProjectReference potrebbero non essere presenti.

Per semplificare la mente, come controllo una sola volta, quando si esegue la migrazione al ripristino statico del grafo, prendere in considerazione l'esecuzione:

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

NuGetnon deve segnalare alcuna modifica. Se viene visualizzata una discrepanza, inviare un problema in NuGet/Home.

Sostituzione di una libreria da un grafico di ripristino

Se un ripristino restituisce l'assembly errato, è possibile escludere la scelta predefinita di tali pacchetti e sostituirla con la propria scelta. Prima di tutto, con un PackageReference di livello superiore, escludere tutti gli asset:

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

Aggiungere quindi il riferimento personalizzato alla copia locale appropriata della DLL:

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