Erros de inicialização do .NET Framework: Gerenciando a experiência do usuário
Nota
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 conseguir encontrar uma versão do CLR para carregar. Essa situação normalmente ocorre quando um aplicativo requer uma versão CLR que é 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 retorna um código de erro HRESULT da função ou interface que foi chamada e pode 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 ajudá-lo 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 logs de vinculação de montagem, que são totalmente diferentes.
Códigos HRESULT de ativação CLR
As APIs de ativação CLR retornam códigos HRESULT para relatar o resultado de uma operação de ativação para um host. Os hosts CLR devem sempre consultar esses valores de retorno 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 tempo de execução 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 fornecerá a eles uma oportunidade de corrigir a situação. A seguinte mensagem de erro é normalmente apresentada nesta situação. O usuário pode escolher Sim para ir para um site da Microsoft onde pode baixar a versão correta do .NET Framework para o aplicativo.
Resolvendo o erro de inicialização
Como desenvolvedor, você tem uma variedade de 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 impedia seu aplicativo de carregar o tempo de execução solicitado. Caso contrário, seu aplicativo pode não ser executado ou algumas funcionalidades podem não estar disponíveis.
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 oferecer suporte ao .NET Framework 4 ou versões posteriores (consulte 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 Guia de implantação para desenvolvedores.
Controlando a mensagem de erro
A exibição de uma mensagem de erro para comunicar que uma versão solicitada do .NET Framework não foi encontrada pode ser vista como um serviço útil ou um pequeno incômodo para os usuários. Em ambos os casos, você pode controlar essa interface do usuário passando sinalizadores 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 solicitada do CLR não for encontrada. Por padrão, a mensagem de erro não é exibida. (O 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 de 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 de aplicativo. Por exemplo, se você tiver um componente COM nativo que hospeda o CLR e que está hospedado em um processo em que SEM_FAILCRITICALERRORS está definido, convém substituir o sinalizador, dependendo do impacto da exibição de mensagens de erro nesse processo de aplicativo específico. Nesse caso, você pode usar um dos seguintes sinalizadores para substituir SEM_FAILCRITICALERRORS:
Use METAHOST_POLICY_IGNORE_ERROR_MODE com o método ICLRMetaHostPolicy::GetRequestedRuntime .
Use RUNTIME_INFO_IGNORE_ERROR_MODE com a função GetRequestedRuntimeInfo .
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 tempo de execução. A tabela a seguir fornece uma lista de hosts e suas políticas de mensagem de erro.
| Host CLR | Description | Política de mensagens de erro | A mensagem de erro pode ser desativada? |
|---|---|---|---|
| Host EXE gerenciado | Inicia EXEs gerenciados. | É mostrado no caso de uma versão do .NET Framework ausente | Não |
| Host COM gerenciado | Carrega componentes COM gerenciados em um processo. | É mostrado no caso de uma versão do .NET Framework ausente | Sim, definindo o sinalizador SEM_FAILCRITICALERRORS |
| Anfitrião ClickOnce | Inicia 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 WPF XBAP. | É 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 que em outras versões do sistema operacional Windows, exceto quando encontra problemas ao carregar o 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 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 seguinte caixa de diálogo 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.
Nota
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 do .NET Framework 1.0 e 1.1, desde que esses aplicativos não estejam explicitamente configurados para serem executados 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.
