Configurare destinazioni e attività

Le attività MSBuild selezionate possono essere impostate per l'esecuzione nell'ambiente di destinazione, quando il computer di sviluppo supporta l'ambiente di destinazione. Ad esempio, quando si usa un computer Windows a 64 bit per compilare un'applicazione destinata a un'architettura Windows a 32 bit, le attività selezionate vengono eseguite in un processo a 32 bit.

Uso degli attributi e dei parametri dell'attività UsingTask

Gli attributi seguenti UsingTask influiscono su tutte le operazioni di un'attività in un processo di compilazione specifico:

• L'attributoRuntime, se presente, imposta la versione CLR (Common Language Runtime) e può accettare uno di questi valori: CLR2, CLR4CurrentRuntime, , NET (a partire da .NET SDK 10/Visual Studio 2026/MSBuild 18.0) o * (qualsiasi runtime).

• L'attributo Architecture , se presente, imposta la piattaforma e il bitness e può accettare uno di questi valori: x86, x64, CurrentArchitectureo * (qualsiasi architettura).

• L'attributo TaskFactory , se presente, imposta la factory delle attività che crea ed esegue l'istanza dell'attività e accetta solo il valore TaskHostFactory. Per altre informazioni, vedere Task factory più avanti in questo documento.

<UsingTask TaskName="SimpleTask"
    Runtime="CLR2"
    Architecture="x86"
    AssemblyFile="$(MSBuildToolsPath)\Microsoft.Build.Tasks.Core.dll" />

È anche possibile usare i MSBuildRuntime parametri e MSBuildArchitecture per impostare il contesto di destinazione di una singola chiamata a un'attività.

<Project>
    <Target Name="MyTarget">
        <SimpleTask MSBuildRuntime="CLR2" MSBuildArchitecture= "x86"/>
    </Target>
</Project>

Prima che MSBuild esegua un'attività, cerca una corrispondenza UsingTask con lo stesso contesto di destinazione. I parametri specificati in UsingTask ma non nell'attività corrispondente vengono considerati corrispondenti. I parametri specificati nell'attività ma non nell'oggetto corrispondente UsingTask vengono considerati corrispondenti. Se i valori dei parametri non vengono specificati in UsingTask o nell'attività, i valori predefiniti * sono (qualsiasi parametro).

Se i parametri sono impostati nell'attività, MSBuild tenta di trovare un oggetto UsingTask che corrisponda a questi parametri o, almeno, non è in conflitto con tali parametri. Più di uno UsingTask può specificare il contesto di destinazione della stessa attività. Ad esempio, un'attività con file eseguibili diversi per ambienti di destinazione diversi potrebbe essere simile a quella seguente:

<UsingTask TaskName="MyTool"
    Runtime="CLR2"
    Architecture="x86"
    AssemblyFile="$(MyToolsPath)\MyTool.v2.0.dll" />

<UsingTask TaskName="MyTool"
    Runtime="CLR4"
    Architecture="x86"
    AssemblyFile="$(MyToolsPath)\MyTool.4.0.dll" />

<Project>
    <Target Name="MyTarget">
        <MyTool MSBuildRuntime="CLR2" MSBuildArchitecture= "x86"/>
    </Target>
</Project>

Override dell'impostazione predefinita UsingTasks

Per impostazione predefinita, MSBuild gestisce UsingTask come "first one wins". A partire dalla versione 17.2, MSBuild supporta l'override di questo comportamento tramite il Override parametro . Un oggetto UsingTask con il parametro Override impostato su true assume la priorità su qualsiasi altro UsingTask dello stesso TaskName.

<UsingTask TaskName="MyTool"
    Runtime="CLR4"
    Architecture="x86"
    Override="true"
    AssemblyFile="$(MyToolsPath)\MyTool.4.0.dll" />

Task factory

La tabella seguente illustra le task factory fornite dall'installazione di MSBuild:

Il meccanismo della factory delle attività è estendibile, quindi è anche possibile usare quelli creati da terze parti o crearne di personalizzati. Un motivo per crearne uno sarebbe quello di supportare un'altra lingua per la scrittura di attività inline.

TaskHostFactory

Prima di eseguire un'attività, MSBuild verifica se è designato per l'esecuzione nel contesto software corrente. Se l'attività è così designata, MSBuild lo passa a AssemblyTaskFactory, che lo esegue nel processo corrente; in caso contrario, MSBuild passa l'attività a TaskHostFactory, che esegue l'attività in un processo che corrisponde al contesto di destinazione. Anche se il contesto corrente e il contesto di destinazione corrispondono, è possibile forzare l'esecuzione di un'attività (per isolamento, sicurezza o altri motivi) impostando TaskFactory su TaskHostFactory.

<UsingTask TaskName="MisbehavingTask"
    TaskFactory="TaskHostFactory"
    AssemblyFile="$(MSBuildToolsPath)\MyTasks.dll">
</UsingTask>

Quando TaskHostFactory viene specificato in modo esplicito, il processo che esegue l'attività è di breve durata. In questo modo il sistema operativo può pulire tutte le risorse correlate all'attività immediatamente dopo l'esecuzione. Per questo motivo, specificare TaskHostFactory quando si fa riferimento alle attività compilate nello stesso processo di compilazione usato, per evitare errori di utilizzo dei file durante l'aggiornamento dell'assembly attività dopo una compilazione.

RoslynCodeTaskFactory

