Properties1 do MSBuildMSBuild Properties1

Note

Este artigo se aplica ao Visual Studio 2015.This article applies to Visual Studio 2015. Se você estiver procurando a documentação do Visual Studio 2017, use o seletor de versão na parte superior esquerda.If you're looking for Visual Studio 2017 documentation, use the version selector at the top left. É recomendável atualizar para o Visual Studio 2017.We recommend upgrading to Visual Studio 2017. Baixe-o aqui.Download it here.

Propriedades são pares nome-valor que podem ser usados para configurar compilações.Properties are name-value pairs that can be used to configure builds. Propriedades são úteis para passar valores para tarefas, avaliar condições e armazenar os valores que serão referenciados em todo o arquivo de projeto.Properties are useful for passing values to tasks, evaluating conditions, and storing values that will be referenced throughout the project file.

Definindo e referenciando propriedades em um arquivo de projetoDefining and Referencing Properties in a Project File

As propriedades são declaradas com a criação de um elemento que tem o nome da propriedade como um filho de um elemento PropertyGroup.Properties are declared by creating an element that has the name of the property as a child of a PropertyGroup element. Por exemplo, o XML a seguir cria uma propriedade chamada BuildDir que tem um valor de Build.For example, the following XML creates a property named BuildDir that has a value of Build.

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

Em todo o arquivo de projeto, as propriedades são referenciadas usando a sintaxe $(PropertyName).Throughout the project file, properties are referenced by using the syntax $(PropertyName). Por exemplo, a propriedade no exemplo anterior é referenciada usando $(BuildDir).For example, the property in the previous example is referenced by using $(BuildDir).

Os valores de propriedade podem ser alterados redefinindo a propriedade.Property values can be changed by redefining the property. A propriedade BuildDir pode receber um novo valor usando este XML:The BuildDir property can be given a new value by using this XML:

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

Todas as propriedades são avaliadas na ordem em que aparecem no arquivo de projeto.Properties are evaluated in the order in which they appear in the project file. O novo valor de BuildDir deve ser declarado depois que o valor antigo for atribuído.The new value for BuildDir must be declared after the old value is assigned.

Propriedades ReservadasReserved Properties

O MSBuild reserva alguns nomes de propriedade para armazenar informações sobre o arquivo de projeto e os binários do MSBuild.MSBuild reserves some property names to store information about the project file and the MSBuild binaries. Essas propriedades são referenciadas com a notação $ como qualquer outra propriedade.These properties are referenced by using the $ notation, just like any other property. Por exemplo, $(MSBuildProjectFile) retorna o nome de arquivo completo do arquivo de projeto, incluindo a extensão de nome de arquivo.For example, $(MSBuildProjectFile) returns the complete file name of the project file, including the file name extension.

Para obter mais informações, consulte Como referenciar o nome ou o local do arquivo de projeto e Propriedades reservadas e conhecidas do MSBuild.For more information, see How to: Reference the Name or Location of the Project File and MSBuild Reserved and Well-Known Properties.

Propriedades de ambienteEnvironment Properties

Você pode referenciar variáveis de ambiente em arquivos de projeto da mesma maneira que as propriedades reservadas.You can reference environment variables in project files just as you reference reserved properties. Por exemplo, para usar a variável de ambiente PATH em seu arquivo de projeto, use $(Path).For example, to use the PATH environment variable in your project file, use $(Path). Se o projeto contiver uma definição de propriedade que tem o mesmo nome que uma propriedade de ambiente, a propriedade no projeto substituirá o valor da variável de ambiente.If the project contains a property definition that has the same name as an environment property, the property in the project overrides the value of the environment variable.

Cada projeto do MSBuild tem um bloco de ambiente isolado: apenas observa, lê e grava em seu próprio bloco.Each MSBuild project has an isolated environment block: it only sees reads and writes to its own block. O MSBuild somente lê as variáveis de ambiente quando ele inicializa a coleção de propriedades, antes de o arquivo de projeto ser avaliado ou criado.MSBuild only reads environment variables when it initializes the property collection, before the project file is evaluated or built. Depois disso, as propriedades de ambiente são estáticas, ou seja, cada ferramenta gerada começa com os mesmos nomes e valores.After that, environment properties are static, that is, each spawned tool starts with the same names and values.

Para obter o valor atual de variáveis de ambiente de uma ferramenta gerada, use as funções de propriedade System.Environment.GetEnvironmentVariable.To get the current value of environment variables from within a spawned tool, use the Property Functions System.Environment.GetEnvironmentVariable. O método preferido, entretanto, é usar o parâmetro de tarefa EnvironmentVariables.The preferred method, however, is to use the task parameter EnvironmentVariables. As propriedades de ambiente definidas nesta matriz de cadeia de caracteres podem ser passadas para a ferramenta gerada sem afetar as variáveis de ambiente do sistema.Environment properties set in this string array can be passed to the spawned tool without affecting the system environment variables.

Tip

Nem todas as variáveis de ambiente são lidas para se tornarem propriedades iniciais.Not all environment variables are read in to become initial properties. Qualquer variável de ambiente cujo nome não é um nome de propriedade do MSBuild válido, como "386", será ignorada.Any environment variable whose name is not a valid MSBuild property names, such as "386", is ignored.

Para obter mais informações, consulte Como usar variáveis de ambiente em um build.For more information, see How to: Use Environment Variables in a Build.

Propriedades de RegistroRegistry Properties

