Partilhar via


Trabalhando com propriedades do projeto

No IDE, todas as opções do compilador, opções de vinculador, configurações do depurador e etapas de compilação personalizadas são expostas como propriedades.Use as páginas de propriedades de um projeto ver exibir e modificar suas propriedades.Você pode aplicar as propriedades do projeto independentemente de qualquer combinação de configuração de compilação (Debug ou Release) e plataforma de destino (Win32, x64 ou ARM).Você também pode definir propriedades para arquivos individuais em um projeto.

Embora você possa definir propriedades “globais” por usuário e por computador, não recomendamos fazer isso.Em vez disso, recomendamos que você use o Gerenciador de Propriedades para criar uma folha de propriedades para armazenar configurações para cada tipo de projeto que você deseja poder reutilizar ou compartilhar com outras pessoas.Folhas de propriedade também tornam menos provável que as configurações de propriedade para outros tipos de projeto sejam alteradas inadvertidamente.As folhas de propriedade serão abordadas em mais detalhes posteriormente neste artigo.

Para exibir o Gerenciador de Propriedades, na barra de menus, selecione Exibir, Outras Janelas, Gerenciador de Propriedades.

O sistema de projetos do Visual C++ é baseado no MSBuild.Embora você possa editar os arquivos de projeto XML e folhas de propriedade diretamente na linha de comando, recomendamos que você use o IDE, especialmente quando alterar as propriedades que participam da herança.Um arquivo manualmente editado que é válido no MSBuild não é necessariamente legível pelo sistema do projeto Visual C++ e você pode gerar erros sutis no processo de compilação.

Um arquivo de projeto é um arquivo XML que possui a extensão de nome de arquivo .vcxproj.Todas as propriedades que você definir no IDE serão gravadas no arquivo de projeto diretamente ou nas folhas de propriedade importadas no tempo de compilação.

A ilustração a seguir mostra as páginas de propriedades para um projeto do Visual C++.Observe que no painel esquerdo, a regra de Diretórios VC++ está selecionada, e no painel direito, as propriedades que são associadas a essa regra são mostradas. (Os valores $(...) são macros, que são abordados posteriormente neste artigo.) A opção Diretórios VC++ é uma propriedade de configuração, e seus valores podem ser diferentes para diferentes configurações, por exemplo, Debug versus Release.Você pode usar as caixas de listagem Configuração e Plataforma na parte superior da caixa de diálogo para definir as configurações às quais as propriedades se aplicam; em muitos casos, Todas as Plataformas e Todas as Configurações são a opção correta.As configurações na regra de Propriedades Comuns se aplicam a todas as configurações.

Páginas de propriedades do projeto

Propriedades de configuração de um projeto

Em geral, as propriedades de um projeto são definidas desta forma:

Para definir uma propriedade de um projeto

  1. Na barra de menus, escolha Projeto, Propriedades.No Gerenciador de Soluções ou no Gerenciador de Propriedades, abra o menu de atalhos para o projeto e escolha Propriedades.A caixa de diálogo Páginas de Propriedades é aberta.

  2. Nas caixas na parte superior da caixa de diálogo, selecione as configurações e as plataformas às quais você deseja aplicar a definição.

    Para criar ou modificar as configurações que aparecem na caixa Configuração, clique no botão Gerenciador de Configurações.

  3. Defina o valor da propriedade.Quando você clica no botão OK, o novo valor é gravado no arquivo de projeto.

ObservaçãoObservação

A caixa de diálogo Páginas de Propriedades mostra somente as páginas de propriedades que se aplicam ao projeto atual.Por exemplo, se o projeto não tiver um arquivo .idl, a página de propriedades MIDL não será exibida.

Mais informações sobre propriedades na caixa de diálogo Páginas de Propriedades:

DicaDica

É possível abrir uma página de propriedades diretamente digitando o nome na janela Início Rápido.

Propriedades codificadas x macros

