dotnet add package

  • Artigo

Este artigo se aplica a: ✔️ SDK do .NET Core 3.1 e versões posteriores

Nome

dotnet add package - Adiciona ou atualiza uma referência de pacote em um arquivo de projeto.

Sinopse

dotnet add [<PROJECT>] package <PACKAGE_NAME>
    [-f|--framework <FRAMEWORK>] [--interactive]
    [-n|--no-restore] [--package-directory <PACKAGE_DIRECTORY>]
    [--prerelease] [-s|--source <SOURCE>] [-v|--version <VERSION>]

dotnet add package -h|--help

Descrição

O comando dotnet add package fornece uma opção conveniente para adicionar ou atualizar uma referência de pacote a um arquivo de projeto. Ao executar o comando, há uma verificação de compatibilidade para garantir que o pacote seja compatível com as estruturas do projeto. Se a verificação for aprovada e o pacote não for referenciado no arquivo de projeto, um elemento <PackageReference> será adicionado ao arquivo de projeto. Se a verificação for aprovada e o pacote não for referenciado no arquivo de projeto, um elemento <PackageReference> será adicionado ao arquivo de projeto. Depois que o arquivo de projeto é atualizado, o dotnet restore é executado.

Por exemplo, adicionar Microsoft.EntityFrameworkCore a ToDo.csproj produz uma saída semelhante ao exemplo a seguir:

  Determining projects to restore...
  Writing C:\Users\username\AppData\Local\Temp\tmp24A8.tmp
info : Adding PackageReference for package 'Microsoft.EntityFrameworkCore' into project 'C:\ToDo\ToDo.csproj'.
info :   CACHE https://api.nuget.org/v3/registration5-gz-semver2/microsoft.entityframeworkcore/index.json
info :   GET https://pkgs.dev.azure.com/dnceng/9ee6d478-d288-47f7-aacc-f6e6d082ae6d/_packaging/516521bf-6417-457e-9a9c-0a4bdfde03e7/nuget/v3/registrations2-semver2/microsoft.entityframeworkcore/index.json
info :   CACHE https://api.nuget.org/v3/registration5-gz-semver2/microsoft.entityframeworkcore/page/0.0.1-alpha/3.1.3.json
info :   CACHE https://api.nuget.org/v3/registration5-gz-semver2/microsoft.entityframeworkcore/page/3.1.4/7.0.0-preview.2.22153.1.json
info :   CACHE https://api.nuget.org/v3/registration5-gz-semver2/microsoft.entityframeworkcore/page/7.0.0-preview.3.22175.1/7.0.0-preview.3.22175.1.json
info :   NotFound https://pkgs.dev.azure.com/dnceng/9ee6d478-d288-47f7-aacc-f6e6d082ae6d/_packaging/516521bf-6417-457e-9a9c-0a4bdfde03e7/nuget/v3/registrations2-semver2/microsoft.entityframeworkcore/index.json 257ms
info : Restoring packages for C:\ToDo\ToDo.csproj...
info : Package 'Microsoft.EntityFrameworkCore' is compatible with all the specified frameworks in project 'C:\ToDo\ToDo.csproj'.
info : PackageReference for package 'Microsoft.EntityFrameworkCore' version '6.0.4' added to file 'C:\ToDo\ToDo.csproj'.
info : Writing assets file to disk. Path: C:\ToDo\obj\project.assets.json
log  : Restored C:\ToDo\ToDo.csproj (in 171 ms).

O arquivo ToDo.csproj agora contém um elemento <PackageReference> para o pacote referenciado.

<PackageReference Include="Microsoft.EntityFrameworkCore" Version="6.0.4" />

Se o projeto estiver integrado ao Gerenciamento Central de Pacotes (CPM), o <PackageVersion> elemento no Directory.Packages.props file será adicionado/atualizado e o <PackageReference> elemento será adicionado ao arquivo de projeto.

Atualmente, há suporte para os seguintes cenários. Esses exemplos pressupõem que a versão mais recente do Microsoft.EntityFrameworkCore seja 6.0.4. Cenários adicionais relacionados ao CPM estão documentados nesta especificação de design.

Cenário 1: <PackageReference> não existe no arquivo de projeto, <PackageVersion> o Directory.Packages.props fileelemento não existe no , e o argumento version não é passado da linha de comando.

Comando CLI que é executado: dotnet add ToDo.csproj package Microsoft.EntityFrameworkCore

O <PackageVersion> elemento é adicionado ao Directory.Packages.props file.

<PackageVersion Include="Microsoft.EntityFrameworkCore" Version="6.0.4" />

