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
Isto pode dever-se a uma confusão de embalagens.
As instalações globais são registradas no seguinte local: /etc/dotnet/install_location. Para obter mais informações, consulte 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 locais de instalação.
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.
Na página de download da versão necessária do .NET, localize o download do .NET Runtime que corresponde à arquitetura listada na mensagem de erro. Em seguida, você pode instalá-lo baixando e executando um instalador.
O .NET está disponível através de vários gerenciadores de pacotes Linux. Para obter mais informações, consulte Instalar o .NET no Linux. (As versões de visualização do .NET normalmente não estão disponíveis por meio de gerenciadores de pacotes.)
Você precisa instalar o pacote .NET Runtime para a versão apropriada, como dotnet-runtime6.
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.
Instalar um tempo de execução 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. Há vários downloads de tempo de execução do .NET.
A tabela a seguir mostra as estruturas que cada tempo de execução contém.
| Download de tempo de execução | Estruturas incluídas |
|---|---|
| ASP.NET Core Runtime | Microsoft.NETCore.App Microsoft.AspNetCore.App |
| Tempo de execução do .NET Desktop | Microsoft.NETCore.App Microsoft.WindowsDesktop.App |
| Tempo de execução de .NET | Microsoft.NETCore.App |
| Download de tempo de execução | Estruturas incluídas |
|---|---|
| ASP.NET Core Runtime | Microsoft.NETCore.App Microsoft.AspNetCore.App |
| Tempo de execução de .NET | Microsoft.NETCore.App |
Selecione um download de tempo de execução que contenha a estrutura ausente e instale-o.
Na página de download da versão .NET necessária, localize o download de tempo de execução que corresponde à arquitetura listada na mensagem de erro. Você provavelmente deseja baixar um instalador.
O .NET está disponível através de vários gerenciadores de pacotes Linux. Consulte Instalar o .NET no Linux para obter detalhes. (As versões de visualização do .NET normalmente não estão disponíveis por meio de gerenciadores de pacotes.)
Você precisa instalar o pacote de tempo de execução do .NET para a versão apropriada, como dotnet-runtime6 ou dotnet-aspnet6.
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 o aplicativo que falhou ao iniciar está usando tal instalação, o "local .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 considerar.
Execute o script dotnet-install
Transfira o script dotnet-install para o seu sistema operativo. Execute o script com opções baseadas nas informações na mensagem de erro. A página de referência do 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 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 Instalação com 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 com automação bash.
Baixar binários
Você pode baixar um arquivo binário do .NET na página de download. Na coluna Binários do download do tempo de execução, baixe a versão binária correspondente à arquitetura necessária. Extraia o arquivo baixado para o "local .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 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 comando ou definir a variável de --roll-forwardDOTNET_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 aplicativos dependentes da estrutura.
Nota
Como o uso dessa 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 versões de uma estrutura.
Alterações interruptivas
Pesquisa de vários níveis desabilitada para .NET 7 e posterior
No Windows, antes do .NET 7, o aplicativo podia procurar estruturas em vários locais de instalação.
Subdiretórios relativos a:
dotnetexecutável ao executar o aplicativo atravésdotnetdo .DOTNET_ROOTvariável de ambiente (se definida) ao executar o aplicativo através de seu executável (apphost).
Local de instalação registrado globalmente (se definido) em
HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\<arch>\InstallLocation.Local de instalação padrão de (ou
%ProgramFiles(x86)%\dotnetpara processos de 32 bits no Windows de%ProgramFiles%\dotnet64 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 destinados ao .NET 7 e posterior, a pesquisa de vários níveis é completamente desabilitada e apenas um local — o primeiro local onde uma instalação do .NET é encontrada — é pesquisado. Quando um aplicativo é executado através dotnetdo , as estruturas são pesquisadas apenas em subdiretórios relativos ao dotnet. Quando um aplicativo é executado através de seu executável (apphost), as estruturas só são pesquisadas no primeiro dos locais listados anteriormente onde o .NET é encontrado.
Para obter mais informações, consulte A pesquisa em vários níveis está desativada.
