Visão geral de possíveis problemas de atualização (Visual C++)

Ao longo dos anos, o compilador do Microsoft C++ passou por muitas alterações, juntamente com as alterações na própria linguagem C++, a Biblioteca Padrão do C++, o CRT (Runtime de C) e outras bibliotecas como MFC e ATL. Como resultado, ao atualizar um aplicativo a partir de uma versão anterior do Visual Studio, você pode encontrar erros e avisos de compilador e vinculador no código previamente compilado corretamente. Quanto mais antiga a base de código original, maior o potencial para tais erros. Esta visão geral resume as classes mais comuns dos problemas que você pode encontrar e fornece links para obter informações mais detalhadas.

As perguntas ou comentários sobre o processo de atualização podem ser enviados para vcupgrade@microsoft.com.

Dependências de biblioteca e o conjunto de ferramentas

Ao atualizar um aplicativo a partir do Visual Studio 2013 ou anterior para uma versão mais recente, geralmente é aconselhável e necessário atualizar todas as bibliotecas e DLLs às quais o aplicativo está vinculado. Você deve ter acesso ao código-fonte ou o fornecedor da biblioteca deve fornecer novos arquivos binários compilados com a mesma versão principal do compilador. Se uma dessas condições for verdadeira, você poderá ignorar esta seção, que lida com os detalhes de compatibilidade do binário. Se nenhum dos dois for o caso, pode ser que as bibliotecas não funcionem em seu aplicativo atualizado. As informações nesta seção o ajudarão você a entender se pode prosseguir com a atualização.

Conjunto de Ferramentas

Os formatos de arquivo .obj e .lib são bem definidos e raramente mudam. Às vezes, são feitas adições a esses formatos de arquivo, mas essas adições geralmente não afetam a capacidade de conjuntos de ferramentas mais recentes de consumir arquivos-objeto e bibliotecas produzidos por conjuntos de ferramentas mais antigos. A grande exceção é se você compilar usando /GL (Otimização do Programa Inteiro). Se você compilar usando /GL, só poderá vincular o arquivo-objeto resultante usando o mesmo conjunto de ferramentas que foi usado para gerá-lo. Portanto, se você gerar um arquivo-objeto com /GL e usar o compilador do Visual Studio 2017 (v141), será necessário vinculá-lo usando o vinculador do Visual Studio 2017 (v141). Isso ocorre porque as estruturas de dados internas dentro dos arquivos-objetos não estão estáveis entre as versões principais do conjunto de ferramentas. Os conjuntos de ferramentas mais novos não entendem os formatos de dados mais antigos.

O C++ não tem uma ABI (interface binária de aplicativo) estável. Mas o Visual Studio mantém um ABI C++ estável para todas as versões secundárias de uma versão. Os conjuntos de ferramentas do Visual Studio 2015 (v140), Visual Studio 2017 (v141), Visual Studio 2019 (v142) e Visual Studio 2022 (v143) variam somente na versão secundária. Todos eles têm o mesmo número de versão principal, que é 14. Para obter mais informações, confira Compatibilidade binária do C++ entre as versões do Visual Studio.

Se você tiver um arquivo-objeto que tenha símbolos externos com vinculação C++, esse arquivo-objeto poderá não se vincular corretamente com arquivos-objeto produzidos por uma versão principal diferente do conjunto de ferramentas. Há muitos resultados possíveis: o link pode falhar totalmente (por exemplo, caso a decoração de nome tenha sido alterada). O link pode ter êxito, mas o aplicativo pode falhar no runtime (por exemplo, caso os layouts de tipo sejam alterados). Ou seu aplicativo pode continuar funcionando, e nada dará errado. Observe também que, embora a ABI do C++ não seja estável, a ABI do C e o subconjunto da ABI do C++ necessárias para COM são estáveis.

Se você vincular a uma biblioteca de importação, qualquer versão mais recente das bibliotecas redistribuíveis do Visual Studio que preservar a compatibilidade com ABI poderá ser usada em runtime. Por exemplo, se você compilar e vincular seu aplicativo usando o conjunto de ferramentas do Visual Studio 2015 Atualização 3, poderá usar qualquer redistribuível posterior. Isso porque as bibliotecas de 2015, 2017, 2019 e 2022 preservaram a compatibilidade binária com as versões anteriores. O contrário não ocorre, ou seja, você não pode usar um redistribuível para uma versão do conjunto de ferramentas anterior à que você usou para compilar qualquer componente do seu código.

