Usar a CLI do LibMan com o ASP.NET Core

Artigo
11/06/2024

O Gerenciador de Bibliotecas (LibMan) é uma ferramenta leve de aquisição de bibliotecas do lado do cliente. O LibMan baixa bibliotecas e estruturas populares do sistema de arquivos ou de uma CDN (rede de distribuição de conteúdo). As CDNs compatíveis incluem CDNJS, jsDelivr e unpkg. Os arquivos de biblioteca selecionados são buscados e colocados no local adequado dentro do projeto do ASP.NET Core.

Pré-requisitos

SDK mais recente do .NET

Instalação

O seguinte comando instala o LibMan:

dotnet tool install -g Microsoft.Web.LibraryManager.Cli

Observação

Por padrão, a arquitetura dos binários do .NET a serem instalados representa a arquitetura do SO sendo executado no momento. Para especificar uma arquitetura de SO diferente, consulte instalação da ferramenta dotnet, opção --arch. Para obter mais informações, confira o problema dotnet/AspNetCore.Docs #29262 do GitHub.

Uma ferramenta global do .NET Core é instalada pelo pacote do NuGet Microsoft.Web.LibraryManager.Cli.

Uso

libman

Para visualizar a versão instalada do LibMan:

libman --version

Para exibir os comandos disponíveis da CLI:

libman --help

O comando anterior exibe uma saída semelhante à seguinte:

 1.0.163+g45474d37ed

Usage: libman [options] [command]

Options:
  --help|-h  Show help information
  --version  Show version information

Commands:
  cache      List or clean libman cache contents
  clean      Deletes all library files defined in libman.json from the project
  init       Create a new libman.json
  install    Add a library definition to the libman.json file, and download the 
             library to the specified location
  restore    Downloads all files from provider and saves them to specified 
             destination
  uninstall  Deletes all files for the specified library from their specified 
             destination, then removes the specified library definition from 
             libman.json
  update     Updates the specified library

Use "libman [command] --help" for more information about a command.

As seções a seguir descrevem os comandos da CLI disponíveis.

Inicializar o LibMan no projeto

O comando libman init criará um arquivo libman.json caso ainda não exista. O arquivo é criado com o conteúdo do modelo de item padrão.

Sinopse

libman init [-d|--default-destination] [-p|--default-provider] [--verbosity]
libman init [-h|--help]

Opções

As opções a seguir estão disponíveis para o comando libman init:

-d|--default-destination <PATH>

Um caminho relativo à pasta atual. Os arquivos de biblioteca serão instalados nesse local se nenhuma propriedade destination for definida para uma biblioteca em libman.json. O valor <PATH> é gravado na propriedade defaultDestination de libman.json.
-p|--default-provider <PROVIDER>

O provedor a ser usado se nenhum provedor for definido para uma determinada biblioteca. O valor <PROVIDER> é gravado na propriedade defaultProvider de libman.json. Substitua <PROVIDER> por um dos seguintes valores:
- cdnjs
- filesystem
- jsdelivr
- unpkg

-h|--help

Mostra informações da Ajuda.
--verbosity <LEVEL>

Defina o detalhamento da saída. Substitua <LEVEL> por um dos seguintes valores:
- quiet
- normal
- detailed

Exemplos

Para criar um arquivo libman.json em um projeto ASP.NET Core:

Navegue até a raiz do projeto.
Execute o comando a seguir:
```
libman init
```
Digite o nome do provedor padrão ou pressione Enter para usar o provedor de CDNJS padrão. Os valores válidos incluem:
- cdnjs
- filesystem
- jsdelivr
- unpkg

Um arquivo libman.json é adicionado à raiz do projeto com o seguinte conteúdo:

{
  "version": "1.0",
  "defaultProvider": "cdnjs",
  "libraries": []
}

Adicionar arquivos de biblioteca

O comando libman install baixa e instala arquivos de biblioteca no projeto. Um arquivo libman.json será adicionado caso um ainda não exista. O arquivo libman.json é modificado para armazenar detalhes de configuração dos arquivos de biblioteca.

Sinopse

libman install <LIBRARY> [-d|--destination] [--files] [-p|--provider] [--verbosity]
libman install [-h|--help]

