Usar LibMan com ASP.NET Core no Visual Studio

  • Artigo

Por Scott Addie

O Visual Studio tem suporte integrado para o LibMan em projetos ASP.NET Core, incluindo:

  • Suporte para configurar e executar operações de restauração do LibMan na compilação.
  • Itens de menu para disparar operações de restauração e limpeza do LibMan.
  • Caixa de diálogo Pesquisar para localizar bibliotecas e adicionar os arquivos a um projeto.
  • Suporte de edição para libman.json—o arquivo de manifesto do LibMan.

Exibir ou baixar código de exemplo (como baixar)

Pré-requisitos

Adicionar arquivos de biblioteca

Os arquivos de biblioteca podem ser adicionados a um projeto ASP.NET Core de duas maneiras diferentes:

  1. Usando a caixa de diálogo Adicionar Biblioteca do Lado do Cliente
  2. Configurando manualmente as entradas de arquivo de manifesto do LibMan

Usando a caixa de diálogo Adicionar Biblioteca do Lado do Cliente

Siga estas etapas para instalar uma biblioteca do lado do cliente:

  • Em Gerenciador de Soluções, clique com o botão direito do mouse na pasta do projeto na qual os arquivos devem ser adicionados. Escolha Adicionar>Biblioteca do Lado do Cliente. É exibida a caixa de diálogo Adicionar Biblioteca do Lado do Cliente:

    Caixa de diálogo Adicionar Biblioteca do Lado do Cliente

  • Selecione o provedor de biblioteca na lista suspensa Provedor. O CDNJS é o provedor padrão.

  • Digite o nome da biblioteca a ser buscada na caixa de texto Biblioteca. O IntelliSense fornece uma lista de bibliotecas que começam com o texto fornecido.

  • Selecione a biblioteca a partir da lista do IntelliSense. Observe que o nome da biblioteca possui sufixo com o símbolo @ e a versão estável mais recente conhecida pelo provedor selecionado.

  • Decida quais arquivos incluir:

    • Selecione o botão de opção Incluir todos os arquivos de biblioteca para incluir todos os arquivos da biblioteca.
    • Selecione o botão de opção Escolher arquivos específicos para incluir um subconjunto dos arquivos da biblioteca. Quando o botão de opção é selecionado, a árvore do seletor de arquivos é habilitada. Marque as caixas à esquerda dos nomes de arquivo para fazer o download.

  • Especifique a pasta do projeto para armazenar os arquivos na caixa de texto Local de Destino. Como recomendação, armazene cada biblioteca em uma pasta separada.

    A pasta sugerida Local de Destino baseia-se no local do qual a caixa de diálogo foi iniciada:

    • Se iniciada a partir da raiz do projeto:
      • wwwroot/lib será usado se wwwroot existir.
      • lib será usado se wwwroot não existir.
    • Se iniciada a partir de uma pasta de projeto, o nome da pasta correspondente será usado.

    A sugestão de pasta possui sufixo com o nome da biblioteca. A tabela a seguir ilustra as sugestões de pasta ao instalar o jQuery em um projeto de Páginas do Razor.

    Local de inicialização Pasta sugerida
    raiz do projeto (se wwwroot existir) wwwroot/lib/jquery/
    raiz do projeto (se wwwroot não existir) lib/jquery/
    Pasta Páginas no projeto Pages/jquery/

  • Clique no botão Instalar para fazer o download dos arquivos, de acordo com a configuração em libman.json.

  • Revise o feed do Gerente de Biblioteca da janela Saída para obter detalhes da instalação. Por exemplo:

    Restore operation started...
Restoring libraries for project LibManSample
Restoring library jquery@3.3.1... (LibManSample)
wwwroot/lib/jquery/jquery.min.js written to destination (LibManSample)
wwwroot/lib/jquery/jquery.js written to destination (LibManSample)
wwwroot/lib/jquery/jquery.min.map written to destination (LibManSample)
Restore operation completed
1 libraries restored in 2.32 seconds

Configurando manualmente as entradas de arquivo de manifesto do LibMan

Todas as operações do LibMan no Visual Studio são baseadas no conteúdo do manifesto do LibMan da raiz do projeto (libman.json). Você pode editar manualmente libman.json para configurar arquivos de biblioteca para o projeto. O Visual Studio restaura todos os arquivos de biblioteca uma vez que libman.json é salvo.