Bibliotecas

Se você #include uma versão específica dos arquivos de cabeçalho, deverá vincular o arquivo de objeto resultante à mesma versão das bibliotecas. Portanto, por exemplo, se seu arquivo de origem for compilado com o Visual Studio 2015 Atualização 3 <immintrin.h>, você deverá vinculá-lo com a biblioteca vcruntime do Visual Studio 2015 Atualização 3. Da mesma forma, se seu arquivo de origem incluir o Visual Studio 2017 versão 15.5 <iostream>, você deverá vincular à biblioteca C++ padrão do Visual Studio 2017 versão 15.5, msvcprt. Não há suporte para a mistura e combinação.

Para a Biblioteca padrão C++, a mistura e combinação foram explicitamente proibidas por meio do uso de #pragma detect_mismatch nos cabeçalhos padrão desde o Visual Studio 2010. Se você tentar vincular os arquivos-objeto incompatíveis ou se vincular com a biblioteca de padrão incorreta, o link falhará.

Nunca houve suporte para a mistura e combinação de versões de CRT mais antigas, mas geralmente funcionava porque a superfície da API não mudava muito ao longo do tempo. A CRT Universal interrompeu a compatibilidade com versões anteriores para que no futuro possamos manter a compatibilidade com versões anteriores. Não temos planos de introduzir novos binários de CRT Universal com versão no futuro. Em vez disso, o CRT Universal existente agora é atualizado no local.

Para proporcionar compatibilidade de link parcial com arquivos-objeto (e bibliotecas) compilados com versões mais antigas dos cabeçalhos do Runtime de C da Microsoft, fornecemos uma biblioteca, legacy_stdio_definitions.lib, com o Visual Studio 2015 e posterior. Essa biblioteca fornece símbolos de compatibilidade para a maioria das exportações de funções e dados que foram removidas do CRT Universal. O conjunto de símbolos de compatibilidade fornecido por legacy_stdio_definitions.lib é suficiente para atender a maioria das dependências, incluindo todas as dependências em bibliotecas no SDK do Windows. No entanto, alguns símbolos foram removidos do CRT Universal que não tem símbolos de compatibilidade. Entre esses símbolos, há algumas funções (por exemplo, __iob_func) e algumas exportações de dados (por exemplo, __imp___iob, __imp___pctype, __imp___mb_cur_max).

Caso você tenha uma biblioteca estática que foi compilada com uma versão mais antiga dos cabeçalhos de Runtime de C, recomendamos as seguintes ações, nesta ordem:

1. Recompile a biblioteca estática usando a nova versão do Visual Studio e os cabeçalhos de CRT Universal para dar suporte à vinculação com o CRT Universal. Essa abordagem é totalmente compatível e é a melhor opção.

2. Se você não puder (ou não quiser) recompilar a biblioteca estática, poderá tentar vincular com legacy_stdio_definitions.lib. Se isso satisfizer as dependências de tempo de link da sua biblioteca estática, teste completamente a biblioteca estática da forma como ela é usada no binário. Verifique se ela não foi afetada negativamente por nenhuma das alterações comportamentais que foram feitas no CRT Universal.

3. Talvez as dependências da biblioteca estática não sejam atendidas por legacy_stdio_definitions.lib ou a biblioteca não funcione com o CRT Universal devido a alterações de comportamento. Nesse caso, recomendamos encapsular sua biblioteca estática em uma DLL vinculada à versão necessária do Microsoft C Runtime. Por exemplo, se a biblioteca estática tiver sido compilada usando o Visual Studio 2013, compile essa DLL usando o conjunto de ferramentas do Visual Studio 2013 e as bibliotecas C++. Ao compilar a biblioteca em uma DLL, você encapsula os detalhes de implementação que é sua dependência em uma versão específica do Runtime de C da Microsoft. Tenha cuidado para que a interface da DLL não vaze detalhes sobre qual C Runtime ela usa, por exemplo, se ela retornar um FILE* no limite da DLL ou um ponteiro alocado malloc que o chamador deve free.