Argumentos

LIBRARY

O nome da biblioteca a ser instalada. Esse nome pode incluir a notação do número de versão (por exemplo, @1.2.0).

Opções

As opções a seguir estão disponíveis para o comando libman install:

-d|--destination <PATH>

O local de instalação da biblioteca. Se não for especificado, será usado o local padrão. Se nenhuma propriedade defaultDestination for especificada em libman.json, essa opção será necessária.

Observação: há limitações para o caminho de destino. Por exemplo, quando a origem do pacote tem uma estrutura de projeto completa e não apenas a pasta de distribuição, não é possível especificar a movimentação de uma pasta. Para obter mais informações, confira Problema nº 407 e Problema nº 702
--files <FILE>

Especifique o nome do arquivo a ser instalado a partir da biblioteca. Caso não seja especificado, todos os arquivos da biblioteca serão instalados. Forneça uma opção --files por arquivo a ser instalado. Também há suporte para caminhos relativos. Por exemplo: --files dist/browser/signalr.js.
-p|--provider <PROVIDER>

O nome do provedor a ser usado para a aquisição da biblioteca. Substitua <PROVIDER> por um dos seguintes valores:
- cdnjs
- filesystem
- jsdelivr
- unpkg
Caso não seja especificado, será usada a propriedade defaultProvider em libman.json. Se nenhuma propriedade defaultProvider for especificada em libman.json, essa opção será necessária.

-h|--help

Mostra informações da Ajuda.
--verbosity <LEVEL>

Defina o detalhamento da saída. Substitua <LEVEL> por um dos seguintes valores:
- quiet
- normal
- detailed

Exemplos

Considere o seguinte arquivo libman.json:

{
  "version": "1.0",
  "defaultProvider": "cdnjs",
  "libraries": []
}

Para instalar o arquivo jquery.min.js do jQuery versão 3.2.1 na pasta wwwroot/scripts/jquery usando o provedor de CDNJS:

libman install jquery@3.2.1 --provider cdnjs --destination wwwroot/scripts/jquery --files jquery.min.js

O arquivo libman.json é semelhante ao seguinte:

{
  "version": "1.0",
  "defaultProvider": "cdnjs",
  "libraries": [
    {
      "library": "jquery@3.2.1",
      "destination": "wwwroot/scripts/jquery",
      "files": [
        "jquery.min.js"
      ]
    }
  ]
}

Para instalar os arquivos calendar.js e calendar.css a partir de C:\temp\contosoCalendar\ usando o provedor do sistema de arquivos:

libman install C:\temp\contosoCalendar\ --provider filesystem --files calendar.js --files calendar.css

O prompt a seguir é exibido por dois motivos:

O arquivo libman.json não contém uma propriedade defaultDestination.
O comando libman install não contém a opção -d|--destination.

Comando libman install - destino

Depois de aceitar o destino padrão, o arquivo libman.json é semelhante ao seguinte:

{
  "version": "1.0",
  "defaultProvider": "cdnjs",
  "libraries": [
    {
      "library": "jquery@3.2.1",
      "destination": "wwwroot/scripts/jquery",
      "files": [
        "jquery.min.js"
      ]
    },
    {
      "library": "C:\\temp\\contosoCalendar\\",
      "provider": "filesystem",
      "destination": "wwwroot/lib/contosoCalendar",
      "files": [
        "calendar.js",
        "calendar.css"
      ]
    }
  ]
}

Restaurar arquivos de biblioteca

O comando libman restore instala arquivos de biblioteca definidos em libman.json. As seguintes regras se aplicam:

Se nenhum arquivo libman.json existir na raiz do projeto, será retornado um erro.
Se uma biblioteca especificar um provedor, a propriedade defaultProvider em libman.json será ignorada.
Se uma biblioteca especificar um destino, a propriedade defaultDestination em libman.json será ignorada.

Sinopse

libman restore [--verbosity]
libman restore [-h|--help]

Opções

As opções a seguir estão disponíveis para o comando libman restore:

-h|--help

Mostra informações da Ajuda.
--verbosity <LEVEL>