Para abrir o libman.json para edição, existem as seguintes opções:

  • Clique duas vezes no arquivo libman.json no Gerenciador de Soluções.
  • Clique com o botão direito do mouse no projeto no Gerenciador de Soluções e selecione Gerenciar Bibliotecas do Lado do Cliente. †
  • Selecione Gerenciar Bibliotecas do Lado do Cliente no menu Projeto do Visual Studio. †

† Se o arquivo libman.json ainda não existir na raiz do projeto, ele será criado com o conteúdo do modelo de item padrão.

O Visual Studio oferece suporte avançado à edição JSON, como colorização, formatação, IntelliSense e validação de esquema. O esquema ON do manifesto do LibMan é encontrado em https://json.schemastore.org/libman.

Com o arquivo de manifesto a seguir, o LibMan recupera arquivos de acordo com a configuração definida na propriedade libraries. A seguir está uma explicação dos literais de objeto definidos dentro do libraries:

  • Um subconjunto do jQuery versão 3.3.1 é recuperado do provedor de CDNJS. O subconjunto é definido na propriedade files—jquery.min.js, jquery.js e jquery.min.map. Os arquivos são colocados na pasta do projeto wwwroot/lib/jquery.
  • A totalidade da inicialização versão 4.1.3 é recuperada e colocada em uma pasta wwwroot/lib/bootstrap. A propriedade provider do literal de objeto substitui o valor da propriedade defaultProvider. O LibMan recupera os arquivos de inicialização do provedor unpkg.
  • Um subconjunto de Lodash foi aprovado por um órgão de controle dentro da organização. Os arquivos lodash.js e lodash.min.js são recuperados do sistema de arquivos local em C:\temp\lodash\. Os arquivos são copiados para a pasta do projeto wwwroot/lib/lodash.
{
  "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/"
    }
  ]
}

Observação

O LibMan dá suporte apenas a uma versão de cada biblioteca de cada provedor. O arquivo libman.json falhará na validação do esquema se contiver duas bibliotecas com o mesmo nome de biblioteca para um determinado provedor.

Restaurar arquivos de biblioteca

Para restaurar arquivos de biblioteca de dentro do Visual Studio, deve haver um arquivo libman.json válido na raiz do projeto. Os arquivos restaurados são colocados no projeto no local especificado para cada biblioteca.

Os arquivos de biblioteca podem ser restaurados em um projeto ASP.NET Core de duas maneiras:

  1. Restaurando arquivos durante a compilação
  2. Restaurando manualmente os arquivos

Restaurando arquivos durante a compilação

O LibMan pode restaurar os arquivos de biblioteca definidos como parte do processo de compilação. Por padrão, o comportamento da restauração em compilação está desabilitado.

Para habilitar e testar o comportamento da restauração em compilação:

  • Clique com o botão direito do mouse em libman.json no Gerenciador de Soluções e selecione Habilitar Restaurar Bibliotecas do Lado do Cliente na Compilação no menu de contexto.

  • Clique no botão Sim quando solicitado a instalar um pacote NuGet. O pacote NuGet Microsoft.Web.LibraryManager.Build é adicionado ao projeto:

    <PackageReference Include="Microsoft.Web.LibraryManager.Build" Version="1.0.113" />

  • Compile o projeto para confirmar se ocorre a restauração do arquivo do LibMan. O pacote Microsoft.Web.LibraryManager.Build injeta um destino do MSBuild que executa o LibMan durante a operação de compilação do projeto.

  • Revise o feed de Compilação da janela Saída para um log de atividades do LibMan:

    1>------ Build started: Project: LibManSample, Configuration: Debug Any CPU ------
1>
1>Restore operation started...
1>Restoring library jquery@3.3.1...
1>Restoring library bootstrap@4.1.3...
1>
1>2 libraries restored in 10.66 seconds
1>LibManSample -> C:\LibManSample\bin\Debug\netcoreapp2.1\LibManSample.dll
========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

Quando o comportamento da restauração em compilação está habilitado, o menu de contexto libman.json exibe uma opção Desabilitar Restaurar Bibliotecas do Lado do Cliente na Compilação. Selecionar essa opção remove a referência de pacote Microsoft.Web.LibraryManager.Build do arquivo de projeto. Consequentemente, as bibliotecas do lado do cliente não são mais restauradas em cada compilação.

Independentemente da configuração da restauração em compilação, você pode restaurar manualmente a qualquer momento no menu de contexto libman.json. Para saber mais, consulte Restaurar manualmente os arquivos.

