Solucionar problemas de inicio de las aplicaciones

  • Artículo

En este artículo se describen algunas causas habituales de los errores de inicio de las aplicaciones y sus posibles soluciones. Se relaciona con las aplicaciones dependientes del marco, que se basan en una instalación de .NET en la máquina.

Si ya sabe qué versión de .NET necesita, puede descargarla desde Descargas de .NET.

No se encontró la instalación de .NET

Si no se encuentra una instalación de .NET, la aplicación no se inicia y aparece un mensaje similar al siguiente:

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

Esto puede deberse a una mezcla de paquetes.

Las instalaciones globales se registran en la ubicación siguiente: /etc/dotnet/install_location. Para obtener más información, vea las ubicaciones de instalación.

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

Las instalaciones globales se registran en la ubicación siguiente: /etc/dotnet/install_location. Para obtener más información, vea las ubicaciones de instalación.

El mensaje de error incluye un vínculo para descargar .NET. Puede seguir ese vínculo para acceder a la página de descarga adecuada. También puede elegir la versión de .NET (especificada por Host version) en Descargas de .NET.

En la página de descargas de la versión de .NET necesaria, busque la descarga de .NET Runtime que coincida con la arquitectura que aparece en el mensaje de error. Después, puede instalarlo descargando y ejecutando un Instalador.

.NET está disponible en varios administradores de paquetes de Linux. Para obtener más información, vea Instalación de .NET en Linux. (Las versiones preliminares de .NET no suelen estar disponibles a través de los administradores de paquetes).

Debe instalar el paquete de .NET Runtime para la versión adecuada, como dotnet-runtime6.

Como alternativa, en la página de descargas de la versión de .NET necesaria, puede descargar archivos binarios para la arquitectura especificada.

No se encontró el marco necesario

Si no se encuentra un marco necesario o una versión compatible, la aplicación no se inicia y aparece un mensaje similar al siguiente:

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]

El error indica el nombre, la versión y la arquitectura del marco que falta, así como la ubicación en la que se espera que se instale. Para ejecutar la aplicación, puede instalar un runtime compatible en la “ubicación de .NET” especificada. Si la aplicación tiene como destino una versión anterior a la que ha instalado y quiere ejecutarla en una versión posterior, también puede configurar el comportamiento de puesta al día de la aplicación.

Instalación de un runtime compatible

El mensaje de error incluye un vínculo para descargar el marco que falta. Puede seguir este vínculo para acceder a la página de descargas adecuada.

Como alternativa, puede descargar un runtime desde la página de Descargas de .NET. Hay varias descargas de .NET Runtime.

En la tabla siguiente se muestran los marcos que contiene cada runtime.

Descarga de runtime Marcos incluidos
ASP.NET Core Runtime Microsoft.NETCore.App
Microsoft.AspNetCore.App
.NET Desktop Runtime Microsoft.NETCore.App
Microsoft.WindowsDesktop.App
Runtime de .NET Microsoft.NETCore.App
Descarga de runtime Marcos incluidos
ASP.NET Core Runtime Microsoft.NETCore.App
Microsoft.AspNetCore.App
Runtime de .NET Microsoft.NETCore.App

Seleccione la descarga de un entorno de ejecución que contenga el marco que falta e instálelo.

En la página de descargas de la versión de .NET necesaria, busque la descarga de runtime que coincida con la arquitectura que aparece en el mensaje de error. Es probable que quiera descargar un instalador.

.NET está disponible en varios administradores de paquetes de Linux. Consulte Instalación de .NET en Linux para más información. (Las versiones preliminares de .NET no suelen estar disponibles a través de los administradores de paquetes).

Debe instalar el paquete de .NET Runtime para la versión adecuada, como dotnet-runtime6 o dotnet-aspnet6.

Como alternativa, en la página de descargas de la versión de .NET necesaria, puede descargar archivos binarios para la arquitectura especificada.

En la mayoría de los casos, cuando la aplicación que no pudo iniciarse está usando una instalación de ese tipo, la “ubicación .NET” del mensaje de error apunta a:

%ProgramFiles%\dotnet

/usr/share/dotnet/

/usr/local/share/dotnet/

Otras opciones