O <PackageReference> elemento é adicionado ao arquivo de projeto.

<PackageReference Include="Microsoft.EntityFrameworkCore" />

Cenário 2: <PackageReference> não existe no arquivo de projeto, <PackageVersion> o Directory.Packages.props fileelemento não existe no , e o argumento version é passado da linha de comando.

Comando CLI que é executado: dotnet add ToDo.csproj package Microsoft.EntityFrameworkCore --version 5.0.4

O <PackageVersion> elemento é adicionado ao Directory.Packages.props file.

<PackageVersion Include="Microsoft.EntityFrameworkCore" Version="5.0.4" />

O <PackageReference> elemento é adicionado ao arquivo de projeto.

<PackageReference Include="Microsoft.EntityFrameworkCore" />

Cenário 3: <PackageReference> não existe no arquivo de projeto, <PackageVersion> o Directory.Packages.props fileelemento existe no , e o argumento version não é passado da linha de comando.

Comando CLI que é executado: dotnet add ToDo.csproj package Microsoft.EntityFrameworkCore

O <PackageVersion> elemento é adicionado ao Directory.Packages.props file.

<PackageVersion Include="Microsoft.EntityFrameworkCore" Version="6.0.4" />

O <PackageReference> elemento é adicionado ao arquivo de projeto.

<PackageReference Include="Microsoft.EntityFrameworkCore" />

Cenário 4: <PackageReference> não existe no arquivo de projeto, <PackageVersion> o Directory.Packages.props fileelemento existe no , e o argumento version é passado da linha de comando.

Comando CLI que é executado: dotnet add ToDo.csproj package Microsoft.EntityFrameworkCore --version 5.0.4

O <PackageVersion> elemento é adicionado ao Directory.Packages.props file.

<PackageVersion Include="Microsoft.EntityFrameworkCore" Version="5.0.4" />

O <PackageReference> elemento é adicionado ao arquivo de projeto.

<PackageReference Include="Microsoft.EntityFrameworkCore" />

Restauração implícita

Não é necessário executar dotnet restore, pois ele é executado implicitamente por todos os comandos que exigem uma restauração, como dotnet new, dotnet build, dotnet run, dotnet test, dotnet publish e dotnet pack. Para desabilitar a restauração implícita, use a opção --no-restore.

O comando dotnet restore ainda é útil em determinados cenários em que realizar uma restauração explícita faz sentido, como compilações de integração contínua no Azure DevOps Services ou em sistemas de compilação que precisam controlar explicitamente quando a restauração ocorrerá.

Para obter informações sobre como gerenciar feeds do NuGet, confira a documentação do dotnet restore.

Argumentos

  • PROJECT

    Especifica o arquivo do projeto. Se não for especificado, o comando pesquisará um no diretório atual.

  • PACKAGE_NAME

    A referência de pacote a ser adicionada.

Opções

  • -f|--framework <FRAMEWORK>

    Adiciona uma referência de pacote somente quando há uma estrutura específica como destino.

  • -?|-h|--help

    Imprime uma descrição de como usar o comando.

  • --interactive

    Permite que o comando pare e aguarde entrada ou ação do usuário. Por exemplo, para concluir a autenticação.

  • -n|--no-restore

    Adiciona uma referência de pacote sem executar a visualização de restauração e a verificação de compatibilidade.

  • --package-directory <PACKAGE_DIRECTORY>

    O diretório no qual restaurar os pacotes. O local de restauração de pacote padrão é %userprofile%\.nuget\packages no Windows e ~/.nuget/packages no macOS e Linux. Para obter mais informações, consulte Como gerenciar as pastas de pacotes globais, de cache e temporárias no NuGet.

  • --prerelease

    Permite a instalação de pacotes de pré-lançamento. Disponível desde o SDK do .NET Core 5

  • -s|--source <SOURCE>

    A URI da origem do pacote NuGet a ser usada durante a operação de restauração.

  • -v|--version <VERSION>

    Versão do pacote. Consulte Controle de versão do pacote NuGet.

Exemplos

  • Adicionar um pacote NuGet Microsoft.EntityFrameworkCore a um projeto:

    dotnet add package Microsoft.EntityFrameworkCore

  • Adicionar uma versão específica de um pacote a um projeto:

    dotnet add ToDo.csproj package Microsoft.Azure.DocumentDB.Core -v 1.0.0

  • Adicionar um pacote usando uma fonte específica do NuGet:

    dotnet add package Microsoft.AspNetCore.StaticFiles -s https://dotnet.myget.org/F/dotnet-core/api/v3/index.json

Confira também