Administración de herramientas de .NET

Este artículo se aplica a: ✔️ SDK de .NET Core 2.1 y versiones posteriores.

Una herramienta .NET es un paquete NuGet especial que contiene una aplicación de consola. Puede instalar una herramienta en el equipo de las maneras siguientes:

• Como herramienta global.

  Los archivos binarios de herramientas se instalan en un directorio predeterminado que se agrega a la variable de entorno PATH. Puede invocar la herramienta desde cualquier directorio de la máquina sin especificar su ubicación. Se usa una versión de una herramienta para todos los directorios de la máquina.

• Como herramienta global en una ubicación personalizada (también conocida como herramienta de ruta de acceso de herramientas).

  Los archivos binarios de herramientas se instalan en una ubicación que especifique. Puede invocar la herramienta desde el directorio de instalación, proporcionando el directorio con el nombre del comando o agregando el directorio a la variable de entorno PATH. Se usa una versión de una herramienta para todos los directorios de la máquina.

• Como herramienta local (se aplica al SDK de .NET Core 3.0 y versiones posteriores).

  Los archivos binarios de herramientas se instalan en un directorio predeterminado. Puede invocar la herramienta desde el directorio de instalación o cualquiera de sus subdirectorios. Los distintos directorios pueden usar versiones diferentes de la misma herramienta.

  La CLI de .NET usa archivos de manifiesto para realizar un seguimiento de las herramientas instaladas como locales en un directorio. Cuando el archivo de manifiesto se guarda en el directorio raíz de un repositorio de código fuente, un colaborador puede clonar el repositorio e invocar un único comando de la CLI de .NET para instalar todas las herramientas enumeradas en los archivos de manifiesto.

Buscar una herramienta

Estas son algunas maneras de encontrar herramientas:

• Use el comando dotnet tool search para buscar una herramienta publicada en NuGet.org.
• Use el filtro de tipo de paquete ".NET tool" para buscar el sitio web de NuGet . Para más información, vea Búsqueda y selección de paquetes.
• Consulte el código fuente de las herramientas que creó el equipo de ASP.NET Core en el directorio Herramientas del repositorio de GitHub dotnet/aspnetcore.
• Obtenga información sobre las herramientas de diagnóstico en herramientas de diagnóstico de .NET.

Comprobación del autor y las estadísticas

Las herramientas de .NET pueden ser eficaces porque se ejecutan en plena confianza y las herramientas globales se agregan a la variable de entorno PATH. No descargue herramientas de personas en las que no confíe.

Si la herramienta se hospeda en NuGet, puede comprobar el autor y las estadísticas buscando la herramienta.

Instalación de una herramienta global

Para instalar una herramienta como herramienta global, use la -g opción o --global de dotnet tool install, como se muestra en el ejemplo siguiente:

dotnet tool install -g dotnetsay

La salida muestra el comando usado para invocar la herramienta y la versión instalada, similar al ejemplo siguiente:

You can invoke the tool using the following command: dotnetsay
Tool 'dotnetsay' (version '2.1.4') was successfully installed.

La ubicación predeterminada de los archivos binarios de una herramienta depende del sistema operativo:

Esta ubicación se agrega a la ruta del usuario cuando se ejecuta el SDK por primera vez. Por lo tanto, las herramientas globales se pueden invocar desde cualquier directorio sin especificar la ubicación de la herramienta.

El acceso a la herramienta es específico del usuario, no global de la máquina. Una herramienta global solo está disponible para el usuario que instaló la herramienta.

Instalación de una herramienta global en una ubicación personalizada

Para instalar una herramienta como herramienta global en una ubicación personalizada, use la --tool-path opción de instalación de la herramienta dotnet, como se muestra en los ejemplos siguientes:

En Windows:

dotnet tool install dotnetsay --tool-path c:\dotnet-tools

En Linux o macOS:

dotnet tool install dotnetsay --tool-path ~/bin

