Compartilhar via

Erros de inicialização do .NET Framework: Gerenciando a experiência do usuário

Observação

Este artigo é específico do .NET Framework. Ele não se aplica a implementações mais recentes do .NET, incluindo o .NET 6 e versões posteriores.

O sistema de ativação clr (common language runtime) determina a versão do CLR que será usada para executar o código do aplicativo gerenciado. Em alguns casos, o sistema de ativação pode não ser capaz de encontrar uma versão do CLR para carregar. Essa situação normalmente ocorre quando um aplicativo requer uma versão CLR inválida ou não instalada em um determinado computador. Se a versão solicitada não for encontrada, o sistema de ativação CLR retornará um código de erro HRESULT da função ou interface que foi chamada e poderá exibir uma mensagem de erro para o usuário que está executando o aplicativo. Este artigo fornece uma lista de códigos HRESULT e explica como você pode impedir que a mensagem de erro seja exibida.

O CLR fornece infraestrutura de log para ajudar a depurar problemas de ativação do CLR, conforme descrito em Como depurar problemas de ativação do CLR. Essa infraestrutura não deve ser confundida com os logs de associação do assembly, que são totalmente diferentes.

Códigos HRESULT de ativação do CLR

As APIs de ativação CLR retornam códigos HRESULT para comunicar o resultado de uma operação de ativação a um host. Os hosts CLR sempre devem consultar esses valores retornados antes de prosseguir com operações adicionais.

  • CLR_E_SHIM_RUNTIMELOAD

  • CLR_E_SHIM_RUNTIMEEXPORT

  • CLR_E_SHIM_INSTALLROOT

  • CLR_E_SHIM_INSTALLCOMP

  • CLR_E_SHIM_LEGACYRUNTIMEALREADYBOUND

  • CLR_E_SHIM_SHUTDOWNINPROGRESS

Interface do usuário para erros de inicialização

Se o sistema de ativação CLR não puder carregar a versão correta do runtime exigida por um aplicativo, ele exibirá uma mensagem de erro aos usuários para informá-los de que seu computador não está configurado corretamente para executar o aplicativo e oferece a eles uma oportunidade de corrigir a situação. A mensagem de erro a seguir normalmente é apresentada nessa situação. O usuário pode escolher Sim para ir a um site da Microsoft onde pode baixar a versão correta do .NET Framework para o aplicativo.

Caixa de diálogo Erro de Inicialização do .NET Framework

Resolvendo o erro de inicialização

Como desenvolvedor, você tem várias opções para controlar a mensagem de erro de inicialização do .NET Framework. Por exemplo, você pode usar um sinalizador de API para impedir que a mensagem seja exibida, conforme discutido na próxima seção. No entanto, você ainda precisa resolver o problema que impediu o aplicativo de carregar o runtime solicitado. Caso contrário, seu aplicativo pode não ser executado ou alguma funcionalidade pode não estar disponível.

Para resolver os problemas subjacentes e fornecer a melhor experiência do usuário (menos mensagens de erro), recomendamos o seguinte:

  • Para aplicativos do .NET Framework 3.5 (e anteriores): configure seu aplicativo para dar suporte ao .NET Framework 4 ou versões posteriores (confira as instruções).

  • Para aplicativos do .NET Framework 4: instale o pacote redistribuível do .NET Framework 4 como parte da configuração do aplicativo. Consulte o Guia de Implantação para Desenvolvedores.

Controlando a mensagem de erro

Exibir uma mensagem de erro para comunicar que uma versão solicitada do .NET Framework não foi encontrada pode ser exibida como um serviço útil ou um pequeno incômodo para os usuários. Em ambos os casos, você pode controlar essa UI passando flags para as APIs de ativação.

O método ICLRMetaHostPolicy::GetRequestedRuntime aceita um membro de enumeração METAHOST_POLICY_FLAGS como entrada. Você pode incluir o sinalizador METAHOST_POLICY_SHOW_ERROR_DIALOG para solicitar uma mensagem de erro se a versão do CLR solicitada não for encontrada. Por padrão, a mensagem de erro não é exibida. (O método ICLRMetaHost::GetRuntime não aceita esse sinalizador e não fornece nenhuma outra maneira de exibir a mensagem de erro.)

