MSBuild .props e .targets in un pacchetto

Articolo
10/23/2023

In aggiunta agli assembly più tradizionali, i pacchetti NuGet possono talvolta aggiungere destinazioni o proprietà di compilazione personalizzate ai progetti che utilizzano tale pacchetto. A tale scopo, è possibile aggiungere un file MSBuild valido, nel formato <package_id>.targets o <package_id>.props ( ad esempio Contoso.Utility.UsefulStuff.targets) all'interno delle cartelle di compilazione del progetto.

Compilare cartelle

Man mano che NuGet si è evoluto, sono state aggiunte diverse cartelle per la compilazione .props e .targets .

Folder	Versione di NuGet	Utilizzo
build	2.5+	Compilare la logica per ogni framework di un progetto.
buildMultiTargeting	4.0+	Compilare la logica per i `outer build` progetti destinati a più framework. Solo PackageReference.
buildTransitive	5.0+	Compilare la logica per gli asset che passano transitivamente a qualsiasi progetto che utilizza. Vedere la pagina delle funzionalità. Solo PackageReference.

Cartella di compilazione specifica del framework

Tutte e 3 le cartelle di compilazione seguono lo stesso modello per decidere il file più adatto in base al framework di destinazione del progetto.

I file nella cartella build/<package_id>.targets di compilazione radice e build/<package_id>.props sono considerati adatti per tutti i framework di destinazione.

Per indicare file specifici del framework, inserirli prima nelle sottocartelle appropriate, come di seguito:

    \build
        \netstandard1.4
            \Contoso.Utility.UsefulStuff.props
            \Contoso.Utility.UsefulStuff.targets
        \net462
            \Contoso.Utility.UsefulStuff.props
            \Contoso.Utility.UsefulStuff.targets

Preferire l'uso di cartelle di compilazione specifiche del framework quando appropriato per evitare installazioni false positive nei progetti che potrebbero non essere supportati dal pacchetto.

Si noti che se un pacchetto non contiene file nelle lib cartelle o ref e solo i file in una cartella di compilazione specifica del framework, tale pacchetto verrà considerato compatibile con tutti i progetti. Le versioni aggiornate degli strumenti pack generano l'avviso NU5127 quando tali pacchetti vengono creati.

Progetti che usano pacchetti con file di compilazione

Progetti PackageReference

.props e .targets non vengono aggiunti al file di progetto, ma vengono resi disponibili tramite {projectName}.nuget.g.targets e {projectName}.nuget.g.props. Questi file vengono generati automaticamente quando viene eseguito il ripristino.

Quando un progetto è destinato a più framework, le importazioni in questi file vengono condizionali nel nome del framework di destinazione.

I file e .targets MSBuild .props per la destinazione multi framework possono essere inseriti nella \buildMultiTargeting cartella . Quando vengono generate le importazioni, viene impostata una condizione che la proprietà $(TargetFramework) MSBuild sia vuota.

Progetti packages.config

Quando installa un pacchetto con i file \build, NuGet aggiunge elementi <Import> di MSBuild nel file di progetto che puntano ai file .targets e .props. (.props viene aggiunto nella parte superiore del file di progetto; .targets viene aggiunto nella parte inferiore. Viene aggiunto un elemento MSBuild <Import> condizionale separato per ogni framework di destinazione.

Creazione di pacchetti con proprietà e destinazioni MSBuild

È possibile usare uno degli strumenti seguenti per includere MSBuild .props e .targets nel pacchetto.

Linee guida per il contenuto delle proprietà e delle destinazioni di MSBuild

NuGet non limita il modo in cui si crea .props e .targets in quanto variano in base alla necessità dell'autore del pacchetto e dei progetti di destinazione stessi.

Esistono alcuni aspetti che non devono essere eseguiti nei pacchetti' .props e .targets, ad esempio non specificando proprietà ed elementi che influiscono sul ripristino, in quanto verranno esclusi automaticamente.

Alcuni esempi di proprietà che non devono essere aggiunte o aggiornate: TargetFramework, TargetFrameworkMoniker, TargetPlatformMoniker, AssetTargetFallback e così via.
Alcuni esempi di elementi che non devono essere aggiunti o aggiornati: PackageReference, PackageVersion, PackageDownload e così via.