El SDK de .NET no agrega esta ubicación automáticamente a la variable de entorno PATH. Para invocar una herramienta de ruta de acceso a la herramienta, debe asegurarse de que el comando está disponible mediante uno de los métodos siguientes:

• Agregue el directorio de instalación a la variable de entorno PATH.
• Especifique la ruta de acceso completa a la herramienta al invocarla.
• Invoque la herramienta desde el directorio de instalación.

Instalación de una herramienta local

Se aplica al SDK de .NET Core 3.0 y versiones posteriores.

Si desea instalar una herramienta solo para el acceso local (para el directorio actual y subdirectorios), debe agregar la herramienta a un archivo de manifiesto de herramienta. Para crear un archivo de manifiesto de herramienta, ejecute el dotnet new tool-manifest comando :

dotnet new tool-manifest

Este comando crea un archivo de manifiesto denominado dotnet-tools.json en el directorio .config . Para agregar una herramienta local al archivo de manifiesto, use el comando dotnet tool install y omita las --global opciones y --tool-path , como se muestra en el ejemplo siguiente:

dotnet tool install dotnetsay

La salida del comando muestra en qué archivo de manifiesto está presente la herramienta recién instalada, similar al ejemplo siguiente:

You can invoke the tool from this directory using the following command:
dotnet tool run dotnetsay
Tool 'dotnetsay' (version '2.1.4') was successfully installed.
Entry is added to the manifest file /home/name/botsay/.config/dotnet-tools.json.

En el ejemplo siguiente se muestra un archivo de manifiesto con dos herramientas locales instaladas:

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "botsay": {
      "version": "1.0.0",
      "commands": [
        "botsay"
      ]
    },
    "dotnetsay": {
      "version": "2.1.3",
      "commands": [
        "dotnetsay"
      ]
    }
  }
}

Normalmente, se agrega una herramienta local al directorio raíz del repositorio. Después de proteger el archivo de manifiesto en el repositorio, los desarrolladores que echan un vistazo al código del repositorio obtienen el archivo de manifiesto más reciente. Para instalar todas las herramientas enumeradas en el archivo de manifiesto, ejecutan el dotnet tool restore comando :

dotnet tool restore

La salida indica las herramientas restauradas:

Tool 'botsay' (version '1.0.0') was restored. Available commands: botsay
Tool 'dotnetsay' (version '2.1.3') was restored. Available commands: dotnetsay
Restore was successful.

Instalación de una versión específica de la herramienta

Para instalar una versión preliminar o una versión específica de una herramienta, especifique el número de versión mediante la --version opción , como se muestra en el ejemplo siguiente:

dotnet tool install dotnetsay --version 2.1.3

Para instalar una versión preliminar de la herramienta sin especificar el número de versión exacto, use la --version opción y proporcione un carácter comodín, como se muestra en el ejemplo siguiente:

dotnet tool install --global dotnetsay --version "*-rc*"

Uso de una herramienta

El comando que se usa para invocar una herramienta puede ser diferente del nombre del paquete que instale. Para mostrar todas las herramientas instaladas actualmente en el equipo para el usuario actual, use el comando dotnet tool list :

dotnet tool list

La salida muestra la versión y el comando de cada herramienta, similar al ejemplo siguiente:

Package Id      Version      Commands       Manifest
-------------------------------------------------------------------------------------------
botsay          1.0.0        botsay         /home/name/repository/.config/dotnet-tools.json
dotnetsay       2.1.3        dotnetsay      /home/name/repository/.config/dotnet-tools.json

Como se muestra en el ejemplo anterior, la lista muestra herramientas locales. Para ver las herramientas globales, use la --global opción . Para ver las herramientas de ruta de acceso de herramientas, use la --tool-path opción .

Para enumerar una herramienta específica, use el comando dotnet tool list <PACKAGE_ID> :

dotnet tool list dotnetsay

La salida solo mostrará esa herramienta si está instalada, similar al ejemplo siguiente:

