Como usar SDKs de projeto do MSBuild

  • Artigo

Para fazer referência a toda a infraestrutura de build necessária para uma pilha de tecnologia de desenvolvimento, como o SDK do .NET, basta fazer referência a um conjunto de propriedades e destinos conhecidos coletivamente como SDK de projeto por sua ID específica. A ID faz referência a um conjunto específico de arquivos .props que contêm definições de propriedade e arquivos .targets que contêm definições de destino. Você faz referência a um SDK de projeto usando o atributo Sdk no Node do projeto de nível superior.

<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
        <TargetFramework>net46</TargetFramework>
    </PropertyGroup>
</Project>

Durante a avaliação do projeto, o MSBuild adiciona importações implícitas nas partes superior e inferior do arquivo de projeto:

<Project>
    <!-- Implicit top import -->
    <Import Project="Sdk.props" Sdk="Microsoft.NET.Sdk" />

    <PropertyGroup>
        <TargetFramework>net46</TargetFramework>
    </PropertyGroup>

    <!-- Implicit bottom import -->
    <Import Project="Sdk.targets" Sdk="Microsoft.NET.Sdk" />
</Project>

Existem muitos SDKs distribuídos pela Microsoft. O SDK do projeto referenciado no exemplo anterior tem o moniker Microsoft.NET.Sdk. Os SDKs do projeto associados ao .NET Core e ao .NET 5 e posteriores estão listados em Visão geral do SDK do projeto .NET.

Referenciar um SDK de projeto

Há três maneiras de referenciar um SDK de projeto:

Usar o atributo Sdk no elemento <Project/>

<Project Sdk="My.Custom.Sdk">
    ...
</Project>

Uma importação implícita é adicionada às partes superior e inferior do projeto, conforme descrito anteriormente.

Para especificar uma versão do SDK, anexe-a ao atributo Sdk:

<Project Sdk="My.Custom.Sdk/1.2.3">
    ...
</Project>

Usar o elemento <Sdk/> de nível superior

<Project>
    <Sdk Name="My.Custom.Sdk" Version="1.2.3" />
    ...
</Project>

Uma importação implícita é adicionada às partes superior e inferior do projeto, conforme descrito anteriormente.

O atributo Version não é obrigatório.

Usar o elemento <Import/> em qualquer lugar no projeto

<Project>
    <PropertyGroup>
        <MyProperty>Value</MyProperty>
    </PropertyGroup>
    <Import Project="Sdk.props" Sdk="My.Custom.Sdk" />
    ...
    <Import Project="Sdk.targets" Sdk="My.Custom.Sdk" />
</Project>

Ao incluir explicitamente as importações no projeto, você tem controle total sobre a ordem.

Ao usar o elemento <Import/>, você também pode especificar um atributo Version opcional. Por exemplo, você pode especificar <Import Project="Sdk.props" Sdk="My.Custom.Sdk" Version="1.2.3" />.

Aviso

Caso você altere o projeto para usar elementos <Import/>, adicione as importações .props e .targets, e remova o SDK do elemento <Project/> e dos elementos <Sdk/>. Se isso não for feito, importações serão duplicadas e um aviso MSB4011 será emitido.

Como os SDKs de projeto são resolvidos

Ao avaliar a importação, o MSBuild resolve dinamicamente o caminho para o SDK de projeto com base no nome e na versão especificados. O MSBuild também tem uma lista de resolvedores de SDK registrados, que são plug-ins que localizam SDKs de projeto no seu computador. Os plug-ins incluem:

  • Um resolvedor baseado em NuGet que consulta os feeds de pacotes configurados para pacotes do NuGet que correspondem à ID e à versão do SDK que você especificou.

    Esse resolvedor só estará ativo se você tiver especificado uma versão opcional. Ele pode ser usado para qualquer SDK de projeto personalizado.

  • Um resolvedor do SDK do .NET que resolva os SDKs do MSBuild instalados com o SDK do .NET.

    Esse resolvedor localiza SDKs de projeto, como Microsoft.NET.Sdk e Microsoft.NET.Sdk.Web, que fazem parte do produto.

  • Um resolvedor padrão que resolve SDKs instalados com o MSBuild.

O resolvedor de SDK baseado em NuGet dá suporte à especificação de uma versão no arquivo global.json, a qual permite que você controle a versão do SDK do projeto em um único local e não em cada projeto individual:

{
    "msbuild-sdks": {
        "My.Custom.Sdk": "5.0.0",
        "My.Other.Sdk": "1.0.0-beta"
    }
}

Somente uma versão de cada SDK de projeto pode ser usada durante uma compilação. Se você referenciar duas versões diferentes do mesmo SDK do projeto, o MSBuild emitirá um aviso. É recomendável não especificar uma versão nos projetos caso uma versão esteja especificada no arquivo global.json.

Conteúdo relacionado