Solución de problemas de uso de herramientas de .NET

Es posible que se produzcan problemas al intentar instalar o ejecutar una herramienta .NET, que puede ser una herramienta global o una herramienta local. En este artículo se describen las causas principales comunes y algunas soluciones posibles.

La herramienta .NET instalada no se puede ejecutar

Cuando se produce un error en la ejecución de una herramienta .NET, lo más probable es que se produzca uno de los siguientes problemas:

• No se encontró el archivo ejecutable de la herramienta.
• No se encontró la versión correcta del entorno de ejecución de .NET.

No se encontró el archivo ejecutable

Si no se encuentra el archivo ejecutable, verá un mensaje similar al siguiente:

Could not execute because the specified command or file was not found.
Possible reasons for this include:
  * You misspelled a built-in dotnet command.
  * You intended to execute a .NET program, but dotnet-xyz does not exist.
  * You intended to run a global tool, but a dotnet-prefixed executable with this name could not be found on the PATH.

El nombre del archivo ejecutable determina cómo se invoca la herramienta. En la tabla siguiente se describe el formato:

Formato de nombre ejecutable	Formato de invocación
dotnet-<toolName>.exe	dotnet <toolName>
<toolName>.exe	<toolName>

Herramientas globales

Las herramientas globales se pueden instalar en el directorio predeterminado o en una ubicación específica. Los directorios predeterminados son:

Sistema operativo	Camino
Linux/macOS	$HOME/.dotnet/tools
Windows	%USERPROFILE%\.dotnet\tools

Si intenta ejecutar una herramienta global, compruebe que la variable de entorno PATH en la máquina contiene la ruta de acceso donde instaló la herramienta global y que el ejecutable está en esa ruta de acceso.

La CLI de .NET intenta agregar la ubicación predeterminada a la variable de entorno PATH en su primer uso. Sin embargo, hay algunos escenarios en los que es posible que la ubicación no se agregue automáticamente a PATH:

• Si usa Linux y ha instalado el SDK de .NET mediante archivos .tar.gz y no apt-get o rpm.
• Si usa macOS 10.15 "Catalina" o versiones posteriores.
• Si usa macOS 10.14 "Mojave" o versiones anteriores, y ha instalado el SDK de .NET con archivos .tar.gz y no .pkg.
• Si ha instalado el SDK de .NET Core 3.0 y ha establecido la variable de entorno de DOTNET_ADD_GLOBAL_TOOLS_TO_PATH en false.
• Si ha instalado el SDK de .NET Core 2.2 o versiones anteriores, y ha establecido la variable de entorno DOTNET_SKIP_FIRST_TIME_EXPERIENCE en true.

En estos casos, o si especificó la opción --tool-path al instalar una herramienta dotnet, la variable de entorno PATH del equipo no contiene automáticamente la ruta de acceso donde se instaló la herramienta global. En ese caso, anexe la ubicación de la herramienta (por ejemplo, $HOME/.dotnet/tools) a la variable de entorno PATH mediante cualquier método que proporcione el shell para actualizar las variables de entorno. Para obtener más información, vea Herramientas de .NET.

Herramientas locales

Si intenta ejecutar una herramienta local, compruebe que hay un archivo de manifiesto denominado dotnet-tools.json en el directorio actual o en cualquiera de sus directorios primarios. Este archivo también puede residir en una carpeta denominada .config en cualquier parte de la jerarquía de carpetas del proyecto, en lugar de la carpeta raíz. Si dotnet-tools.json existe, ábralo y busque la herramienta que intenta ejecutar. Si el archivo no contiene una entrada para "isRoot": true, compruebe también la jerarquía de archivos para obtener más archivos de manifiesto de herramientas.

Si está intentando ejecutar una herramienta de .NET que se instaló con una ruta de acceso especificada, debe incluir esa ruta de acceso al usar la herramienta. Un ejemplo de uso de una herramienta instalada en una ruta de acceso de herramientas es:

..\<toolDirectory>\dotnet-<toolName>

No se encontró el tiempo de ejecución