Algumas propriedades do projeto podem usar como valor uma referência a uma propriedade que é definida em outro lugar.Esse tipo de valor é referido como uma macro para distingui-lo de outros tipos de configurações de propriedade de projeto.Uma macro pode referir-se a uma propriedade que é definida pelo sistema MSBuild ou a uma que você definiu.Ao usar macros em vez de valores embutidos, como caminhos de diretório, você pode compartilhar configurações de propriedade mais facilmente entre computadores e entre versões do Visual Studio, além de poder garantir melhor que as configurações do projeto participem corretamente da herança de propriedade.

  • macros globais
    Aplica-se a todos os itens em uma configuração de projeto.Tem a sintaxe $(name).Um exemplo de uma macro global é $(VCInstallDir), que armazena o diretório raiz da sua instalação do Visual Studio.Uma macro global corresponde a PropertyGroup em MSBuild.

  • macros de item
    Tem a sintaxe %(name).Para um arquivo, uma macro de item se aplica somente a esse arquivo — por exemplo, você pode usar %(AdditionalIncludeDirectories) para especificar diretórios de inclusão que se aplicam somente a um arquivo específico.Esse tipo de macro de item corresponde a um metadado ItemGroup no MSBuild.Quando usada no contexto de uma configuração de projeto, uma macro de item se aplica a todos os arquivos de determinado tipo.Por exemplo, a propriedade da configuração Definições do Pré-processador C/C++ pode ter uma macro de item %(PreprocessorDefinitions) que se aplica a todos os arquivos .cpp no projeto.Esse tipo de macro de item corresponde a um metadado ItemDefinitionGroup no MSBuild.Para obter mais informações, consulte Definições de itens.

Você pode usar macros para definir valores de propriedades e usar o Editor de Propriedades para ver os valores de macros disponíveis.

Edição de Propriedades

Você pode usar o Editor de Propriedades para alterar certas propriedades da cadeia de caracteres e selecionar macros como valores.Para acessar o Editor de Propriedades, selecione uma propriedade em uma página de propriedades e, em seguida, selecione o botão de seta para a direita.Se a lista suspensa contiver <Editar>, você poderá escolher essa opção para exibir o Editor de Propriedades dessa propriedade.

Property_Editor_Dropdown

No Editor de Propriedades, você pode escolher o botão Macros para ver as macros disponíveis e seus valores atuais.A ilustração a seguir mostra o Editor de Propriedades da propriedade Diretórios de Inclusão Adicionais depois de o botão Macros ser escolhido.Quando a caixa de seleção Herdar do pai ou padrões de projeto é marca e você adiciona um novo valor, ele é acrescentado a todos os valores herdados atualmente.Se você desmarcar a caixa de seleção, o novo valor substituirá os valores herdados.Na maioria dos casos, deixe a caixa de seleção marcada.

Editor de propriedades, Visual C++

Compartilhando configurações de propriedade reutilizáveis

Se você tiver um conjunto de propriedades comuns usadas com frequência que queira aplicar a vários projetos, use o Gerenciador de Propriedades para capturá-las em um arquivo de folha de propriedades reutilizável que, por convenção, tem uma extensão de nome de arquivo .props.Você pode aplicar a folha (ou folhas) a novos projetos para que não precisar definir suas propriedades a partir do zero.Para acessar o Gerenciador de Propriedades, na barra de menus, selecione Exibir, Gerenciador de Propriedades.

Se você escolher Adicionar Nova Folha de Propriedades do Projeto e selecionar, por exemplo, a folha de propriedades MyProps.props, uma caixa de diálogo da página de propriedades aparecerá.Observe que isso se aplica à folha de propriedades MyProps; as alterações feitas são gravadas na folha, não no arquivo de projeto (.vcxproj).

As propriedades em uma folha de propriedades são substituídas se a mesma propriedade for definida diretamente no arquivo .vcxproj.

Você pode importar uma folha de propriedades quantas vezes for necessário.Vários projetos em uma solução podem herdar configurações da mesma folha de propriedades, e um projeto pode ter várias folhas.Uma folha de propriedades em si pode herdar configurações de outra folha de propriedades.

Observação importanteImportante

Um arquivo .props por padrão não participa no controle de código-fonte porque não é criado como um item de projeto.Você pode adicionar manualmente o arquivo como um item de solução se quiser incluí-lo no controle de código-fonte.

Para criar uma folha de propriedades

  1. Na barra de menus, escolha Exibir, Gerenciador de Propriedades.O Gerenciador de Propriedades será aberto.

  2. Para definir o escopo da folha de propriedades, selecione o item ao qual se aplica.Isso pode ser uma configuração específica ou outra folha de propriedades.Abra o menu de atalho desse item e escolha Adicionar Nova Folha de Propriedades do Projeto.Especifique um nome e um local.

  3. No Gerenciador de Propriedades, abra a nova folha de propriedades e defina as propriedades que você deseja incluir.

Herança de propriedade