O uso de vários CRTs em um único processo não é exatamente um problema. (Na verdade, a maioria dos processos carrega várias DLLs do CRT. Por exemplo, os componentes do sistema operacional Windows dependem da msvcrt.dll, e o CLR depende de sua própria CRT privada.) Os problemas surgem quando você mistura o estado de CRTs diferentes. Por exemplo, você não deve alocar memória usando msvcr110.dll!malloc e tentar desalocar essa memória usando msvcr120.dll!free, e também não deve tentar abrir um ARQUIVO usando msvcr110!fopen e tentar ler esse ARQUIVO usando msvcr120!fread. Desde que não misture o estado de CRTs diferentes, você pode ter vários CRTs carregados em um único processo com segurança.

Para obter mais informações, consulte Upgrade your code to the Universal CRT (Atualizar seu código para o CRT Universal).

Erros causados pelas configurações do projeto

Para começar o processo de atualização, basta abrir um projeto/solução/workspace mais antigo na versão mais recente do Visual Studio. O Visual Studio criará um novo projeto com base nas configurações do projeto antigo. Verifique se o projeto mais antigo tem caminhos de biblioteca ou inclui caminhos embutidos em código para locais não padrão. É possível que os arquivos nesses caminhos não fiquem visíveis para o compilador quando o projeto usar as configurações padrão. Para obter mais informações, consulte Linker OutputFile setting (Configuração de OutputFile do vinculador).

Em geral, agora é um bom momento para organizar o código do projeto para simplificar a manutenção do projeto e ajudar a fazer com que seu código atualizado compile o mais rápido possível. Se seu código-fonte já estiver bem organizado e seu projeto mais antigo compilar com o Visual Studio 2010 ou posterior, você poderá editar manualmente o novo arquivo de projeto para dar suporte à compilação no compilador antigo e no novo. O exemplo a seguir mostra como compilar para Visual Studio 2015 e Visual Studio 2017:

<PlatformToolset Condition="'$(VisualStudioVersion)'=='14.0'">v140</PlatformToolset>
<PlatformToolset Condition="'$(VisualStudioVersion)'=='15.0'">v141</PlatformToolset>

LNK2019: externo não resolvido

Para os símbolos não resolvidos, você precisará corrigir as configurações do projeto.

• Se o arquivo de origem estiver em um local não padrão, você adicionou o caminho para os diretórios de inclusão do projeto?

• Se o externo estiver definido em um arquivo .lib, você especificou o caminho do lib nas propriedades do projeto e a versão correta do arquivo .lib está localizada lá?

• Você está tentando vincular a um arquivo .lib que foi compilado com uma versão diferente do Visual Studio? Nesse caso, consulte a seção anterior sobre dependências de biblioteca e o conjunto de ferramentas.

• Os tipos dos argumentos no site de chamada realmente coincidem com uma sobrecarga existente da função? Verifique se os tipos subjacentes são os esperados, tanto para os typedefs na assinatura da função quanto no código que chama a função.

Para solucionar problemas de erros de símbolo não resolvido, você pode usar o dumpbin.exe para examinar os símbolos definidos em um binário. Experimente a seguinte linha de comando para exibir os símbolos definidos em uma biblioteca:

dumpbin.exe /LINKERMEMBER somelibrary.lib

/Zc:wchar_t (wchar_t é do tipo nativo)

(No Microsoft Visual C++ 6.0 e versões anteriores, wchar_t não foi implementado como um tipo interno, ele foi declarado em wchar.h como um typedef para unsigned short.) O padrão C++ requer que wchar_t seja do tipo interno. Usar a versão typedef pode causar problemas de portabilidade. Se você atualizar de versões anteriores do Visual Studio e encontrar o erro do compilador C2664 porque o código está tentando converter implicitamente um wchar_t em unsigned short, recomendamos alterar o código para corrigir o erro, em vez de definir /Zc:wchar_t-. Para obter mais informações, confira /Zc:wchar_t (wchar_t Is Native Type).

Atualizando com as opções do vinculador /NODEFAULTLIB, /ENTRY e /NOENTRY

