Propriedades do MSBuild

As propriedades são pares nome-valor que podem ser usados para configurar builds. As propriedades são úteis para passar valores para tarefas, avaliar condições e armazenar valores que serão referenciados em todo o arquivo de projeto.

Definir e referenciar propriedades em um arquivo de projeto

As propriedades são declaradas criando um elemento que tem o nome da propriedade como um filho de um elemento PropertyGroup. Por exemplo, o XML a seguir cria uma propriedade chamada BuildDir que tem um valor de Build.

<PropertyGroup>
    <BuildDir>Build</BuildDir>
</PropertyGroup>

Os nomes de propriedade válidos começam com uma letra maiúscula ou minúscula ou sublinhado (_); os caracteres subsequentes válidos incluem caracteres alfanuméricos (letras ou dígitos), sublinhado e hifen (-).

Em todo o arquivo de projeto, as propriedades são referenciadas usando a sintaxe $(<PropertyName>). Por exemplo, a propriedade no exemplo anterior é referenciada usando $(BuildDir).

Os valores da propriedade podem ser alterados redefinindo a propriedade. A BuildDir propriedade pode receber um novo valor usando este XML:

<PropertyGroup>
    <BuildDir>Alternate</BuildDir>
</PropertyGroup>

As propriedades são avaliadas na ordem em que aparecem no arquivo de projeto. O novo valor deve BuildDir ser declarado após a atribuição do valor antigo.

Propriedades reservadas

O MSBuild reserva alguns nomes de propriedade para armazenar informações sobre o arquivo de projeto e os binários do MSBuild. Essas propriedades são referenciadas usando a notação $, assim como qualquer outra propriedade. Por exemplo, $(MSBuildProjectFile) retorna o nome de arquivo completo do arquivo de projeto, incluindo a extensão de nome de arquivo.

Para saber mais, confira Como referenciar o nome ou o local do arquivo de projeto e Propriedades reservadas e conhecidas do MSBuild.

Propriedades internas do MSBuild

As propriedades definidas em arquivos de importação padrão que começam com um sublinhado (_) são privadas para o MSBuild e não devem ser lidas, redefinidas ou substituídas no código do usuário.

Propriedades de ambiente

Você pode referenciar variáveis de ambiente em arquivos de projeto assim como referenciar propriedades reservadas. Por exemplo, para usar a variável de PATH ambiente no arquivo de projeto, use $(Path). Se o projeto contiver uma definição de propriedade que tenha o mesmo nome de uma propriedade de ambiente, a propriedade no projeto substituirá o valor da variável de ambiente.

Cada projeto do MSBuild tem um bloco de ambiente isolado: ele só vê leituras e gravações em seu próprio bloco. O MSBuild lê somente variáveis de ambiente quando inicializa a coleção de propriedades, antes que o arquivo de projeto seja avaliado ou compilado. Depois disso, as propriedades de ambiente são estáticas, ou seja, cada ferramenta gerada começa com os mesmos nomes e valores.

Para obter o valor atual das variáveis de ambiente de dentro de uma ferramenta gerada, use as funções de propriedade System.Environment.GetEnvironmentVariable. O método preferencial, no entanto, é usar o parâmetro EnvironmentVariablesde tarefa. As propriedades de ambiente definidas nessa matriz de cadeia de caracteres podem ser passadas para a ferramenta gerada sem afetar as variáveis de ambiente do sistema.

Para obter mais informações, consulte Como usar variáveis de ambiente em um build.

Propriedades do Registro

Você pode ler valores do registro do sistema usando a sintaxe a seguir, onde Hive está o hive do Registro (por exemplo, HKEY_LOCAL_MACHINE), MyKey é o nome da chave, MySubKey é o nome da subchave e Value é o valor da subchave.

$(registry:Hive\MyKey\MySubKey@Value)

Para obter o valor de subchave padrão, omita o Value.

$(registry:Hive\MyKey\MySubKey)

Esse valor do Registro pode ser usado para inicializar uma propriedade de build. Por exemplo, para criar uma propriedade de build que represente a home page do navegador da Web do Visual Studio, use este código:

<PropertyGroup>
  <VisualStudioWebBrowserHomePage>
    $(registry:HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\14.0\WebBrowser@HomePage)
  </VisualStudioWebBrowserHomePage>