Restaurando manualmente os arquivos

Para restaurar manualmente os arquivos de biblioteca:

  • Para todos os projetos na solução:
    • Clique com o botão direito do mouse no nome da solução em Gerenciador de Soluções.
    • Selecione a opção Restaurar Bibliotecas do Lado do Cliente.
  • Para um projeto específico:
    • Clique com o botão direito do mouse no arquivo libman.json em Gerenciador de Soluções.
    • Selecione a opção Restaurar Bibliotecas do Lado do Cliente.

Enquanto a operação de restauração está em execução:

  • O ícone da Central de Status de Tarefas (TSC, na sigla em inglês) na barra de status do Visual Studio será animado e mostrará Restaurar operação iniciada. Clicar no ícone abre uma dica de ferramenta listando as tarefas em segundo plano conhecidas.

  • As mensagens serão enviadas para a barra de status e para o feed do Gerente de Bibliotecas da janela Saída. Por exemplo:

    Restore operation started...
Restoring libraries for project LibManSample
Restoring library jquery@3.3.1... (LibManSample)
wwwroot/lib/jquery/jquery.min.js written to destination (LibManSample)
wwwroot/lib/jquery/jquery.js written to destination (LibManSample)
wwwroot/lib/jquery/jquery.min.map written to destination (LibManSample)
Restore operation completed
1 libraries restored in 2.32 seconds

Excluir arquivos de biblioteca

Para executar a operação de limpeza, que exclui arquivos de biblioteca restaurados anteriormente no Visual Studio:

  • Clique com o botão direito do mouse no arquivo libman.json em Gerenciador de Soluções.
  • Selecione a opção Limpar Bibliotecas do Lado do Cliente.

Para evitar a remoção não intencional de arquivos que não são da biblioteca, a operação de limpeza não exclui diretórios inteiros. Ela remove apenas os arquivos que foram incluídos na restauração anterior.

Enquanto a operação de limpeza está em execução:

  • O ícone da TSC na barra de status do Visual Studio será animado e mostrará Operação iniciada nas bibliotecas do cliente. Clicar no ícone abre uma dica de ferramenta listando as tarefas em segundo plano conhecidas.
  • As mensagens são enviadas para a barra de status e para o feed do Gerente de Bibliotecas da janela Saída. Por exemplo:
Clean libraries operation started...
Clean libraries operation completed
2 libraries were successfully deleted in 1.91 secs

A operação de limpeza exclui apenas arquivos do projeto. Os arquivos de biblioteca permanecem no cache para recuperação mais rápida em operações de restauração futuras. Para gerenciar arquivos de biblioteca armazenados no cache do computador local, use a CLI do LibMan.

Desinstalar arquivos de biblioteca

Para desinstalar arquivos de biblioteca:

  • Abra o libman.json.

  • Posicione o cursor dentro do literal de objeto libraries correspondente.

  • Clique no ícone de lâmpada que aparece na margem esquerda e selecione Desinstalar <library_name>@<library_version>:

    Opção do menu de contexto Desinstalar biblioteca

Como alternativa, você pode editar e salvar manualmente o manifesto do LibMan (libman.json). A operação de restauração é executada quando o arquivo é salvo. Os arquivos de biblioteca que não estão mais definidos no libman.json são removidos do projeto.

Atualizar a versão da biblioteca

Para verificar se há uma versão atualizada da biblioteca:

  • Abra o libman.json.
  • Posicione o cursor dentro do literal de objeto libraries correspondente.
  • Clique no ícone de lâmpada que aparece na margem esquerda. Passe o mouse sobre Verificar se há atualizações.

O LibMan verifica se há uma versão da biblioteca mais recente do que a versão instalada. Os seguintes resultados podem ocorrer:

  • Uma mensagem Sem atualizações encontradas será exibida se a versão mais recente já estiver instalada.

  • A versão estável mais recente será exibida se ainda não estiver instalada.

    Opção do menu de contexto Verificar se há atualizações

  • Se uma pré-versão mais recente do que a versão instalada estiver disponível, a pré-versão será exibida.

Para fazer downgrade para uma versão mais antiga da biblioteca, edite manualmente o arquivo libman.json. Quando o arquivo é salvo, a operação de a operação de restauração do LibMan:

  • Remove arquivos redundantes da versão anterior.
  • Adiciona arquivos novos e atualizados da nova versão.

Recursos adicionais