Solucionar problemas de falhas de inicialização de aplicativos

Este artigo descreve alguns motivos comuns e possíveis soluções para falhas de inicialização de aplicativos. Ele está relacionado a aplicativos dependentes da estrutura, que dependem de uma instalação do .NET em sua máquina.

Se você já sabe qual versão do .NET você precisa, você pode baixá-lo de downloads do .NET.

Instalação do .NET não encontrada

Se uma instalação do .NET não for encontrada, o aplicativo não será iniciado com uma mensagem semelhante a:

You must install .NET to run this application.

App: C:\repos\myapp\myapp.exe
Architecture: x64
Host version: 7.0.0
.NET location: Not found

You must install .NET to run this application.

App: /home/user/repos/myapp/myapp
Architecture: x64
Host version: 7.0.0
.NET location: Not found

You must install .NET to run this application.

App: /home/user/repos/myapp/myapp
Architecture: x64
Host version: 7.0.0
.NET location: Not found

A mensagem de erro inclui um link para baixar o .NET. Você pode seguir esse link para chegar à página de download apropriada. Você também pode escolher a versão do .NET (especificada por Host version) nos downloads do .NET.

Como alternativa, na página de download da versão .NET necessária, você pode baixar binários para a arquitetura especificada.

Quadro necessário não encontrado

Se uma estrutura necessária ou uma versão compatível não for encontrada, o aplicativo não será iniciado com uma mensagem semelhante a:

You must install or update .NET to run this application.

App: C:\repos\myapp\myapp.exe
Architecture: x64
Framework: 'Microsoft.NETCore.App', version '5.0.15' (x64)
.NET location: C:\Program Files\dotnet\

The following frameworks were found:
  6.0.2 at [c:\Program Files\dotnet\shared\Microsoft.NETCore.App]

You must install or update .NET to run this application.

App: /home/user/repos/myapp/myapp
Architecture: x64
Framework: 'Microsoft.NETCore.App', version '5.0.15' (x64)
.NET location: /usr/share/dotnet/

The following frameworks were found:
  6.0.2 at [/usr/share/dotnet/shared/Microsoft.NETCore.App]

You must install or update .NET to run this application.

App: /home/user/repos/myapp/myapp
Architecture: x64
Framework: 'Microsoft.NETCore.App', version '5.0.15' (x64)
.NET location: /usr/local/share/dotnet/

The following frameworks were found:
  6.0.2 at [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]

O erro indica o nome, a versão e a arquitetura da estrutura ausente e o local no qual se espera que ela seja instalada. Para executar o aplicativo, você pode instalar um tempo de execução compatível no "local .NET" especificado. Se o aplicativo tiver como destino uma versão inferior à que você instalou e você quiser executá-lo em uma versão superior, você também poderá configurar o comportamento de roll-forward para o aplicativo.

Instale um runtime compatível

A mensagem de erro inclui um link para baixar a estrutura ausente. Você pode seguir este link para chegar à página de download apropriada.

Como alternativa, você pode baixar um tempo de execução da página de downloads do .NET . Existem várias transferências do ambiente de execução do .NET.

A tabela a seguir mostra as estruturas que cada tempo de execução contém.

Selecione uma transferência do runtime que inclua o framework em falta e, em seguida, instale-a.

Como alternativa, na página de download da versão .NET necessária, você pode baixar binários para a arquitetura especificada.

Na maioria dos casos, quando a aplicação que não foi iniciada está a usar esse tipo de instalação, a "localização do .NET" na mensagem de erro aponta para:

Verifique a variável de ambiente DOTNET_ROOT

A DOTNET_ROOT variável ambiente indica à aplicação onde encontrar o dotnet driver e os frameworks de que precisa. Se esta variável estiver mal definida, ou apontar para um local que não contenha uma instalação válida de .NET, a aplicação falha ao iniciar mesmo quando o .NET está instalado noutro local da máquina.

Problemas comuns a observar:

• A variável aponta para uma localização errada — DOTNET_ROOT pode ser definida para um caminho de uma instalação .NET anterior, de um ambiente CI ou de um script que já não reflete a localização atual da instalação.
• A variável está definida quando não deveria — Se DOTNET_ROOT estiver definida no ambiente, o .NET ignora completamente o local de instalação predefinido. Remova ou atualize a variável se o .NET tiver sido movido.
• Desajuste de arquitetura — Use a variante específica da arquitetura ao executar aplicações de 32 bits numa máquina de 64 bits. Por exemplo, definir DOTNET_ROOT_X86 para apontar para a instalação de 32 bits. Para mais informações, consulte DOTNET_ROOT variável de ambiente.

Para diagnosticar, imprima o valor atual da variável e confirme que aponta para um diretório que contenha uma instalação válida de .NET:

echo $env:DOTNET_ROOT

echo $DOTNET_ROOT

Se a variável estiver definida, verifique se o caminho existe e contém a versão .NET esperada. Se a variável não estiver definida, o .NET volta ao local de instalação padrão da sua plataforma.

Execute o script dotnet-install

Usa o script dotnet-install quando precisares de uma instalação rápida, não administrativa, como em cenários de CI ou ambientes temporários.

O script instala .NET numa pasta que escolheres. Não se comporta como o instalador padrão do sistema operativo e cria uma instalação privada.

Para executar uma aplicação a partir dessa instalação privada, defina a DOTNET_ROOT variável de ambiente (ou a variante específica da arquitetura) quando iniciar através de um executável (conhecido como apphost), ou iniciar através do host correspondente dotnet a partir do mesmo local de instalação.

Para opções de scripts e detalhes de comportamento, consulte a referência dos scripts dotnet-install.

Baixar binários

Você pode baixar um arquivo binário do .NET na página de download. Na coluna Binários da página de transferência do runtime, transfira a distribuição binária correspondente à arquitetura necessária. Extraia o arquivo baixado para o "local .NET" especificado na mensagem de erro.

Configurar o comportamento de avanço

Se você já tiver uma versão superior da estrutura necessária instalada, poderá fazer com que o aplicativo seja executado nessa versão superior configurando seu comportamento de roll-forward.

Ao executar o aplicativo, você pode especificar a opção de linha de--roll-forward comando ou definir a variável deDOTNET_ROLL_FORWARD ambiente. Por padrão, um aplicativo requer uma estrutura que corresponda à mesma versão principal que o aplicativo destina, mas pode usar uma versão secundária ou de patch superior. No entanto, os desenvolvedores de aplicativos podem ter especificado um comportamento diferente. Para obter mais informações, consulte Roll-forward de aplicações dependentes de framework.

Consulte também

• Instale o .NET
• Locais de instalação do .NET
• Verifique as versões do .NET instaladas
• Aplicativos dependentes da estrutura