Trovare e usare una versione di MSBuild

Per assicurarsi che le compilazioni a livello di codice delle applicazioni corrispondano alle compilazioni eseguite all'interno di Visual Studio o MSBuild.exe, potrebbe essere necessario caricare la stessa versione degli assembly MSBuild installati con una versione specifica di Visual Studio e usare gli stessi SDK disponibili all'interno di tale versione di Visual Studio. In alternativa, quando si crea un'applicazione di compilazione che verrà eseguita in computer che potrebbero avere diverse versioni installate di MSBuild, .NET e Visual Studio, è anche possibile trovare e usare una versione coerente di MSBuild. Microsoft.Build.Locator API semplifica questo processo.

Usare Microsoft. Build.Locator

Microsoft. Il pacchetto Build.Locator è rilevante per situazioni in cui l'applicazione viene eseguita in computer client, macchine virtuali o all'interno di contenitori, in cui Visual Studio è installato o in ambienti in cui è installato solo Visual Studio Build Tools o solo l'SDK di .NET, ad esempio quando vengono richieste compilazioni con la riga di comando dotnet build. In ogni caso, l'applicazione deve trovare la versione desiderata di MSBuild. Tale versione di MSBuild può essere la versione corrispondente a Visual Studio, MSBuild.exeo dotnet build oppure una versione specifica coerente indipendentemente dalle diverse configurazioni del computer negli ambienti in cui è possibile usare l'applicazione.

Se si ridistribuisce Microsoft.Build.Locator.dll con l'applicazione, non è necessario distribuire altri assembly MSBuild.

L'uso dell'API del localizzatore richiede alcune modifiche nel progetto, descritte di seguito. Per un esempio delle modifiche necessarie per aggiornare un progetto, vedere i commit eseguiti in un progetto di esempio nel repository MSBuildLocator.

Modificare i riferimenti a MSBuild

Per assicurarsi che MSBuild venga caricato da una posizione centrale, non è necessario distribuire gli assembly con l'applicazione.

Il meccanismo per modificare il progetto per evitare il caricamento di MSBuild da una posizione centrale dipende dal modo in cui si fa riferimento a MSBuild.

Usare pacchetti NuGet (preferiti)

Queste istruzioni presuppongono che si usino riferimenti NuGet in stile PackageReference.

Modificare i file di progetto per fare riferimento agli assembly MSBuild dai loro pacchetti NuGet. Specificare ExcludeAssets=runtime per indicare a NuGet che gli assembly sono necessari solo in fase di compilazione e che non devono essere copiati nella directory di output.

La versione principale e secondaria dei pacchetti MSBuild deve essere minore o uguale alla versione minima di Visual Studio che si vuole supportare. Ad esempio, se si desidera supportare Visual Studio 2017 e versioni successive, fare riferimento alla versione del pacchetto 15.1.548.

Ad esempio, è possibile usare questo codice XML:

<ItemGroup>
  <PackageReference Include="Microsoft.Build" Version="15.1.548" ExcludeAssets="runtime" />
  <PackageReference Include="Microsoft.Build.Utilities.Core" Version="15.1.548" ExcludeAssets="runtime" />
</ItemGroup>

Utilizzare assembly di estensione

Se non è possibile usare pacchetti NuGet, è possibile fare riferimento agli assembly MSBuild distribuiti con Visual Studio. Per evitare che MSBuild venga copiato nella directory di output, assicurati di impostare Copy Local su False se fai riferimento direttamente a MSBuild. Nel file di progetto questa impostazione è simile al codice seguente:

    <Reference Include="Microsoft.Build, Version=15.1.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a, processorArchitecture=MSIL">
      <Private>False</Private>
    </Reference>

Verificare che l'output sia pulito

Compilare il progetto ed esaminare la directory di output per assicurarsi che non contenga assembly Microsoft.Build.*.dll diversi da Microsoft.Build.Locator.dll, aggiunti nel passaggio successivo.

Aggiungere informazioni di riferimento sul pacchetto per Microsoft. Build.Locator

Aggiungere un riferimento al pacchetto NuGet per Microsoft. Build.Locator.

    <PackageReference Include="Microsoft.Build.Locator">
      <Version>1.1.2</Version>
    </PackageReference>

Non specificare ExcludeAssets=runtime per il pacchetto Microsoft.Build.Locator.

Registrare l'istanza prima di chiamare MSBuild

Quando si crea un'applicazione di compilazione per uso generale, non si conoscono le versioni di Visual Studio, .NET e MSBuild potrebbe essere installato in un computer in cui viene eseguita l'applicazione. Lo scopo di MSBuildLocator è trovare un'installazione appropriata di MSBuild da usare nei computer con ambienti di installazione diversi. MSBuildLocator consente di specificare una logica per determinare quale MSBuild usare, ma lo sviluppatore dell'applicazione deve determinare quale versione di MSBuild richiede o può accettare oppure fornire agli utenti un modo per specificare una versione e includere la logica per tradurre tale scelta in chiamate appropriate all'API MSBuildLocator.

Il modo più semplice per aggiungere la chiamata all'API locator consiste nell'aggiungere una chiamata a MSBuildLocator.RegisterInstance nel codice di avvio dell'applicazione. Un esempio consiste nel selezionare la versione più recente, come illustrato di seguito, ma l'applicazione potrebbe avere requisiti specifici.

Non è possibile fare riferimento a tipi MSBuild (dallo spazio dei nomi Microsoft.Build) nel metodo che chiama MSBuildLocator. Ad esempio, non è possibile usare codice simile al seguente:

void ThisWillFail()
{
    // Register the most recent version of MSBuild
    RegisterInstance(MSBuildLocator.QueryVisualStudioInstances().OrderByDescending(
       instance => instance.Version).First());
    Project p = new Project(SomePath); // Could be any MSBuild type
    // Code that uses the MSBuild type
}

Scrivere invece codice simile al seguente:

void MethodThatDoesNotDirectlyCallMSBuild()
{
    var instance = ... // select which of the installed instances to use
    
    // Register a specific instance of MSBuild
    MSBuildLocator.RegisterInstance(instance);
    MethodThatCallsMSBuild();
}

void MethodThatCallsMSBuild()
{
    Project p = new Project(SomePath);
    // Code that uses the MSBuild type
}

Per specificare un'istanza di MSBuild, è possibile selezionare un risultato da MSBuildLocator.QueryVisualStudioInstances passare a MSBuildLocator.RegisterInstance usando la logica personalizzata necessaria.

Contenuti correlati

Per informazioni sulle API MSBuild, vedere le informazioni di riferimento sulle API MSBuild:

• Microsoft. Build.Evaluation
• Microsoft. Build.Execution
• Microsoft. Build.Framework
• Microsoft. Build.Logging
• Microsoft. Build.Tasks
• Microsoft. Build.Utilities