<PropertyGroup>

Criar propriedades durante a execução

As propriedades posicionadas fora Target dos elementos são valores atribuídos durante a fase de avaliação de um build. Durante a fase de execução subsequente, as propriedades podem ser criadas ou modificadas da seguinte maneira:

• Uma propriedade pode ser emitida por qualquer tarefa. Para emitir uma propriedade, o elemento Task deve ter um elemento Output filho que tenha um PropertyName atributo.

• Uma propriedade pode ser emitida pela tarefa CreateProperty . Esse uso foi preterido.

• Target os elementos podem conter PropertyGroup elementos que podem conter declarações de propriedade.

Propriedades globais

O MSBuild permite que você defina propriedades na linha de comando usando a opção -property (ou -p). Esses valores de propriedade global substituem valores de propriedade que são definidos no arquivo de projeto. Isso inclui propriedades de ambiente, mas não inclui propriedades reservadas, que não podem ser alteradas.

O exemplo a seguir define a propriedade global Configuration como DEBUG.

msbuild.exe MyProj.proj -p:Configuration=DEBUG

As propriedades globais também podem ser definidas ou modificadas para projetos filho em um build de vários projetos usando o Properties atributo da tarefa MSBuild. As propriedades globais também são encaminhadas para projetos filho, a menos que o RemoveProperties atributo da tarefa MSBuild seja usado para especificar a lista de propriedades a não serem encaminhadas. Para obter mais informações, consulte a tarefa MSBuild.

Propriedades locais

As propriedades locais podem ser redefinidas em um projeto. As propriedades globais não podem. Quando uma propriedade local é definida da linha de comando com a opção -p , a configuração no arquivo de projeto tem precedência sobre a linha de comando.

Especifique uma propriedade local usando o TreatAsLocalProperty atributo em uma marca de projeto.

O código a seguir especifica que duas propriedades são locais:

<Project Sdk="Microsoft.Net.Sdk" TreatAsLocalProperty="Prop1;Prop2">

As propriedades locais não são encaminhadas para projetos filho em uma compilação de vários projetos. Se você fornecer um valor na linha de comando com a opção -p , os projetos filho receberão o valor da propriedade global em vez do valor local alterado no projeto pai, mas o projeto filho (ou qualquer uma de suas importações) também poderá alterá-lo com seu próprio TreatAsLocalProperty.

Exemplo com propriedades locais

O exemplo de código a seguir demonstra o efeito de TreatAsLocalProperty:

<!-- test1.proj -->
<Project TreatAsLocalProperty="TreatedAsLocalProp">
    <PropertyGroup>
        <TreatedAsLocalProp>LocalOverrideValue</TreatedAsLocalProp>
    </PropertyGroup>

    <Target Name="Go">
        <MSBuild Projects="$(MSBuildThisFileDirectory)\test2.proj" Targets="Go2" Properties="Inner=true" />
    </Target>

    <Target Name="Go2" BeforeTargets="Go">
        <Warning Text="TreatedAsLocalProp($(MSBuildThisFileName)): $(TreatedAsLocalProp)" />
    </Target>
</Project>

<!-- test2.proj -->
<Project TreatAsLocalProperty="TreatedAsLocalProp">
    <Target Name="Go2">
        <Warning Text="TreatedAsLocalProp($(MSBuildThisFileName)): $(TreatedAsLocalProp)" />
    </Target>
</Project>

Suponha que você crie uma linha de comando test1.proj e dê TreatedAsLocalProperty o valor GlobalOverrideValueglobal:

dotnet msbuild .\test1.proj -p:TreatedAsLocalProp=GlobalOverrideValue

A saída é a seguinte:

test1.proj(11,9): warning : TreatedAsLocalProp(test): LocalOverrideValue
test2.proj(3,9): warning : TreatedAsLocalProp(test2): GlobalOverrideValue

O projeto filho herda o valor global, mas o projeto pai usa a propriedade definida localmente.

Propriedades e importações locais

Quando TreatAsLocalProperty o atributo é usado no projeto importado, a ordem é importante ao considerar qual valor a propriedade obtém.

O exemplo de código a seguir mostra o efeito de TreatAsLocalProperty um projeto importado:

