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 de 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 dos 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
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, confira 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, confira locais de instalação.
A mensagem de erro inclui um link para baixar o .NET. Você pode acessar este link para visitar 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, instale baixando e executando o Instalador.
O .NET está disponível por meio de vários gerenciadores de pacotes do Linux. Para saber mais, confira 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 .NET Runtime 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 desejada.
Estrutura necessária não encontrada
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 runtime compatível no "local do .NET" especificado. Se o aplicativo for direcionado a uma versão inferior à que você instalou e você quiser executá-lo em uma versão mais alta, você também poderá configurar o comportamento de roll-forward do aplicativo.
Instalar um runtime compatível
A mensagem de erro inclui um link para baixar a estrutura ausente. Você pode acessar este link para visitar 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 disponíveis.
A tabela a seguir mostra as estruturas que cada runtime contém.
| Download do runtime | Estruturas incluídas |
|---|---|
| Runtime do ASP.NET Core | Microsoft.NETCore.App Microsoft.AspNetCore.App |
| Runtime do .NET Desktop | Microsoft.NETCore.App Microsoft.WindowsDesktop.App |
| Execução do .NET | Microsoft.NETCore.App |
| Download do runtime | Estruturas incluídas |
|---|---|
| Runtime do ASP.NET Core | Microsoft.NETCore.App Microsoft.AspNetCore.App |
| Execução do .NET | Microsoft.NETCore.App |
Selecione um download de runtime que contém a estrutura ausente e instale-a.
Na página de download da versão necessária do .NET, localize o download de 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. Confira 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 desejada.
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 dotnet-install script para seu sistema operacional. Execute o script com as opções baseadas nas informações da mensagem de erro. A página de referência do dotnet-install script 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, confira 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, confira Instalação por 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, confira Instalar com a automação do bash.
Baixar binários
Você pode baixar um arquivo binário do .NET na página de download. Na coluna Binaries do download do runtime, baixe a versão binária que corresponde à arquitetura necessária. Extraia o arquivo 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
Controlar 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 linha de comando --roll-forward ou definir a variável de ambiente DOTNET_ROLL_FORWARD.
Por padrão, um aplicativo requer uma estrutura que corresponda à mesma versão principal direcionada ao aplicativo, 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, confira Roll forward de aplicativos dependentes de estrutura.
Observação
Como usar essa opção permite que o aplicativo seja executado em uma versão de estrutura diferente daquela para a qual foi projetado, isso pode resultar em comportamento não intencional devido a alterações entre as versões de uma estrutura.
Alterações de quebra
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.
Subdiretórios relativos a:
- Executável
dotnetao executar o aplicativo por meio dedotnet. - Variável de ambiente
DOTNET_ROOT(se definida) ao executar o aplicativo por meio do executável (apphost).
- Executável
Local de instalação registrado globalmente (se definido) em
HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\<arch>\InstallLocation.Local de instalação padrão de
%ProgramFiles%\dotnet(ou%ProgramFiles(x86)%\dotnetpara 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 de ambiente DOTNET_MULTILEVEL_LOOKUP=0.
Para aplicativos direcionados ao .NET 7 e posteriores, a pesquisa de vários níveis está completamente desabilitada e apenas um local – o primeiro local em que uma instalação do .NET é encontrada – é pesquisado. Ao executar um aplicativo por meio de dotnet, as estruturas são pesquisadas apenas em subdiretórios relativos a dotnet. Ao executar um aplicativo por meio do 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, confira A pesquisa em vários níveis está desabilitada.