Defina o detalhamento da saída. Substitua <LEVEL> por um dos seguintes valores:
- quiet
- normal
- detailed

Exemplos

Para restaurar os arquivos de biblioteca definidos em libman.json:

libman restore

Excluir arquivos de biblioteca

O comando libman clean exclui arquivos de biblioteca restaurados anteriormente por meio do LibMan. As pastas que ficarem vazias depois dessa operação serão excluídas. Não são removidas as configurações associadas dos arquivos de biblioteca na propriedade libraries de libman.json.

Sinopse

libman clean [--verbosity]
libman clean [-h|--help]

Opções

As opções a seguir estão disponíveis para o comando libman clean:

-h|--help

Mostra informações da Ajuda.
--verbosity <LEVEL>

Defina o detalhamento da saída. Substitua <LEVEL> por um dos seguintes valores:
- quiet
- normal
- detailed

Exemplos

Para excluir os arquivos de biblioteca instalados por meio do LibMan:

libman clean

Desinstalar arquivos de biblioteca

O comando libman uninstall:

Exclui todos os arquivos associados à biblioteca especificada do destino em libman.json.
Remove a configuração de biblioteca associada de libman.json.

O erro ocorre quando:

Não há nenhum arquivo libman.json na raiz do projeto.
A biblioteca especificada não existe.

Se houver mais de uma biblioteca com o mesmo nome instalada, será solicitado que você escolha uma delas.

Sinopse

libman uninstall <LIBRARY> [--verbosity]
libman uninstall [-h|--help]

Argumentos

LIBRARY

O nome da biblioteca a ser desinstalada. Esse nome pode incluir a notação do número de versão (por exemplo, @1.2.0).

Opções

As opções a seguir estão disponíveis para o comando libman uninstall:

-h|--help

Mostra informações da Ajuda.
--verbosity <LEVEL>

Defina o detalhamento da saída. Substitua <LEVEL> por um dos seguintes valores:
- quiet
- normal
- detailed

Exemplos

Considere o seguinte arquivo libman.json:

{
  "version": "1.0",
  "defaultProvider": "cdnjs",
  "libraries": [
    {
      "library": "jquery@3.3.1",
      "files": [
        "jquery.min.js",
        "jquery.js",
        "jquery.min.map"
      ],
      "destination": "wwwroot/lib/jquery/"
    },
    {
      "provider": "unpkg",
      "library": "bootstrap@4.1.3",
      "destination": "wwwroot/lib/bootstrap/"
    },
    {
      "provider": "filesystem",
      "library": "C:\\temp\\lodash\\",
      "files": [
        "lodash.js",
        "lodash.min.js"
      ],
      "destination": "wwwroot/lib/lodash/"
    }
  ]
}

Para desinstalar o jQuery, um dos seguintes comandos terá êxito:
```
libman uninstall jquery
```
```
libman uninstall jquery@3.3.1
```
Para desinstalar os arquivos Lodash instalados por meio do provedor filesystem:
```
libman uninstall C:\temp\lodash\
```

Atualizar a versão da biblioteca

O comando libman update atualiza uma biblioteca instalada por meio do LibMan para a versão especificada.

O erro ocorre quando:

Não há nenhum arquivo libman.json na raiz do projeto.
A biblioteca especificada não existe.

Se houver mais de uma biblioteca com o mesmo nome instalada, será solicitado que você escolha uma delas.

Sinopse

libman update <LIBRARY> [-pre] [--to] [--verbosity]
libman update [-h|--help]

Argumentos

LIBRARY

O nome da biblioteca a ser atualizada.

Opções

As opções a seguir estão disponíveis para o comando libman update:

-pre

Obtenha a versão de pré-lançamento mais recente da biblioteca.
--to <VERSION>

Obtenha uma versão específica da biblioteca.

-h|--help

Mostra informações da Ajuda.
--verbosity <LEVEL>

Defina o detalhamento da saída. Substitua <LEVEL> por um dos seguintes valores:
- quiet
- normal
- detailed

Exemplos

Para atualizar o jQuery para a versão mais recente:
```
libman update jquery
```
Para atualizar o jQuery para a versão 3.3.1:
```
libman update jquery --to 3.3.1
```
Para atualizar o jQuery para a versão de pré-lançamento mais recente:
```
libman update jquery -pre
```