<!-- importer.proj -->
<Project>
    <PropertyGroup>
        <TreatedAsLocalProp>FirstOverrideValue</TreatedAsLocalProp>
    </PropertyGroup>

    <Import Project="import.props" />

    <PropertyGroup>
        <TreatedAsLocalProp Condition=" '$(TrySecondOverride)' == 'true' ">SecondOverrideValue</TreatedAsLocalProp>
    </PropertyGroup>

    <Target Name="Go">
        <Warning Text="TreatedAsLocalProp($(MSBuildThisFileName)): $(TreatedAsLocalProp)" />
    </Target>
</Project>

<!-- import.proj -->
<Project TreatAsLocalProperty="TreatedAsLocalProp">
    <PropertyGroup>
        <TreatedAsLocalProp>ImportOverrideValue</TreatedAsLocalProp>
    </PropertyGroup>

    <!-- Here, TreatedAsLocalProp has the value "ImportOverrideValue"-->
</Project>

Suponha que você crie importer.proj e defina um valor global para TreatedAsLocalProp o seguinte:

dotnet msbuild .\importer.proj -p:TreatedAsLocalProp=GlobalOverrideValue

A saída é:

importer.proj(9,9): warning : TreatedAsLocalProp(importer.proj): GlobalOverrideValue

Agora suponha que você crie com a propriedade TrySecondOverride para true:

dotnet msbuild .\importer.proj -p:TreatedAsLocalProp=GlobalOverrideValue -p:TrySecondOverride=true

A saída é:

importer.proj(13,9): warning : TreatedAsLocalProp(importer.proj): SecondOverrideValue

O exemplo mostra que a propriedade é tratada como local após o projeto importado em que o TreatAsLocalProperty atributo foi usado, não apenas dentro do arquivo importado. O valor da propriedade é afetado pelo valor de substituição global, mas somente antes do projeto importado em que TreatAsLocalProperty é usado.

Para obter mais informações, consulte o elemento Project (MSBuild) e Como criar os mesmos arquivos de origem com opções diferentes.

Funções de propriedade

A partir do .NET Framework versão 4, você pode usar funções de propriedade para avaliar os scripts do MSBuild. Você pode ler o tempo do sistema, comparar cadeias de caracteres, corresponder a expressões regulares e executar muitas outras ações no script de build sem usar tarefas do MSBuild.

Você pode usar métodos de cadeia de caracteres (instância) para operar em qualquer valor de propriedade e pode chamar os métodos estáticos de muitas classes do sistema. Por exemplo, você pode definir uma propriedade de build como a data de hoje da seguinte maneira.

<Today>$([System.DateTime]::Now.ToString("yyyy.MM.dd"))</Today>

Para obter mais informações e uma lista de funções de propriedade, consulte Funções de propriedade.

Armazenar XML em propriedades

As propriedades podem conter XML arbitrário, o que pode ajudar a passar valores para tarefas ou exibir informações de log. O exemplo a seguir mostra a ConfigTemplate propriedade, que tem um valor que contém XML e outras referências de propriedade. O MSBuild substitui as referências de propriedade usando seus respectivos valores de propriedade. Os valores de propriedade são atribuídos na ordem em que aparecem. Portanto, neste exemplo, $(MySupportedVersion)e $(MyRequiredVersion)$(MySafeMode) já deveria ter sido definido.

<PropertyGroup>
    <ConfigTemplate>
        <Configuration>
            <Startup>
                <SupportedRuntime
                    ImageVersion="$(MySupportedVersion)"
                    Version="$(MySupportedVersion)"/>
                <RequiredRuntime
                    ImageVersion="$(MyRequiredVersion)"
                    Version="$(MyRequiredVersion)"
                    SafeMode="$(MySafeMode)"/>
            </Startup>
        </Configuration>
    </ConfigTemplate>
</PropertyGroup>

Conteúdo relacionado

• conceitos do MSBuild
• MSBuild
• Como usar variáveis de ambiente em um build
• Como fazer referência ao nome ou local do arquivo de projeto
• Como criar os mesmos arquivos de origem com opções diferentes
• Propriedades reservadas e conhecidas do MSBuild
• Elemento Property (MSBuild)