Las herramientas de .NET son aplicaciones dependientes del marco, lo que significa que dependen de un entorno de ejecución de .NET instalado en el equipo. Si no se encuentra el entorno de ejecución esperado, siguen reglas de puesta al día normales del entorno de ejecución de .NET, como:

• Una aplicación avanza a la versión de parche más alta de la versión principal y secundaria especificada.
• Si no hay ningún tiempo de ejecución coincidente con un número de versión principal y secundaria coincidente, se usa la siguiente versión secundaria superior.
• Esta puesta al día no se produce entre versiones preliminares del runtime ni entre versiones preliminares y versiones de lanzamiento. Por lo tanto, el autor debe volver a compilar y publicar las herramientas de .NET creadas con versiones preliminares y reinstalarlas.

El avance no se producirá de forma predeterminada en dos escenarios comunes:

• Solo hay disponibles versiones inferiores del entorno de ejecución. La puesta al día solo selecciona versiones posteriores del runtime.
• Solo hay disponibles versiones principales más altas del entorno de ejecución. La puesta al día no traspasa los límites de la versión principal.

Si una aplicación no encuentra un tiempo de ejecución adecuado, no se puede ejecutar e informa de un error.

Puede averiguar qué entornos de ejecución de .NET están instalados en la máquina mediante uno de los siguientes comandos:

dotnet --list-runtimes
dotnet --info

Si cree que la herramienta debe admitir la versión en tiempo de ejecución que tiene instalada actualmente, puede ponerse en contacto con el autor de la herramienta y ver si pueden actualizar el número de versión o el destino múltiple. Una vez que han recompilado y republicado el paquete de herramientas en NuGet con un número de versión actualizado, puede actualizar su copia. Aunque esto no sucede, la solución más rápida para usted es instalar una versión del entorno de ejecución que funcionaría con la herramienta que está intentando ejecutar. Para descargar una versión específica del entorno de ejecución de .NET, visite la página de descarga de .NET .

Si instala el SDK de .NET en una ubicación no predeterminada, debe establecer la variable de entorno DOTNET_ROOT en el directorio que contiene el archivo ejecutable dotnet.

Error en la instalación de la herramienta .NET

Hay varias razones por las que se puede producir un error en la instalación de una herramienta global o local de .NET. Cuando se produzca un error en la instalación de la herramienta, verá un mensaje similar al siguiente:

Tool '{0}' failed to install. This failure may have been caused by:

* You are attempting to install a preview release and did not use the --version option to specify the version.
* A package by this name was found, but it was not a .NET tool.
* The required NuGet feed cannot be accessed, perhaps because of an Internet connection problem.
* You mistyped the name of the tool.

For more reasons, including package naming enforcement, visit https://aka.ms/failure-installing-tool

Para ayudar a diagnosticar estos errores, los mensajes NuGet se muestran directamente al usuario, junto con el mensaje anterior. El mensaje de NuGet puede ayudarle a identificar el problema.

• Aplicación de normas de nomenclatura de paquetes
• Versiones preliminares
• Package no es una herramienta de .NET
• No se puede acceder al feed de NuGet
• id. de paquete incorrecto
• 401 (No autorizado)

Cumplimiento de la nomenclatura de los paquetes

Microsoft ha cambiado sus instrucciones sobre el identificador de paquete para las herramientas, lo que da lugar a que no se encuentren varias herramientas con el nombre previsto. La nueva guía es que todas las herramientas de Microsoft deben tener el prefijo "Microsoft". Este prefijo está reservado y solo se puede usar para paquetes firmados con un certificado autorizado de Microsoft.

Durante la transición, algunas herramientas de Microsoft tendrán la forma antigua del identificador del paquete, mientras que otras tendrán el nuevo formulario:

dotnet tool install -g Microsoft.<toolName>
dotnet tool install -g <toolName>

A medida que se actualizan los identificadores de paquete, deberá cambiar al nuevo identificador de paquete para obtener las actualizaciones más recientes. Los paquetes con el nombre de la herramienta simplificada quedarán en desuso.

Versiones preliminares

