Tutorial: Instalación y uso de una herramienta local de .NET mediante la CLI de .NET

Artículo
05/10/2023

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

En este tutorial se enseña cómo instalar y usar una herramienta local. Usará una herramienta que ha creado en el primer tutorial de esta serie.

Requisitos previos

Complete el primer tutorial de esta serie.
Instale el entorno de ejecución de .NET Core 2.1.

En este tutorial, instalará y usará una herramienta que tiene como destino .NET Core 2.1, por lo que debe tener ese entorno de ejecución instalado en el equipo. Para instalar la versión 2.1 del entorno de ejecución, vaya a la página de descarga de .NET Core 2.1 y busque el vínculo de instalación del entorno de ejecución en la columna Ejecutar aplicaciones: entorno de ejecución.

Crear un archivo de manifiesto

Para instalar una herramienta solo para el acceso local (del directorio y los subdirectorios actuales), debe agregarse a un archivo de manifiesto.

Desde la carpeta microsoft.botsay, suba un nivel hasta la carpeta repository:

cd ..

Cree un archivo de manifiesto; para ello, ejecute el comando dotnet new:

dotnet new tool-manifest

En la salida se indica que el archivo se ha creado correctamente.

The template "Dotnet local tool manifest file" was created successfully.

El archivo .config/dotnet-tools.json aún no contiene ninguna herramienta:

{
  "version": 1,
  "isRoot": true,
  "tools": {}
}

Las herramientas enumeradas en un archivo de manifiesto están disponibles en el directorio y los subdirectorios actuales. El directorio actual es el que contiene el directorio .config con el archivo de manifiesto.

Si se usa un comando de la CLI que hace referencia a una herramienta local, el SDK busca un archivo de manifiesto en el directorio actual y los directorios principales. Si encuentra un archivo de manifiesto, pero el archivo no incluye la herramienta a la que se hace referencia, continúa con la búsqueda en los directorios principales. La búsqueda finaliza cuando encuentra la herramienta a la que se hace referencia o un archivo de manifiesto con isRoot establecido en true.

Instalación de botsay como una herramienta local

Instale la herramienta desde el paquete que ha creado en el primer tutorial:

dotnet tool install --add-source ./microsoft.botsay/nupkg microsoft.botsay

Este comando agrega la herramienta al archivo de manifiesto que ha creado en el paso anterior. En la salida del comando se muestra el archivo de manifiesto en el que se encuentra la herramienta que acaba de instalar:

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

Ahora, el archivo .config/dotnet-tools.json tiene una herramienta:

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "microsoft.botsay": {
      "version": "1.0.0",
      "commands": [
        "botsay"
      ]
    }
  }
}

Usar la herramienta

Para invocar la herramienta, ejecute el comando dotnet tool run desde la carpeta repository:

dotnet tool run botsay hello from the bot

Restauración de una herramienta local instalada por otros usuarios

Normalmente, una herramienta local se instala en el directorio raíz del repositorio. Después de insertar el archivo de manifiesto en el repositorio, otros desarrolladores pueden obtener el archivo de manifiesto más reciente. Para instalar todas las herramientas enumeradas en el archivo de manifiesto, pueden ejecutar un único comando dotnet tool restore.

Abra el archivo .config/dotnet-tools.json y reemplace el contenido con el siguiente código JSON:

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

Guarde los cambios.

Cambiar esto tiene el mismo resultado que obtener la versión más reciente del repositorio después de que otra persona haya instalado el paquete dotnetsay en el directorio del proyecto.

Ejecute el comando dotnet tool restore.

dotnet tool restore

El comando genera una salida como la del siguiente ejemplo:

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

Compruebe que las herramientas están disponibles:

dotnet tool list

La salida es una lista de paquetes y comandos, similar al ejemplo siguiente:

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

Pruebe las herramientas:

dotnet tool run dotnetsay hello from dotnetsay
dotnet tool run botsay hello from botsay

Actualización de una herramienta local

La versión instalada de la herramienta local dotnetsay es 2.1.3. Use el comando dotnet tool update para actualizar la herramienta a la versión más reciente.

dotnet tool update dotnetsay

En la salida se indica el nuevo número de versión:

Tool 'dotnetsay' was successfully updated from version '2.1.3' to version '2.1.7'
(manifest file /home/name/repository/.config/dotnet-tools.json).

El comando update busca el primer archivo de manifiesto que contiene el identificador del paquete y lo actualiza. Si no hay ningún identificador del paquete en ningún archivo de manifiesto que esté en el ámbito de la búsqueda, el SDK agrega una nueva entrada al archivo de manifiesto más cercano. El ámbito de búsqueda va hacia los directorios principales hasta que se encuentra un archivo de manifiesto con isRoot = true.

Eliminación de las herramientas locales

Ejecute el comando dotnet tool uninstall para quitar las herramientas instaladas:

dotnet tool uninstall microsoft.botsay

dotnet tool uninstall dotnetsay

Solucionar problemas

Si recibe un mensaje de error al seguir el tutorial, vea Solución de problemas de uso de herramientas de .NET Core.

Vea también

Para obtener más información, vea Herramientas de .NET.