As propriedades do projeto estão em camadas.Cada camada herda os valores da camada anterior, mas um valor herdado pode ser substituído pela definição explícita da propriedade.Veja a árvore básica de herança:

  1. Configurações padrão do Conjunto de Ferramentas MSBuild CPP (..\Arquivos de Programas\MSBuild\Microsoft.Cpp\v4.0\Microsoft.Cpp.Default.props, que é importado pelo arquivo .vcxproj)

  2. Folhas de propriedade

  3. Arquivo .vcxproj. (Pode substituir as configurações padrão e as da folha de propriedades.)

  4. Metadados de itens

DicaDica

Em uma página de propriedades, uma propriedade em bold é definida no contexto atual.Uma propriedade na fonte normal é herdada.

Um arquivo de projeto (.vcxproj) importa outras folhas de propriedade no momento da compilação.Depois que todas as folhas de propriedade são importadas, o arquivo do projeto será avaliado e a última definição de qualquer valor de propriedade será usada.Às vezes é útil ver o arquivo expandido para determinar como um valor de propriedade fornecido é herdado.Para ver a versão expandida, digite o comando a seguir em um prompt de comando do Visual Studio. (Altere os nomes dos arquivos de espaço reservado com o nome que você deseja usar.)

msbuild /pp:temp.txtmyapp**.vcxproj**