• Está intentando instalar una versión preliminar y no usó la opción --version para especificar la versión.

Las herramientas de .NET que están en versión preliminar deben especificarse con una parte del nombre para indicar que están en versión preliminar. No es necesario incluir toda la versión preliminar. Suponiendo que los números de versión están en el formato esperado, puede usar algo parecido al ejemplo siguiente:

dotnet tool install -g --version 1.1.0-pre <toolName>

El paquete no es una herramienta de .NET

• Se encontró un paquete NuGet con este nombre, pero no era una herramienta de .NET.

Si intenta instalar un paquete NuGet que es un paquete NuGet normal y no una herramienta .NET, verá un error similar al siguiente:

NU1212: combinación de paquete de proyecto no válida para <toolName>. El estilo del proyecto DotnetToolReference solo puede contener referencias del tipo DotnetTool.

No se puede acceder al flujo de NuGet

• No se puede acceder a la fuente de NuGet necesaria, quizás debido a un problema de conexión a Internet.

La instalación de herramientas requiere acceso a la fuente NuGet que contiene el paquete de herramientas. Se produce un error si la fuente no está disponible. Puede alterar los flujos de datos con nuget.config, solicitar un archivo específico de nuget.config o especificar flujos de datos adicionales con el conmutador --add-source. De forma predeterminada, NuGet genera un error para cualquier fuente con la que no se pueda conectar. La marca --ignore-failed-sources puede omitir estos orígenes no accesibles.

El identificador de paquete es incorrecto

• Ha escrito mal el nombre de la herramienta.

Un motivo común de error es que el nombre de la herramienta no es correcto. Esto puede ocurrir debido a errores tipográficos, o porque la herramienta se ha movido o ha quedado obsoleta. Para las herramientas de NuGet.org, una manera de asegurarse de que tiene el nombre correcto es buscar la herramienta en NuGet.org y copiar el comando de instalación.

401 (no autorizado)

Lo más probable es que haya especificado una fuente de NuGet alternativa y esa fuente requiere autenticación. Hay varias maneras diferentes de resolver esto:

• Agregue el parámetro --ignore-failed-sources para omitir el error de la fuente privada y usar la fuente pública de Microsoft.

  Si va a instalar una herramienta desde la fuente NuGet de Microsoft, la fuente personalizada devuelve este error antes de que la fuente NuGet de Microsoft devuelva un resultado. El error finaliza la solicitud, cancelando cualquier otra solicitud de fuente pendiente, que podría ser la fuente NuGet de Microsoft. Agregar la opción --ignore-failed-sources hace que el comando trate este error como una advertencia y permite que otras fuentes procesen la solicitud.

  dotnet tool install -g --ignore-failed-sources <toolName>
  

• Fuerce la fuente de NuGet de Microsoft con el parámetro --add-source.

  Es posible que al archivo de configuración de NuGet global o local le falte el canal público de NuGet de Microsoft. Use una combinación de los parámetros --add-source y --ignore-failed-sources para evitar la fuente errónea y confiar en la fuente pública de Microsoft.

  dotnet tool install -g --add-source 'https://api.nuget.org/v3/index.json' --ignore-failed-sources <toolName>
  

• Use una configuración personalizada de NuGet, el parámetro --configfile <FILE>.

  Cree un archivo nuget.config local con solo la fuente pública de NuGet de Microsoft y haga referencia a él con el parámetro --configfile:

  dotnet tool install -g --configfile "./nuget.config" <toolName>
  

  Este es un archivo de configuración de ejemplo:

  <?xml version="1.0" encoding="utf-8"?>
  <configuration>
    <packageSources>
      <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
    </packageSources>
  </configuration>
  

  Para obtener más información, vea la referencia de nuget.config.

• Agregue las credenciales necesarias al archivo de configuración.

  Si sabe que el paquete existe en la fuente configurada, proporcione las credenciales de inicio de sesión en el archivo de configuración de NuGet. Para obtener más información sobre las credenciales en un archivo de configuración de NuGet, consulte la sección packageSourceCredentials de la referencia nuget.config.

Consulte también

• Herramientas de .NET