A opção do vinculador /NODEFAULTLIB (ou a propriedade do vinculador Ignorar Todas as Bibliotecas Padrão) instrui o vinculador a não vincular automaticamente nas bibliotecas padrão como o CRT. Isso significa que cada biblioteca deve ser listada como entrada individualmente. Esta lista de bibliotecas é fornecida na propriedade Dependências Adicionais na seção Vinculador da caixa de diálogo Propriedades do Projeto.

Os projetos que usam essa opção apresentam um problema durante a atualização, porque o conteúdo de algumas das bibliotecas padrão foram refatorados. Como cada biblioteca deve ser listada na propriedade Dependências Adicionais ou na linha de comando do vinculador; é necessário atualizar a lista de bibliotecas para usar todos os nomes atuais.

A tabela a seguir mostra as bibliotecas cujo conteúdo foi alterado começando com o Visual Studio 2015. Para atualizar, é necessário adicionar os novos nomes da biblioteca na segunda coluna às bibliotecas na primeira coluna. Algumas dessas bibliotecas são bibliotecas de importação, mas isso não importa.

O mesmo problema também se aplica se você usa a opção /ENTRY ou a opção /NOENTRY, que também faz com que as bibliotecas padrão sejam ignoradas.

Erros causados pela melhoria da conformidade com a linguagem

O compilador do Microsoft C++ melhorou continuamente sua conformidade com o padrão C++ ao longo dos anos. O código que foi compilado em versões anteriores pode falhar ao ser compilado em versões posteriores do Visual Studio. Isso ocorre porque o compilador sinalizará corretamente um erro que anteriormente foi ignorado ou explicitamente permitido.

Por exemplo, a opção /Zc:forScope foi introduzida no início do histórico do MSVC. Ela permite o comportamento não conforme para variáveis de loop. Essa opção foi preterida e deve ser removida em versões futuras. É altamente recomendável que você não use essa opção ao atualizar seu código. Para obter mais informações, confira /Zc:forScope- foi preterida.

Um exemplo de um erro do compilador comum que você pode ver ao atualizar é quando um argumento não const é passado para um parâmetro const. As versões mais antigas do compilador nem sempre sinalizavam isso como um erro. Para obter mais informações, consulte The compiler's more strict conversions (As conversões mais restritas do compilador).

Para obter mais informações sobre melhorias de compatibilidade específicas, consulte Histórico de alterações do Visual C++ de 2003 – 2015 e Melhorias de conformidade do C++ no Visual Studio.

Erros envolvendo os tipos integrais <stdint.h>

O cabeçalho <stdint.h> define typedefs e macros que, diferente dos tipos integrais internos, têm a garantia de ter um comprimento específico em todas as plataformas. Alguns exemplos são uint32_t e int64_t. O cabeçalho <stdint.h> foi adicionado no Visual Studio 2010. Códigos que tenham sido escritos antes de 2010 podem ter fornecido definições privadas para esses tipos. E essas definições podem nem sempre ser consistentes com as definições <stdint.h>.

Se o erro for C2371 e houver um tipo stdint envolvido, isso provavelmente significará que o tipo está definido em um cabeçalho em seu código ou em um arquivo de biblioteca de terceiros. Ao atualizar, você deve eliminar quaisquer definições personalizadas dos tipos <stdint.h>, mas primeiro compare as definições personalizadas às definições padrão atuais para garantir que você não introduza novos problemas.

Você pode pressionar F12 (Ir para Definição) para ver onde o tipo em questão está definido.

A opção do compilador /showIncludes pode ser útil aqui. Na caixa de diálogo Páginas de Propriedades do seu projeto, selecione a página Propriedades de Configuração>C/C++>Avançado e defina Mostrar Inclusões como Sim. Depois, recompile seu projeto. Você verá a lista de arquivos para #include na janela de saída. Cada cabeçalho é recuado sob o cabeçalho que o inclui.

Erros envolvendo funções CRT

Foram feitas várias alterações no runtime de C ao longo dos anos. Muitas versões seguras de funções foram adicionadas e algumas foram removidas. Além disso, conforme descrito anteriormente neste artigo, a implementação da Microsoft do CRT foi refatorada no Visual Studio 2015 em novos binários e arquivos .lib associados.