Você pode ler valores do Registro de sistema usando a seguinte sintaxe, em que Hive é o hive do Registro (por exemplo, HKEY_LOCAL_MACHINE) Key é o nome da chave, SubKey é o nome da subchave e Value é o valor da subchave.You can read system registry values by using the following syntax, where Hive is the registry hive (for example, HKEY_LOCAL_MACHINE ), Key is the key name, SubKey is the subkey name, and Value is the value of the subkey.

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

Para obter o valor da subchave padrão, omita o Value.To get the default subkey value, omit the Value.

$(registry:Hive\MyKey\MySubKey)  

Esse Registro pode ser usado para inicializar uma propriedade de build.This registry value can be used to initialize a build property. Por exemplo, para criar uma propriedade de build que representa a home page do navegador da Web do Visual Studio, use este código:For example, to create a build property that represents the Visual Studio web browser home page, use this code:

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

Propriedades globaisGlobal Properties

O MSBuild permite que você defina propriedades na linha de comando usando o comutador /property (ou /p).MSBuild lets you set properties on the command line by using the /property (or /p) switch. Esses valores de propriedades globais substituem os valores de propriedade que são definidos no arquivo de projeto.These global property values override property values that are set in the project file. Isso inclui propriedades de ambiente, mas não inclui propriedades reservadas, que não podem ser alteradas.This includes environment properties, but does not include reserved properties, which cannot be changed.

O exemplo a seguir define a propriedade Configuration global como DEBUG.The following example sets the global Configuration property to 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 atributo Properties da tarefa do MSBuild.Global properties can also be set or modified for child projects in a multi-project build by using the Properties attribute of the MSBuild task. Para mais informações, consulte Tarefa do MSBuild.For more information, see MSBuild Task.

Se você especificar uma propriedade usando o atributo TreatAsLocalProperty em uma marca de projeto, esse valor da propriedade global não substituirá o valor da propriedade que é definido no arquivo de projeto.If you specify a property by using the TreatAsLocalProperty attribute in a project tag, that global property value doesn't override the property value that's set in the project file. Para obter mais informações, consulte Elemento de projeto (MSBuild) e Como compilar os mesmos arquivos de origem com opções diferentes.For more information, see Project Element (MSBuild) and How to: Build the Same Source Files with Different Options.

Funções de propriedadeProperty Functions

A partir do .NET Framework versão 4, você pode usar funções de propriedade para avaliar seus scripts do MSBuild.Starting in .NET Framework version 4, you can use property functions to evaluate your MSBuild scripts. Você pode ler a hora do sistema, comparar cadeias de caracteres, combinar expressões regulares e executar outras ações no script de build sem usar as tarefas do MSBuild.You can read the system time, compare strings, match regular expressions, and perform many other actions within your build script without using MSBuild tasks.

Você pode usar métodos de cadeia de caracteres (instância) para operar qualquer valor da propriedade e pode chamar os métodos estáticos de muitas classes de sistema.You can use string (instance) methods to operate on any property value, and you can call the static methods of many system classes. Por exemplo, você pode definir uma propriedade de build com a data de hoje da seguinte maneira.For example, you can set a build property to today's date as follows.

<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.For more information, and a list of property functions, see Property Functions.

Criando propriedades durante a execuçãoCreating Properties During Execution

As propriedades posicionadas fora dos elementos Target são valores atribuídos durante a fase de avaliação de um build.Properties positioned outside Target elements are assigned values during the evaluation phase of a build. Durante a fase de execução subsequente, as propriedades podem ser criadas ou modificadas das seguintes maneiras:During the subsequent execution phase, properties can be created or modified as follows:

  • Uma propriedade pode ser emitida por qualquer tarefa.A property can be emitted by any task. Para emitir uma propriedade, o elemento Task deve ter um elemento filho Output que tem um atributo PropertyName.To emit a property, the Task element must have a child Output element that has a PropertyName attribute.

  • Uma propriedade pode ser emitida pela tarefa CreateProperty.A property can be emitted by the CreateProperty task. Esse uso é preterido.This usage is deprecated.

  • A partir do .NET Framework 3.5, os elementos Target podem conter elementos PropertyGroup que podem conter declarações de propriedade.Starting in the .NET Framework 3.5, Target elements may contain PropertyGroup elements that may contain property declarations.

Armazenamento de XML em propriedadesStoring XML in Properties

As propriedades podem conter XML arbitrário, que pode ajudar a passar valores para tarefas ou exibir informações de log.Properties can contain arbitrary XML, which can help in passing values to tasks or displaying logging information. O exemplo a seguir mostra a propriedade ConfigTemplate, que tem um valor que contém o XML e outras referências de propriedade.The following example shows the ConfigTemplate property, which has a value that contains XML and other property references. MSBuildMSBuild substitui as referências de propriedade usando seus respectivos valores de propriedade.replaces the property references by using their respective property values. Os valores de propriedade são atribuídos na ordem em que aparecem.Property values are assigned in the order in which they appear. Portanto, nesse exemplo, $(MySupportedVersion), $(MyRequiredVersion) e $(MySafeMode) já devem ter sido definidos.Therefore, in this example, $(MySupportedVersion), $(MyRequiredVersion), and $(MySafeMode) should have already been defined.


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

Consulte tambémSee Also

Conceitos do MSBuildMSBuild Concepts
MSBuildMSBuild
Como usar variáveis de ambiente em um build How to: Use Environment Variables in a Build
Como referenciar o nome ou o local do arquivo de projeto How to: Reference the Name or Location of the Project File
Como compilar os mesmos arquivos de origem com opções diferentes How to: Build the Same Source Files with Different Options
Propriedades reservadas e conhecidas do MSBuild MSBuild Reserved and Well-Known Properties
Elemento Property (MSBuild)Property Element (MSBuild)