O Windows fornece uma função SetErrorMode que você pode usar para declarar se deseja que as mensagens de erro sejam mostradas como resultado do código executado em seu processo. Você pode especificar o sinalizador SEM_FAILCRITICALERRORS para impedir que a mensagem de erro seja exibida.

No entanto, em alguns cenários, é importante substituir a configuração de SEM_FAILCRITICALERRORS definida por um processo do aplicativo. Por exemplo, se você tiver um componente COM nativo que hospeda o CLR e que é hospedado em um processo em que SEM_FAILCRITICALERRORS está definido, talvez queira substituir o sinalizador, dependendo do impacto de exibir mensagens de erro naquele processo de aplicativo específico. Nesse caso, você pode usar um dos sinalizadores a seguir para substituir SEM_FAILCRITICALERRORS:

Política de interface do usuário para hosts fornecidos por CLR

O CLR inclui um conjunto de hosts para uma variedade de cenários, e todos esses hosts exibem uma mensagem de erro quando encontram problemas ao carregar a versão necessária do runtime. A tabela a seguir fornece uma lista de hosts e suas políticas de mensagem de erro.

Host do CLR Descrição Política de mensagem de erro A mensagem de erro pode ser desabilitada?
Host EXE gerenciado Inicia EXEs gerenciados. É mostrado no caso de uma versão ausente do .NET Framework Não
Host COM gerenciado Carrega componentes COM gerenciados em um processo. É mostrado no caso de uma versão ausente do .NET Framework Sim, definindo o sinalizador SEM_FAILCRITICALERRORS
Host ClickOnce Inicia os aplicativos ClickOnce. É mostrado no caso de uma versão ausente do .NET Framework, começando com o .NET Framework 4.5 Não
Host XBAP Inicia aplicativos XBAP do WPF. É mostrado no caso de uma versão ausente do .NET Framework, começando com o .NET Framework 4.5 Não

Comportamento e interface do usuário do Windows 8

O sistema de ativação CLR fornece o mesmo comportamento e interface do usuário no Windows 8 como em outras versões do sistema operacional Windows, exceto quando encontra problemas ao carregar CLR 2.0. O Windows 8 inclui o .NET Framework 4.5, que usa CLR 4.5. No entanto, o Windows 8 não inclui o .NET Framework 2.0, 3.0 ou 3.5, que todos usam CLR 2.0. Como resultado, os aplicativos que dependem do CLR 2.0 não são executados no Windows 8 por padrão. Em vez disso, eles exibem a caixa de diálogo a seguir para permitir que os usuários instalem o .NET Framework 3.5. Os usuários também podem habilitar o .NET Framework 3.5 no Painel de Controle. Ambas as opções são discutidas no artigo Instalar o .NET Framework 3.5 no Windows 11, Windows 10, Windows 8.1 e Windows 8.

Caixa de diálogo para instalação da versão 3.5 no Windows 8

Observação

O .NET Framework 4.5 substitui o .NET Framework 4 (CLR 4) no computador do usuário. Portanto, os aplicativos do .NET Framework 4 são executados perfeitamente, sem exibir essa caixa de diálogo, no Windows 8.

Quando o .NET Framework 3.5 é instalado, os usuários podem executar aplicativos que dependem do .NET Framework 2.0, 3.0 ou 3.5 em seus computadores Windows 8. Eles também podem executar aplicativos .NET Framework 1.0 e 1.1, desde que esses aplicativos não estejam explicitamente configurados para execução somente no .NET Framework 1.0 ou 1.1. Consulte Migrando do .NET Framework 1.1.

A partir do .NET Framework 4.5, o log de ativação do CLR foi aprimorado para incluir entradas de log que registram quando e por que a mensagem de erro de inicialização é exibida. Para obter mais informações, consulte Como depurar problemas de ativação do CLR.

Consulte também