Se o erro envolver uma função CRT, pesquise o Histórico de alterações de 2003 a 2015 do Visual C++ ou Aprimoramentos de conformidade do C++ no Visual Studio para ver se esses artigos contêm informações adicionais. Se o erro for LNK2019, confirme se a função não foi removida. Caso contrário, se tiver certeza de que a função ainda existe e que o código de chamada está correto, verifique se o projeto está usando /NODEFAULTLIB. Nesse caso, é necessário atualizar a lista de bibliotecas para usar as novas bibliotecas (UCRT) universais. Para saber mais, confira a seção acima sobre Biblioteca e dependências.

Se o erro envolver printf ou scanf, verifique se você não está definindo alguma função em particular sem incluir stdio.h. Nesse caso, remova as definições privadas ou vincule a legacy_stdio_definitions.lib. É possível definir essa biblioteca na caixa de diálogo Páginas de Propriedades em Propriedades de Configuração>Vinculador>Entrada, na propriedade Dependências Adicionais. Se vincular com o SDK do Windows 8.1 ou anterior, adicione legacy_stdio_definitions.lib.

Se o erro envolve argumentos de cadeia de caracteres de formato, provavelmente é porque o compilador é mais estrito sobre a aplicação do padrão. Para saber mais, confira o histórico de alterações. Preste atenção nos erros aqui, pois eles podem potencialmente representar um risco de segurança.

Erros causados por alterações no padrão C++

O padrão C++ em si evoluiu de maneiras que nem sempre são compatíveis com versões anteriores. O C++11 apresentou a semântica de movimento, novas palavras-chave e outros recursos de biblioteca padrão e idioma. Essas alterações podem causar erros de compilador e até mesmo comportamentos diferentes de runtime.

Por exemplo, um programa C++ antigo pode incluir o cabeçalho iostream.h. Esse cabeçalho foi preterido no início do histórico do C++ e eventualmente foi completamente removido do Visual Studio. Nesse caso, você precisa usar <iostream> e reescrever seu código. Para obter mais informações, confira Como atualizar um código iostream antigo.

C4838: aviso de conversão de estreitamento

O padrão C++ agora especifica que as conversões de valores integrais sem sinal para com sinal são conversões de estreitamento. O compilador não gerava esse aviso antes do Visual Studio 2015. Inspecione cada ocorrência para verificar se o estreitamento não impacta a exatidão do seu código.

Avisos para usar funções CRT seguras

Ao longo dos anos, foram introduzidas versões seguras de funções de runtime de C. Embora as versões antigas e não seguras ainda estejam disponíveis, é recomendável alterar o código para usar as versões seguras. O compilador emitirá um aviso para o uso das versões não seguras. Você pode optar por desabilitar ou ignorar esses avisos. Para desabilitar o aviso para todos os projetos na solução, abra Exibir>Gerenciador de Propriedades, selecione todos os projetos para os quais deseja desabilitar o aviso, clique com o botão direito do mouse nos itens selecionados e escolha Propriedades. Na caixa de diálogo Páginas de Propriedades em Propriedades de Configuração>C/C++>Avançado, selecione Desabilitar Avisos Específicos. Escolha a seta suspensa e, depois, Editar. Digite 4996 na caixa de texto. (Não inclua o prefixo “C”). Para obter mais informações, confira Portabilidade para usar o CRT Seguro.

Erros causados por alterações nas APIs do Windows ou SDKs obsoletos

Ao longo dos anos, os tipos de dados e as APIs do Windows foram adicionados e às vezes alterados ou removidos. Além disso, outros SDKs que não pertenciam ao sistema operacional principal apareceram e desapareceram. Programas mais antigos podem conter chamadas às APIs que não existem mais. Eles também podem conter chamadas às APIs em outros SDKs da Microsoft que não têm mais suporte. Você podia ver erros sobre APIs do Windows ausentes ou APIs de SDKs mais antigos da Microsoft. É possível que as APIs tenham sido removidas ou substituídas por funções mais recentes e mais seguras.

A documentação da API do Windows lista os sistemas operacionais mínimos ou máximos com suporte. Para obter informações sobre uma API específica do Windows, pesquise-a no Índice de API para aplicativos desktop do Windows.