Os arquivos de projeto expandidos podem ser grandes e difíceis de entender, a menos que você esteja familiarizado com o MSBuild.Veja a estrutura básica de um arquivo de projeto:

  1. Propriedades fundamentais do projeto, que não são expostas no IDE.

  2. Importação de Microsoft.cpp.default.props, que define algumas propriedades básicas e independentes do conjunto de ferramentas.

  3. Propriedades globais de configuração (expostas como propriedades padrão PlatformToolset e Project na página Configuração Geral.Essas propriedades determinam quais folhas de propriedade intrínseca e conjuntos de ferramentas são importados no Microsoft.cpp.props na próxima etapa.

  4. Importação de Microsoft.cpp.props, que define a maioria dos padrões do projeto.

  5. Importação de todas as folhas de propriedade, incluindo arquivos .user.Essas folhas de propriedade podem substituir tudo, exceto as propriedades padrão PlatformToolset e Project.

  6. O restante das propriedades de configuração do projeto.Esses valores podem substituir o que foi definido nas folhas de propriedade.

  7. Itens (arquivos) com seus metadados.Essas são sempre as últimas palavras em regras de avaliação do MSBuild, mesmo que ocorram antes de outras propriedades e importações.

Para obter mais informações, consulte Propriedades do MSBuild.

Arquivos .user e por que eles são problemáticos

As versões anteriores do Visual Studio usavam folhas de propriedade globais que tinham uma extensão de nome de arquivo .user e estavam localizadas na pasta <perfildousuário>\AppData\Local\Microsoft\MSBuild\v4.0\.Não recomendamos mais esses arquivos, pois definem propriedades para configurações do projeto com base no computador e no usuário.Essas configurações “globais” podem interferir com as compilações, especialmente quando você está definindo mais de uma plataforma no computador de compilação.Por exemplo, se você tiver um projeto do MFC e um projeto do Windows Phone, as propriedades .user serão inválidas para um deles.Folhas de propriedade reutilizáveis são mais flexíveis e mais robustas.

Embora os arquivos .user ainda sejam instalados pelo Visual Studio e participem da herança de propriedade, eles são vazios por padrão.A prática recomendada é excluir a referência a eles no Gerenciador de Propriedades para garantir que seus projetos operem independentemente de qualquer usuário, configuração de computador. É importante garantir o comportamento correto em um ambiente de SCC (controle de código-fonte).

Adicionando um diretório de inclusão ao conjunto de diretórios padrão

Quando você adiciona um diretório de inclusão a um projeto, é importante não substituir todos os diretórios padrão.A maneira correta de adicionar um diretório é acrescentar o novo caminho, por exemplo “C:\MyNewIncludeDir\”, e anexar na macro $(IncludePath) para o valor da propriedade.

Criando uma macro definida pelo usuário

Você pode criar macros definidas pelo usuário para usar como variáveis em compilações do projeto.Por exemplo, você pode criar uma macro definida pelo usuário que forneça um valor a uma etapa personalizada de compilação ou a uma ferramenta personalizada de compilação.Uma macro definida é um par de nome/valor.Em um arquivo de projeto, use a notação $(name) para acessar o valor.

Uma macro definida pelo usuário é armazenada em uma folha de propriedades.Se seu projeto ainda não contiver uma folha de propriedades, você poderá criar uma seguindo as etapas anteriores deste artigo.

Para criar uma macro definida pelo usuário

  1. Na janela Gerenciador de Propriedades (na barra de menus, escolha Exibir, Gerenciador de Propriedades), abra o menu de atalho de uma folha de propriedades (o nome termina com .user) e escolha Propriedades.A caixa de diálogo Páginas de Propriedades dessa folha de propriedades se abrirá.

  2. No painel esquerdo da caixa de diálogo, selecione Macros do Usuário.No painel direito, escolha o botão Adicionar Macro para abrir a caixa de diálogo Adicionar Macro de Usuário.

  3. Na caixa de diálogo, especifique um nome e um valor para a macro.Marque a caixa de seleção Defina esta macro como uma variável de ambiente no ambiente de compilação.

Definindo variáveis de ambiente para uma compilação

O compilador do Visual C++ (cl.exe) reconhece determinadas variáveis de ambiente, especificamente LIB, LIBPATH, PATH e INCLUDE.Quando você compila com o IDE, as propriedades que são definidas na página de propriedades Página de propriedade dos diretórios do VC++ são usadas para definir essas variáveis de ambiente.Se os valores LIB, LIBPATH e INCLUDE já tiverem sido definidos, por exemplo, por um prompt de comando do desenvolvedor, eles serão substituídos pelos valores das propriedades correspondentes do MSBuild.A compilação, em seguida, anexa o valor da propriedade de diretórios executáveis dos Diretórios VC++ como PATH.Você pode definir uma variável de ambiente definida pelo usuário criando uma macro definida pelo usuário e clicando na caixa que diz Defina esta macro como uma variável de ambiente no ambiente de compilação.

Definindo variáveis de ambiente para uma sessão de depuração

No painel esquerdo da caixa de diálogo Páginas de Propriedades do projeto, expanda Propriedades de Configuração e selecione Depuração.

No painel direito, modifique as configurações do projeto Ambiente ou Ambiente de Mesclagem e escolha o botão OK.

Exibindo as macros e seus valores

Na caixa de diálogo Páginas de Propriedades de um projeto, selecione uma propriedade de cadeia de caracteres, como Diretórios VC++, escolha o botão de seta para baixo na coluna direita e escolha <Editar> para abrir o Editor de Propriedades.No Editor de Propriedades, escolha o botão Macros.

Definindo propriedades para várias configurações simultaneamente

Para definir propriedades para todas as configurações, nas caixas na parte superior da caixa de diálogo Páginas de Propriedades de um projeto, selecione Todas as Configurações e Todas as Plataformas e, em seguida, defina as propriedades que você deseja.

Para definir propriedades para apenas algumas configurações, selecione-as simultaneamente no Gerenciador de Propriedades e, em seguida, abra o menu de atalho e selecione Propriedades.Os parâmetros que você alterar serão aplicados a cada configuração selecionada.

Você também pode criar uma folha de propriedades para várias configurações.Para fazer isso, crie uma folha de propriedades para cada configuração, abra o menu de atalho para uma delas, selecione Adicionar Folha de Propriedades Existente e, em seguida, adicione as outras folhas.No entanto, se você usar uma folha de propriedades comum, quando definir uma propriedade, ela será definida para todas as configurações às quais a folha se aplica. Além disso, o IDE não mostra quais projetos ou outras folhas de propriedade estão herdando de determinada folha de propriedades.

Em grandes soluções que terão vários projetos, pode ser útil criar uma folha de propriedades no nível da solução.Quando você adicionar um projeto à solução, use o Gerenciador de Propriedades para adicionar a folha de propriedades ao projeto.Se for necessário no nível do projeto, você pode adicionar uma nova folha de propriedades para definir valores específicos do projeto.

Para navegar e procurar rapidamente todas as opções

A página de propriedades Todas as Opções (no nó C/C++ no painel esquerdo da caixa de diálogo Páginas de Propriedades) oferece uma maneira rápida de navegar e de pesquisar as propriedades disponíveis no contexto atual.Tem uma caixa de pesquisa especial e uma sintaxe simples para ajudar você a filtrar resultados:

  • Nenhum prefixo:
    Pesquisar nomes de propriedade somente (subcadeia de caracteres sem diferenciação de maiúsculas e minúsculas).

  • '/' ou '-' :
    Pesquisar somente em opções de compilador (prefixo sem diferenciação de maiúsculas e minúsculas)

  • v:
    Pesquisar somente em valores (subcadeia de caracteres sem diferenciação de maiúsculas e minúsculas).

Consulte também

Outros recursos

Criando e gerenciando projetos do Visual C++