Propriedades do MSBuild

As propriedades são pares nome-valor que podem ser usados para configurar compilações. 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 cujo nome é a propriedade como 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 ASCII maiúscula ou minúscula ou sublinhado (_); os caracteres subsequentes válidos incluem caracteres alfanuméricos (letras ou dígitos ASCII), sublinhado e hífen (-).

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 de 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 para BuildDir deve ser declarado após a atribuição do valor antigo.

Propriedades reservadas

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

Para obter mais informações, consulte Como fazer referência ao nome ou 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 do ambiente

Você pode fazer referência a variáveis de ambiente em arquivos de projeto assim como faz referência a propriedades reservadas. Por exemplo, para usar a PATH variável de ambiente em seu arquivo de projeto, use $(Path). Se o projeto contém uma definição de propriedade que tem o mesmo nome de uma propriedade de ambiente, a propriedade no projeto substitui o valor da variável de ambiente.

Cada projeto MSBuild tem um bloco de ambiente isolado: ele só vê leituras e gravações em seu próprio bloco. O MSBuild só lê variáveis de ambiente quando inicializa a coleção de propriedades, antes que o arquivo de projeto seja avaliado ou criado. Depois disso, as propriedades do 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 Property System.Environment.GetEnvironmentVariable. O método preferido, no entanto, é usar o parâmetro EnvironmentVariablestask . 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 uma compilação.

Propriedades do Registro

Você pode ler os valores do Registro do sistema usando a sintaxe a seguir, onde Hive é 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 Valuearquivo .

$(registry:Hive\MyKey\MySubKey)

Esse valor do Registro pode ser usado para inicializar uma propriedade de compilação. Por exemplo, para criar uma propriedade de compilação que representa 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 recebem valores durante a fase de avaliação de uma compilação. Durante a fase de execução subsequente, as propriedades podem ser criadas ou modificadas da seguinte forma:

• 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 podem conter PropertyGroup elementos que podem conter declarações de propriedade.

Propriedades globais

MSBuild permite definir propriedades na linha de comando usando a opção -property (ou -p). Esses valores de propriedade global substituem os valores de propriedade 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 uma compilação 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 que não devem ser encaminhadas. Para obter mais informações, consulte Tarefa MSBuild.

Propriedades locais

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

Você especifica uma propriedade local usando o TreatAsLocalProperty atributo em uma tag 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 -p opção, 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 a linha de comando test1.proj e dê TreatedAsLocalProperty o valor GlobalOverrideValueglobal :

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

O resultado é o 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 locais e importações

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

O exemplo de código a seguir mostra o efeito de TreatAsLocalProperty em 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.props -->
<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 a seguinte maneira:

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

A saída é:

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

Agora suponha que você construa 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 onde 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 onde TreatAsLocalProperty é usado.

Para obter mais informações, consulte Project element (MSBuild) e How to: Build the same source files with different options.

Funções de propriedade

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

Você pode usar métodos string (instance) 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 compilação para 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 na passagem de valores para tarefas ou na exibição de 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. MSBuild substitui as referências de propriedade usando seus respetivos valores de propriedade. Os valores de propriedade são atribuídos na ordem em que aparecem. Portanto, neste exemplo, $(MySupportedVersion), $(MyRequiredVersion), e $(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 uma compilação
• Como: Fazer referência ao nome ou local do arquivo de projeto
• Como: Criar os mesmos arquivos de origem com opções diferentes
• MSBuild propriedades reservadas e bem conhecidas
• Elemento Property (MSBuild)