RoslynCodeTaskFactory fornisce un meccanismo in base al quale è possibile scrivere codice C# o Visual Basic per un'attività in un file di progetto per un uso immediato. Il codice viene compilato durante il processo di compilazione per produrre un'attività che è possibile eseguire nella stessa compilazione. Il codice scritto è destinato a .NET Standard, quindi può essere usato durante l'esecuzione dotnet builddi , che usa la versione .NET Core (e .NET 5 e successive) di MSBuild, nonché msbuild.exe, che usa .NET Framework. RoslynCodeTaskFactory è ideale per la personalizzazione che è un po 'troppo difficile da eseguire nella logica di MSBuild, ma non abbastanza complesso per creare un progetto separato. Vedere Creare un'attività inline di MSBuild con RoslynCodeTaskFactory.

CodeTaskFactory

CodeTaskFactory è una versione precedente di RoslynCodeTaskFactory limitata alla versione .NET Framework di MSBuild. Vedere Attività inline di MSBuild. Questa factory di attività è supportata, ma il codice più recente deve essere usato per un'applicabilità RoslynCodeTaskFactory più ampia.

TaskHosts in MSBuild

MSBuild esegue attività come parte del processo di compilazione e talvolta tali attività richiedono l'esecuzione in un contesto di runtime o architettura diverso rispetto al processo di compilazione predefinito. A tale scopo, MSBuild può usare un "TaskHost", ovvero un processo MSBuild separato responsabile dell'esecuzione di attività nell'ambiente richiesto. TaskHosts garantisce isolamento, compatibilità e supporto per la destinazione di framework o piattaforme diversi.

In passato, TaskHosts consentiva l'esecuzione di attività in processi .NET Framework separati di versioni specifiche, ad esempio CLR2 o CLR4. Questo supporto è stato regolato dagli attributi Runtime e Architecture dell'elemento <UsingTask> nel file di progetto o nel file di destinazione.

• Architecture può specificare valori come x86, x64, CurrentArchitectureo * per "qualsiasi architettura".
• Runtime può specificare valori come CLR2, CLR4e (di recente) NET o CurrentRuntime.

Per la maggior parte delle attività di MSBuild, il processo predefinito è sufficiente. Tuttavia, per le attività personalizzate o più avanzate, in particolare quelle con dipendenze specifiche della piattaforma, TaskHosts sblocca la compatibilità e la flessibilità avviando automaticamente un runtime appropriato.

Utilizzo di .NET TaskHost

Con la versione di .NET 10 SDK e Visual Studio 2026, MSBuild ha introdotto il supporto per un .NET TaskHost. Questa funzionalità consente a MSBuild di eseguire attività che devono usare un runtime .NET in un processo .NET separato. Questa opzione viene abilitata tramite l'attributo Runtime="NET" nell'elemento <UsingTask> :

<UsingTask TaskName="MyNetTask"
           Runtime="NET"
           AssemblyFile="path\to\task.dll" />

Quando questo attributo è impostato:

• MSBuild gestisce automaticamente un pool di processi TaskHost .NET ed esegue l'attività specificata in un nodo del pool.
• Le attività possono sfruttare le API o le librerie esclusive dei runtime .NET moderni.
• L'isolamento protegge il processo di compilazione da conflitti tra dipendenze o versioni.

Se si spediscono destinazioni che devono usare set di strumenti MSBuild meno recenti, è possibile selezionare in modo condizionale una UsingTask definizione in base alla versione corrente di MSBuild (e, se applicabile, $(MSBuildRuntimeType)):

<UsingTask TaskName="MyTask"
           Runtime="NET"
           AssemblyFile="my/net/tasks.dll"
           Condition="$([MSBuild]::VersionGreaterThanOrEquals('$(MSBuildVersion)', '18.0'))" />

<UsingTask TaskName="MyTask"
           Runtime="CLR4"
           AssemblyFile="my/netframework/tasks.dll"
           Condition="!$([MSBuild]::VersionGreaterThanOrEquals('$(MSBuildVersion)', '18.0')) and '$(MSBuildRuntimeType)' == 'Full'" />

Perché usare .NET TaskHost?

• Accesso alle API .NET moderne: .NET TaskHost consente alle attività di usare funzionalità e librerie disponibili solo nelle versioni recenti di .NET.
• Compatibilità migliorata: La separazione dell'esecuzione delle attività può evitare conflitti di controllo delle versioni e dipendenze.
• Correzione futura: Si intende espandere ulteriormente il supporto di TaskHost e unificare la logica SDK/resolver (vedere dotnet/msbuild#12895 per il lavoro in corso).

Parametri dell'attività fantasma

Come qualsiasi altro parametro MSBuildRuntime dell'attività e MSBuildArchitecture può essere impostato dalle proprietà di compilazione.

<Project>
    <PropertyGroup>
        <FrameworkVersion>3.0</FrameworkVersion>
    </PropertyGroup>
    <Target Name="MyTarget">
        <SimpleTask MSBuildRuntime="$(FrameworkVersion)" MSBuildArchitecture= "x86"/>
    </Target>
</Project>

A differenza di altri parametri di attività e MSBuildRuntimeMSBuildArchitecture non sono evidenti per l'attività stessa. Per scrivere un'attività che riconosce il contesto in cui viene eseguita, è necessario testare il contesto chiamando .NET Framework oppure usare le proprietà di compilazione per passare le informazioni di contesto tramite altri parametri dell'attività.

I MSBuildRuntime parametri e MSBuildArchitecture forniscono il modo più flessibile per impostare il contesto di destinazione, ma anche il più limitato nell'ambito. Da un lato, poiché sono impostati nell'istanza dell'attività stessa e non vengono valutati fino a quando l'attività non sta per essere eseguita, possono derivare il loro valore dall'ambito completo delle proprietà disponibili sia in fase di valutazione che in fase di compilazione. D'altra parte, questi parametri si applicano solo a una particolare istanza di un'attività in una determinata destinazione.

Contenuti correlati

• Configurare destinazioni e attività
• Elemento UsingTask