Versão do Windows

Ao atualizar um programa que usa a API do Windows, direta ou indiretamente, você precisa decidir a versão mínima do Windows para dar suporte. Na maioria dos casos, o Windows 7 é uma boa opção. Para saber mais, confira Problemas de arquivo de cabeçalho. A macro WINVER define a versão mais antiga do Windows na qual o programa foi projetado para ser executado. Se o seu programa MFC definir WINVER como 0x0501 (Windows XP), você receberá um aviso porque o MFC não dá mais suporte ao XP, mesmo que o conjunto de ferramentas do compilador em si tenha um modo XP. O suporte ao conjunto de ferramentas do compilador para Windows XP foi encerrado no Visual Studio 2017.

Para obter mais informações, confira Como atualizar a versão de destino do Windows e Mais arquivos de cabeçalho desatualizados.

ATL / MFC

A ATL e o MFC são APIs relativamente estáveis, mas as alterações são feitas ocasionalmente. Para obter mais informações, confira o Histórico de alterações de 2003 a 2015 do Visual C++, Novidades do Visual C++ no Visual Studio e Aprimoramentos de conformidade do C++ no Visual Studio.

LNK 2005 _DllMain@12 já definido no MSVCRTD.lib

Esse erro pode ocorrer em aplicativos MFC. Ele indica um problema de ordenação entre a biblioteca CRT e a biblioteca MFC. Primeiro, o MFC deve ser vinculado para que ele forneça os operadores new e delete. Para corrigir o erro, use a opção /NODEFAULTLIB para ignorar estas bibliotecas padrão: MSVCRTD.lib e mfcs140d.lib. Em seguida, adicione essas mesmas bibliotecas como dependências adicionais.

32 bits vs 64 bits

Se seu código original for compilado para sistemas de 32 bits, você terá a opção de criar uma versão de 64 bits em vez de (ou além de) um novo aplicativo de 32 bits. Em geral, você deve fazer seu programa compilar no modo de 32 bits primeiro e então tentar o de 64 bits. O build para 64 bits é simples, mas em alguns casos ela pode revelar bugs que foram ocultados pelos builds de 32 bits.

Além disso, você deve estar atento a possíveis problemas de tempo de compilação e runtime relacionados ao tamanho do ponteiro, valores de tempo e tamanho e especificadores de formato com tamanho específico nas funções printf e scanf. Para obter mais informações, confira Configurar o Visual C++ para destinos x64 de 64 bits e Problemas comuns de migração de 64 bits do Visual C++. Para obter mais dicas de migração, confira Guia de programação para Windows de 64 bits.

Unicode vs MBCS/ASCII

Antes de o Unicode ser padronizado, muitos programas usavam o MBCS (Conjunto de Caracteres Multibyte) para representar os caracteres que não estavam incluídos no conjunto de caracteres ASCII. Em projetos MFC mais antigos, a configuração padrão era o MBCS. Ao atualizar um programa como esse, você verá avisos que aconselham usar o Unicode. Se você decidir que a conversão para o Unicode não vale o custo de desenvolvimento, poderá optar por desabilitar ou ignorar o aviso. Para desabilitá-lo para todos os projetos na solução, abra Exibir>Gerenciador de Propriedades, selecione todos os projetos para os quais deseja desabilitar o aviso, clique com o botão direito do mouse nos itens selecionados e escolha Propriedades. Na caixa de diálogo Páginas de Propriedades, selecione Propriedades de Configuração>C/C++>Avançado. Na propriedade Desabilitar Avisos Específicos, abra a seta suspensa e escolha Editar. Digite 4996 na caixa de texto. (Não inclua o prefixo "C".) Escolha OK para salvar a propriedade e, depois, OK para salvar as alterações.

Para obter mais informações, consulte Porting from MBCS to Unicode (Portabilidade de MBCS para Unicode). Para obter informações gerais sobre MBCS vs. Unicode, confira Texto e cadeias de caracteres no Visual C++ e Internacionalização.

Confira também

Como atualizar projetos de versões anteriores do Visual C++
Aprimoramentos de conformidade do C++ no Visual Studio