Hay otras opciones de instalación y soluciones alternativas que puede tener en cuenta.

Ejecutar el script de dotnet-install

Descargue el script dotnet-install para su sistema operativo. Ejecute el script configurando las opciones según la información del mensaje de error. La página de referencia del script dotnet-install muestra todas las opciones disponibles.

Inicie PowerShell y ejecute:

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

Por ejemplo, el mensaje de error de la sección anterior correspondería a:

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

Si se produce un error que indica que la ejecución de scripts está deshabilitada, es posible que tenga que establecer la directiva de ejecuciones para permitir que el script se ejecute:

Set-ExecutionPolicy Bypass -Scope Process

Para obtener más información sobre la instalación mediante el script, consulte Instalación mediante la automatización de PowerShell.

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

Por ejemplo, el mensaje de error de la sección anterior correspondería a:

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

Para obtener más información sobre la instalación mediante el script, consulte Instalación con script.

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

Por ejemplo, el mensaje de error de la sección anterior correspondería a:

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

Para obtener más información sobre la instalación mediante el script, consulte Instalación mediante la automatización de Bash.

Descargar archivos binarios

Puede descargar un archivo binario de .NET desde la página de descargas. En la columna Binarios de la descarga del runtime, descargue la versión que coincida con la arquitectura necesaria. Extraiga el archivo descargado en la “ubicación .NET” especificada en el mensaje de error.

Para obtener más información acerca de la instalación manual, consulte Instalación de .NET en Windows

Para obtener más información acerca de la instalación manual, consulte Instalación de .NET en Linux

Para obtener más información acerca de la instalación manual, consulte Instalación de .NET en macOS

Configuración del comportamiento de puesta al día

Si ya tiene instalada una versión posterior del marco necesario, puede hacer que la aplicación se ejecute en esa versión posterior configurando su comportamiento de puesta al día.

Al ejecutar la aplicación, puede especificar la --roll-forward opción de línea de comandos o establecer la DOTNET_ROLL_FORWARDvariable de entorno. De manera predeterminada, una aplicación requiere un marco que coincida con la misma versión principal a la que se dirige la aplicación, pero puede usar una versión posterior si esta es secundaria o de revisión. Sin embargo, los desarrolladores de aplicaciones pueden haber especificado un comportamiento diferente. Para obtener más información, consulte Puesta al día de aplicaciones dependientes de la plataforma.

Nota

Dado que el uso de esta opción permite que la aplicación se ejecute en una versión de marco diferente a la prevista en su diseño, puede haber comportamientos no deseados debido a los cambios entre las versiones del marco.

Últimos cambios

Búsqueda de varios niveles deshabilitada para .NET 7 y versiones posteriores

En Windows, antes de .NET 7, la aplicación podía buscar marcos en varias ubicaciones de instalación.

  1. Subdirectorios relativos a:

    • Ejecutable de dotnet al ejecutar la aplicación mediante dotnet.
    • Variable de entorno DOTNET_ROOT (si se establece) al ejecutar la aplicación mediante su ejecutable (apphost).

  2. Ubicación de instalación registrada globalmente (si se establece) en HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\<arch>\InstallLocation.

  3. Ubicación de instalación predeterminada de %ProgramFiles%\dotnet (o de %ProgramFiles(x86)%\dotnet para procesos de 32 bits en Windows de 64 bits).

Este comportamiento de búsqueda de varios niveles se ha habilitado de manera predeterminada, pero se puede deshabilitar estableciendo la variable de entorno DOTNET_MULTILEVEL_LOOKUP=0.

En el caso de las aplicaciones destinadas a .NET 7 y versiones posteriores, la búsqueda de varios niveles está completamente deshabilitada y solo se busca en una ubicación: la primera en la que se encuentre una instalación de .NET. Cuando una aplicación se ejecuta mediante dotnet, los marcos solo se buscan en subdirectorios relativos a dotnet. Cuando una aplicación se ejecuta mediante su ejecutable (apphost), los marcos solo se buscan en la primera de las ubicaciones enumeradas anteriormente en las que se encuentre .NET.

Para más información, consulte Búsqueda de varios niveles deshabilitada.

Consulte también