Gerenciar o cache da biblioteca

O comando libman cache gerencia o cache da biblioteca do LibMan. O provedor filesystem não usa o cache da biblioteca.

Sinopse

libman cache clean [<PROVIDER>] [--verbosity]
libman cache list [--files] [--libraries] [--verbosity]
libman cache [-h|--help]

Argumentos

PROVIDER

É usado apenas com o comando clean. Define o cache do provedor como limpo. Os valores válidos incluem:

cdnjs
filesystem
jsdelivr
unpkg

Opções

As opções a seguir estão disponíveis para o comando libman cache:

--files

Lista os nomes dos arquivos armazenados em cache.
--libraries

Lista os nomes das bibliotecas armazenadas em cache.

-h|--help

Mostra informações da Ajuda.
--verbosity <LEVEL>

Defina o detalhamento da saída. Substitua <LEVEL> por um dos seguintes valores:
- quiet
- normal
- detailed

Exemplos

Para exibir os nomes das bibliotecas armazenadas em cache por provedor, use um dos seguintes comandos:

libman cache list

libman cache list --libraries

Uma saída semelhante à apresentada a seguir será exibida:

Cache contents:
---------------
unpkg:
    knockout
    react
    vue
cdnjs:
    font-awesome
    jquery
    knockout
    lodash.js
    react

Para exibir os nomes de arquivos de biblioteca armazenados em cache por provedor:

libman cache list --files

Uma saída semelhante à apresentada a seguir será exibida:

Cache contents:
---------------
unpkg:
    knockout:
        <list omitted for brevity>
    react:
        <list omitted for brevity>
    vue:
        <list omitted for brevity>
cdnjs:
    font-awesome
        metadata.json
    jquery
        metadata.json
        3.2.1\core.js
        3.2.1\jquery.js
        3.2.1\jquery.min.js
        3.2.1\jquery.min.map
        3.2.1\jquery.slim.js
        3.2.1\jquery.slim.min.js
        3.2.1\jquery.slim.min.map
        3.3.1\core.js
        3.3.1\jquery.js
        3.3.1\jquery.min.js
        3.3.1\jquery.min.map
        3.3.1\jquery.slim.js
        3.3.1\jquery.slim.min.js
        3.3.1\jquery.slim.min.map
    knockout
        metadata.json
        3.4.2\knockout-debug.js
        3.4.2\knockout-min.js
    lodash.js
        metadata.json
        4.17.10\lodash.js
        4.17.10\lodash.min.js
    react
        metadata.json

Observe que a saída anterior mostra que as versões jQuery 3.2.1 e 3.3.1 são armazenadas em cache no provedor de CDNJS.

Para esvaziar o cache de biblioteca do provedor de CDNJS:
```
libman cache clean cdnjs
```
Depois de esvaziar o cache do provedor de CDNJS, o comando libman cache list exibirá o seguinte:
```
Cache contents:
---------------
unpkg:
    knockout
    react
    vue
cdnjs:
    (empty)
```
Para esvaziar o cache de todos os provedores com suporte:
```
libman cache clean
```
Depois de esvaziar todos os caches do provedor, o comando libman cache list exibirá o seguinte:
```
Cache contents:
---------------
unpkg:
    (empty)
cdnjs:
    (empty)
```

Compartilhar via

Usar a CLI do LibMan com o ASP.NET Core

Pré-requisitos

Instalação

Uso

Inicializar o LibMan no projeto

Sinopse

Opções

Exemplos

Adicionar arquivos de biblioteca

Sinopse

Argumentos

Opções

Exemplos

Restaurar arquivos de biblioteca

Sinopse

Opções

Exemplos

Excluir arquivos de biblioteca

Sinopse

Opções

Exemplos

Desinstalar arquivos de biblioteca

Sinopse

Argumentos

Opções

Exemplos

Atualizar a versão da biblioteca

Sinopse

Argumentos

Opções

Exemplos

Gerenciar o cache da biblioteca

Sinopse

Argumentos

Opções

Exemplos

Recursos adicionais

Recursos adicionais