Package Id      Version      Commands       Manifest
-------------------------------------------------------------------------------------------
dotnetsay       2.1.3        dotnetsay      /home/name/repository/.config/dotnet-tools.json

Invocación de una herramienta global

Para las herramientas globales, use el comando tool por sí mismo. Por ejemplo, si el comando es dotnetsay o dotnet-doc, es lo que se usa para invocar la herramienta global:

dotnetsay
dotnet-doc

Si el comando comienza con el prefijo , una manera alternativa de invocar la herramienta es usar el dotnet- comando y omitir el prefijo dotnetdel comando de la herramienta. Por ejemplo, si el comando es dotnet-doc, el siguiente comando invoca la herramienta:

dotnet doc

Sin embargo, en el siguiente escenario no puede usar el dotnet comando para invocar una herramienta global:

• Una herramienta global y una herramienta local tienen el mismo comando prefijo por dotnet-.
• Quiere invocar la herramienta global desde un directorio que esté en el ámbito de la herramienta local.

En este escenario, dotnet doc e dotnet dotnet-doc invoque la herramienta local. Para invocar la herramienta global, use el comando por sí mismo:

dotnet-doc

Invocar una herramienta de ruta de acceso de herramientas

Para invocar una herramienta global instalada mediante la tool-path opción , asegúrese de que el comando está disponible como se explicó anteriormente en este artículo.

Invocar una herramienta local

Para invocar una herramienta local, debe usar el dotnet comando desde el directorio de instalación. Puede usar el formato largo (dotnet tool run <COMMAND_NAME>) o el formato corto (dotnet <COMMAND_NAME>), como se muestra en los ejemplos siguientes:

dotnet tool run dotnetsay
dotnet dotnetsay

Si el comando tiene el prefijo dotnet-, puede incluir o omitir el prefijo al invocar la herramienta. Por ejemplo, si el comando es dotnet-doc, cualquiera de los ejemplos siguientes invoca la herramienta local:

dotnet tool run dotnet-doc
dotnet dotnet-doc
dotnet doc

Actualización de una herramienta

La actualización de una herramienta implica desinstalarla y reinstalarla con la versión estable más reciente. Para actualizar una herramienta, use el comando dotnet tool update con la misma opción que usó para instalar la herramienta:

dotnet tool update --global <packagename>
dotnet tool update --tool-path <packagename>
dotnet tool update <packagename>

Para una herramienta local, el SDK busca en el directorio actual y directorios primarios para buscar el primer archivo de manifiesto que contiene el identificador del paquete. Si no hay ningún identificador de paquete de este tipo en ningún archivo de manifiesto, el SDK agrega una nueva entrada al archivo de manifiesto más cercano.

Desinstalar una herramienta

Desinstale una herramienta mediante el comando dotnet tool uninstall con la misma opción que usó para instalar la herramienta:

dotnet tool uninstall --global <packagename>
dotnet tool uninstall --tool-path <packagename>
dotnet tool uninstall <packagename>

Para una herramienta local, el SDK busca en el directorio actual y directorios primarios para buscar el primer archivo de manifiesto que contiene el identificador del paquete.

Obtención de ayuda y solución de problemas

Si una herramienta no se puede instalar o ejecutar, consulte Solución de problemas de uso de herramientas de .NET. Puede obtener una lista de los comandos y parámetros disponibles dotnet tool mediante el --help parámetro :

dotnet tool --help

Para obtener instrucciones de uso de herramientas, escriba uno de los siguientes comandos o vea el sitio web de la herramienta:

<command> --help
dotnet <command> --help

Consulte también

• Tutorial: Creación de una herramienta .NET mediante la CLI de .NET
• Tutorial: Instalación y uso de una herramienta global de .NET mediante la CLI de .NET
• Tutorial: Instalación y uso de una herramienta local de .NET mediante la CLI de .NET
• Creación de herramientas de .NET específicas de RID y AOT