Compartilhar via

Solucionar problemas de falhas de inicialização do aplicativo

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 seu computador.

Se você já souber qual versão do .NET precisa, poderá baixá-la nos downloads do .NET.

Instalação do .NET não encontrada

Se uma instalação do .NET não for encontrada, o aplicativo falhará ao iniciar 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

Isso pode ser devido a uma combinação de pacotes.

As instalações globais são registradas no seguinte local: /etc/dotnet/install_location. Para obter mais informações, consulte os locais de instalação.

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

As instalações globais são registradas no seguinte local: /etc/dotnet/install_location. Para obter mais informações, consulte os locais de instalação.

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

Na página de download da versão necessária do .NET, localize o download do Runtime do .NET que corresponde à arquitetura listada na mensagem de erro. Em seguida, você pode instalá-lo baixando e executando um Instalador.

O .NET está disponível por meio de vários gerenciadores de pacotes do Linux. Para obter mais informações, consulte Instalar o .NET no Linux. (As versões prévias do .NET normalmente não estão disponíveis por meio de gerenciadores de pacotes.)

Você precisa instalar o pacote do Runtime do .NET para a versão apropriada, como dotnet-runtime6.

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

Estrutura necessária não encontrada

Se uma estrutura necessária ou uma versão compatível não for encontrada, o aplicativo falhará ao iniciar 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 ela deverá ser instalada. Para executar o aplicativo, você pode instalar um runtime compatível no "local do .NET" especificado. Se o aplicativo tiver como destino uma versão inferior à que você instalou e quiser executá-la em uma versão mais alta, você também poderá configurar o comportamento de roll-forward para o aplicativo.

Instalar um runtime compatível

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

Como alternativa, você pode baixar um runtime na página de downloads do .NET . Há vários downloads de runtime do .NET.

A tabela a seguir mostra as estruturas que cada runtime contém.

Download do runtime Estruturas incluídas
ASP.NET Core Runtime Microsoft.NETCore.App
Microsoft.AspNetCore.App
Runtime da Área de Trabalho do .NET Microsoft.NETCore.App
Microsoft.WindowsDesktop.App
Runtime do .NET Microsoft.NETCore.App
Download do runtime Estruturas incluídas
ASP.NET Core Runtime Microsoft.NETCore.App
Microsoft.AspNetCore.App
Runtime do .NET Microsoft.NETCore.App

Selecione um download de runtime que contenha a estrutura ausente e instale-a.

Na página de download da versão necessária do .NET, localize o download do runtime que corresponde à arquitetura listada na mensagem de erro. Você provavelmente deseja baixar um Instalador.

O .NET está disponível por meio de vários gerenciadores de pacotes do Linux. Consulte Instalar o .NET no Linux para obter detalhes. (As versões prévias do .NET normalmente não estão disponíveis por meio de gerenciadores de pacotes.)

Você precisa instalar o pacote de runtime do .NET para a versão apropriada, como dotnet-runtime6 ou dotnet-aspnet6.

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

Na maioria dos casos, quando o aplicativo que não foi iniciado está usando essa instalação, o "local do .NET" na mensagem de erro aponta para:

%ProgramFiles%\dotnet

/usr/share/dotnet/

/usr/local/share/dotnet/

Outras opções

Há outras opções de instalação e solução alternativa a serem consideradas.

Executar o script dotnet-install

Baixe o script dotnet-install para seu sistema operacional. Execute o script com opções com base nas informações na mensagem de erro. A página de referência de script dotnet-install mostra todas as opções disponíveis.

Inicie o PowerShell e execute:

dotnet-install.ps1 -Architecture <architecture> -InstallDir <directory> -Runtime <runtime> -Version <version>

Por exemplo, a mensagem de erro na seção anterior corresponderia a:

dotnet-install.ps1 -Architecture x64 -InstallDir "C:\Program Files\dotnet\" -Runtime dotnet -Version 5.0.15

Se você encontrar um erro informando que a execução de scripts está desabilitada, talvez seja necessário definir a política de execução para permitir que o script seja executado:

Set-ExecutionPolicy Bypass -Scope Process

Para obter mais informações sobre a instalação usando o script, consulte Instalar com a automação do PowerShell.

./dotnet-install.sh --architecture <architecture> --install-dir <directory> --runtime <runtime> --version <version>

Por exemplo, a mensagem de erro na seção anterior corresponderia a:

./dotnet-install.sh --architecture x64 --install-dir /usr/share/dotnet/ --runtime dotnet --version 5.0.15

Para obter mais informações sobre a instalação usando o script, consulte a instalação do Script.

./dotnet-install.sh --architecture <architecture> --install-dir <directory> --runtime <runtime> --version <version>

Por exemplo, a mensagem de erro na seção anterior corresponderia a:

./dotnet-install.sh --architecture x64 --install-dir /usr/local/share/dotnet/ --runtime dotnet --version 5.0.15

Para obter mais informações sobre a instalação usando o script, consulte Instalar o .NET com um script.

Baixar binários

Você pode baixar um arquivo binário do .NET na página de download. Na coluna Binários do download do runtime, baixe a versão binária que corresponde à arquitetura necessária. Extraia o arquivo morto baixado para o "local do .NET" especificado na mensagem de erro.

Para obter mais informações sobre a instalação manual, consulte Instalar o .NET no Windows

Para obter mais informações sobre a instalação manual, consulte Instalar o .NET no Linux

Para obter mais informações sobre a instalação manual, consulte Instalar o .NET no macOS

Configurar o comportamento de roll-forward

Se você já tiver uma versão mais alta 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--roll-forward linha de 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 visa, mas pode usar uma versão secundária ou de patch mais alta. No entanto, os desenvolvedores de aplicativos podem ter especificado um comportamento diferente. Para obter mais informações, consulte roll-forward de aplicativos dependentes do Framework.

Observação

Como usar essa opção permite que o aplicativo seja executado em uma versão de estrutura diferente daquela para a qual ele foi projetado, isso pode resultar em um comportamento não intencional devido a alterações entre as versões de uma estrutura.

Alterações da falha

Pesquisa de vários níveis desabilitada para .NET 7 e posterior

No Windows, antes do .NET 7, o aplicativo poderia pesquisar estruturas em vários locais de instalação.

  1. Subdiretórios relativos a:

    • dotnet executável ao executar o aplicativo por meio dotnetde .
    • DOTNET_ROOT variável de ambiente (se definida) ao executar o aplicativo por meio de seu executável (apphost).

  2. Local de instalação registrado globalmente (se definido) em HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\<arch>\InstallLocation.

  3. Local de instalação padrão ( %ProgramFiles%\dotnet ou %ProgramFiles(x86)%\dotnet para processos de 32 bits no Windows de 64 bits).

Esse comportamento de pesquisa de vários níveis foi habilitado por padrão, mas pode ser desabilitado definindo a variável DOTNET_MULTILEVEL_LOOKUP=0de ambiente.

Para aplicativos direcionados ao .NET 7 e posterior, a pesquisa de vários níveis está completamente desabilitada e apenas um local , o primeiro local onde uma instalação do .NET é encontrada, é pesquisado. Quando um aplicativo é executado, dotnetas estruturas são pesquisadas apenas em subdiretórios relativos a dotnet. Quando um aplicativo é executado por meio de seu executável (apphost), as estruturas são pesquisadas apenas no primeiro dos locais listados anteriormente em que o .NET é encontrado.

Para obter mais informações, consulte Se a pesquisa de vários níveis está desabilitada.

Consulte também

  • Last updated on