Criar um pacote usando a CLI nuget.exe

Não importa o que o pacote faz ou qual código ele contém, você usa uma das ferramentas nuget.exe da CLI (interface de linha de comando) ou dotnet.exepara empacotar essa funcionalidade em um componente que pode ser compartilhado e usado por outros desenvolvedores. Para instalar as ferramentas da CLI do NuGet, consulte Instalar ferramentas de cliente do NuGet. Visual Studio não inclui automaticamente uma ferramenta da CLI.

• Para projetos não estilo SDK, normalmente .NET projetos do Framework, siga as etapas descritas neste artigo para criar um pacote. Para obter um início rápido que forneça instruções passo a passo para usar Visual Studio e a CLI do nuget.exe, consulte Quickstart: Criar e publicar um pacote usando Visual Studio (.NET Framework, Windows).

• Para projetos .NET Core e .NET Standard que usam o formato de estilo SDK e quaisquer outros projetos no estilo SDK, consulte Criar um pacote NuGet com a CLI do dotnet.

• Para projetos migrados de packages.config para PackageReference, use o msbuild -t:pack comando.

Tecnicamente, um pacote NuGet é um arquivo ZIP que foi renomeado para ter a extensão .nupkg e cujo conteúdo corresponde a determinadas convenções. Este artigo descreve o processo detalhado de criação de um pacote que atenda a essas convenções.

O empacotamento começa com o código compilado (assemblies), símbolos e outros arquivos que você deseja entregar como um pacote. Para obter uma visão geral do processo de empacotamento, consulte o fluxo de trabalho de criação de pacote. Esse processo é independente de compilar ou gerar os arquivos que entram no pacote. Mas você pode extrair informações em um arquivo de projeto para manter os assemblies e pacotes compilados em sincronia.

Decidir quais assemblies empacotar

A maioria dos pacotes de uso geral contém um ou mais assemblies que outros desenvolvedores podem usar em seus próprios projetos.

Em geral, é melhor ter um assembly por pacote NuGet, desde que cada um seja útil de forma independente. Por exemplo, considere os seguintes casos que envolvem um assembly chamado Utilities.dll que depende de um assembly chamado Parser.dll:

• Se Parser.dll for útil por conta própria, crie um pacote para Utilities.dll e outro para Parser.dll. Isso permite que os desenvolvedores usem Parser.dll independentemente de Utilities.dll.

• Se Parser.dll contiver o código usado apenas por Utilities.dll, tudo bem manter Parser.dll no mesmo pacote. Em geral, se a biblioteca for composta por vários assemblies que não são úteis independentemente, é adequado combiná-los em um único pacote.

• Se Utilities.dll também depender de Utilities.resources.dlle Utilities.resources.dll não for útil por conta própria, coloque ambos no mesmo pacote.

Recursos, como o assembly Utilities.resources.dll no exemplo anterior, são um caso especial. Quando um pacote é instalado em um projeto, o NuGet adiciona automaticamente referências de assembly às DLLs do pacote, excluindo aquelas nomeadas .resources.dll, porque são consideradas assemblies satélite de localização. Para obter mais informações sobre versões localizadas de uma biblioteca, consulte Criando pacotes NuGet localizados. Por esse motivo, evite usar .resources.dll para arquivos que contêm código de pacote essencial.

Se sua biblioteca contiver assemblies de interoperabilidade COM (Component Object Model), siga as diretrizes adicionais em Criar pacotes NuGet que contêm assemblies de interoperabilidade COM.

A função e a estrutura do arquivo .nuspec

Quando você souber quais arquivos deseja empacotar, a próxima etapa é criar um manifesto de pacote em um arquivo XML .nuspec .

O manifesto:

• Descreve o conteúdo do pacote e está incluído nele.
• Conduz a criação do pacote e informa ao NuGet como instalar o pacote em um projeto. Por exemplo, o manifesto identifica outras dependências de pacote para que o NuGet também possa instalar essas dependências quando o pacote principal estiver instalado.
• Contém propriedades necessárias e opcionais, conforme descrito no restante desta seção. Para obter informações detalhadas, incluindo outras propriedades não mencionadas aqui, consulte a referência .nuspec.

As seguintes propriedades são necessárias no manifesto:

• O identificador do pacote, que deve ser exclusivo em toda a galeria que hospeda o pacote
• Um número de versão específico no formato Major.Minor.Patch[-Sufixo], em que o -Sufixo identifica versões de pré-lançamento
• O título do pacote como deve aparecer no host (como nuget.org)
• Informações do autor
• Uma descrição longa do pacote

As seguintes propriedades são opcionais comuns:

• Notas de versão.
• Informações sobre direitos autorais.
• Uma breve descrição da interface do usuário Gerenciador de Pacotes em Visual Studio.
• Uma ID de localidade.
• Uma URL do projeto.
• Uma licença como uma expressão ou arquivo. A propriedade licenseUrl está obsoleta. Em vez disso, use o license elemento de metadados nuspec .
• Um arquivo read-me.
• Um arquivo de ícone. A propriedade iconUrl está obsoleta. Em vez disso, use o icon elemento de metadados nuspec .
• Listas de dependências e referências.
• Etiquetas que auxiliam em pesquisas de galerias.

O código a seguir é um arquivo .nuspec típico (mas fictício), com comentários que descrevem as propriedades:

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
    <metadata>
        <!-- An identifier that must be unique within the hosting gallery -->
        <id>Contoso.Utility.UsefulStuff</id>

        <!-- A package version number that's used when resolving dependencies -->
        <version>1.8.3</version>

        <!-- A comma-separated list of package authors that sometimes appears directly on the gallery -->
        <authors>Dejana Tesic, Rajeev Dey</authors>

        <!-- A project URL that provides a link for the gallery -->
        <projectUrl>http://github.com/contoso/UsefulStuff</projectUrl>

        <!-- License information that's displayed on the gallery -->
        <license type="expression">Apache-2.0</license>
        
        <!-- The location of a read-me file that's displayed in the Visual Studio Package Manager UI -->
        <readme>readme.md</readme>

        <!-- An icon that's used in the Visual Studio Package Manager UI -->
        <icon>icon.png</icon>

        <!-- 
            A property that when true, prompts the user to accept the license when
            installing the package
        -->
        <requireLicenseAcceptance>false</requireLicenseAcceptance>

        <!-- Detailed information about a particular release -->
        <releaseNotes>Bug fixes and performance improvements</releaseNotes>

        <!-- 
            A description that can be used in the Package Manager UI. The
            nuget.org gallery uses information you add in the portal. 
        -->
        <description>Core utility functions for web applications</description>

        <!-- Copyright information -->
        <copyright>Copyright ©2026 Contoso Corporation</copyright>

        <!-- Tags that appear in the gallery and can be used for tag searches -->
        <tags>web utility http json url parsing</tags>

        <!-- Dependencies that are automatically installed when the package is installed -->
        <dependencies>
            <dependency id="Newtonsoft.Json" version="9.0" />
        </dependencies>
    </metadata>

    <!-- A read-me Markdown file that's displayed in the Package Manager UI -->
    <files>
        <file src="readme.md" target="" />
        <file src="icon.png" target="" />
    </files>
</package>

Para obter informações detalhadas sobre como declarar dependências e especificar números de versão, consulte packages.config e controle de versão do pacote. Você também pode usar os include atributos e exclude no dependency elemento para especificar os ativos de dependência que deseja incluir ou excluir no pacote. Para obter mais informações, consulte .nuspec Reference – elemento Dependencies.

Como o manifesto está incluído no pacote criado a partir dele, você pode encontrar exemplos examinando pacotes existentes. Uma boa origem é a pasta global-packages em seu computador. Para localizar sua localização, use o seguinte comando:

nuget locals -list global-packages

Assim que souber a localização da pasta global-packages, execute as seguintes etapas para localizar um arquivo de manifesto:

1. Vá para a pasta de pacotes globais .
2. Nessa pasta, vá para a subpasta de qualquer pacote e vá para uma subpasta para qualquer versão desse pacote.
3. Na subpasta de versão, faça uma cópia do arquivo .nupkg e altere a extensão da cópia para zip.
4. Abra o arquivo .zip e examine o arquivo .nuspec dentro dele.

Criar o arquivo .nuspec

A criação de um manifesto completo normalmente começa com um arquivo .nuspec básico gerado por meio de um dos seguintes métodos:

• Um diretório de trabalho baseado em convenção
• Uma DLL de montagem
• A Visual Studio project
• Um novo arquivo com valores padrão

Em seguida, edite o arquivo manualmente para que ele descreva o conteúdo exato desejado no pacote final.

De um diretório de trabalho baseado em convenção

Como um pacote NuGet é um arquivo ZIP que foi renomeado com a extensão .nupkg , geralmente é mais fácil criar a estrutura de pastas desejada em seu sistema de arquivos local e, em seguida, criar o arquivo .nuspec diretamente dessa estrutura. Em nuget pack seguida, o comando adiciona automaticamente todos os arquivos nessa estrutura de pastas, mas exclui todas as pastas que começam com um período, para que você possa manter arquivos privados na mesma estrutura.

A vantagem dessa abordagem é que você não precisa especificar no manifesto quais arquivos você deseja incluir no pacote, conforme explicado posteriormente nesta seção. Em vez disso, você pode fazer com que o processo de build produza a estrutura exata da pasta que entra no pacote. Você também pode incluir facilmente outros arquivos que podem não fazer parte de um projeto caso contrário:

• Conteúdo e código-fonte que devem ser injetados no projeto de destino
• Scripts do PowerShell
• Transformações em arquivos de configuração e código-fonte existentes em um projeto

As pastas se alinham com as seguintes convenções:

Como sua estrutura de pastas pode conter assemblies para muitas estruturas de destino, esse método é necessário quando você cria pacotes que dão suporte a várias estruturas.

Quando você tiver a estrutura de pasta desejada em vigor, execute o seguinte comando nessa pasta para criar o arquivo .nuspec :

nuget spec

O arquivo .nuspec gerado não contém referências explícitas a arquivos na estrutura de pastas. O NuGet inclui automaticamente todos os arquivos quando o pacote é criado. No entanto, você ainda precisa editar valores de espaço reservado em outras partes do manifesto.

De uma DLL de assembly

No caso básico de criação de um pacote a partir de um assembly, você pode gerar um arquivo .nuspec a partir dos metadados no assembly usando o seguinte comando:

nuget spec <assembly-name>.dll

O uso deste formulário substitui alguns espaços reservados no manifesto por valores específicos do conjunto. Por exemplo, a <id> propriedade é definida como o nome do assembly e <version> é definida como a versão do assembly. No entanto, algumas propriedades no manifesto não têm valores correspondentes no assembly. Essas propriedades ainda contêm marcadores de posição depois que você executa o comando.

De um projeto de Visual Studio

A criação de um arquivo .nuspec de um arquivo .csproj ou .vbproj é conveniente, pois outros pacotes instalados no projeto são referenciados automaticamente como dependências. Para criar um manifesto de um arquivo de projeto, use o seguinte comando na pasta que contém o arquivo de projeto:

# Use in a folder that contains a project file, such as <project-name>.csproj or <project-name>.vbproj.
nuget spec

O arquivo project-name resultante contém tokens que são substituídos no tempo de empacotamento por valores do projeto, incluindo referências a quaisquer outros pacotes que já foram instalados.

Se você tiver dependências de pacote para incluir no .nuspec, utilize nuget pack. Em seguida, obtenha o arquivo .nuspec de dentro do arquivo .nupkg gerado. Por exemplo, use o seguinte comando:

# Use in a folder that contains a project file, such as <project-name>.csproj or <project-name>.vbproj.
nuget pack myproject.csproj

Um token é delimitado por $ símbolos em ambos os lados da propriedade do projeto. Por exemplo, o <id> valor em um manifesto gerado dessa forma normalmente se parece com a seguinte linha:

<id>$id$</id>

Esse token é substituído pelo valor AssemblyName do arquivo de projeto no momento do empacotamento. Para obter o mapeamento exato de valores de projeto para tokens do arquivo .nuspec, consulte Tokens de substituição.

Os tokens eliminam a necessidade de atualizar valores cruciais, como o número de versão no arquivo .nuspec à medida que você atualiza o projeto. Mas você também pode substituir os tokens por valores literais.

Várias opções extras de empacotamento estão disponíveis quando você trabalha em um projeto de Visual Studio, conforme descrito no pacote nuget Run para gerar o arquivo .nupkg posteriormente neste artigo.

Pacotes no nível da solução

Somente NuGet 2.x. Não disponível no NuGet 3.0+.

O NuGet 2.x dá suporte à noção de um pacote no nível da solução que instala ferramentas ou comandos extras para o Console Gerenciador de Pacotes (o conteúdo da pasta tools), mas não adiciona referências, conteúdo ou personalizações de build a nenhum projeto na solução. Esses pacotes não contêm arquivos em suas pastas diretas lib, content ou build, e nenhuma de suas dependências tem arquivos nas respectivas pastas lib, content ou build.

O NuGet rastreia pacotes instalados no nível da solução em um arquivo packages.config na pasta .nuget , em vez do arquivo packages.config do projeto.

De um novo arquivo com valores padrão

O comando a seguir cria um manifesto padrão com espaços reservados, o que ajuda a garantir que você comece com a estrutura de arquivo adequada:

nuget spec [<package-name>]

Se você omitir <package-name>, o arquivo resultante se chamará Package.nuspec. Se você fornecer um nome como Contoso.Utility.UsefulStuff, o arquivo se chamará Contoso.Utility.UsefulStuff.nuspec.

O arquivo .nuspec resultante contém espaços reservados para valores como projectUrl. Antes de usar o arquivo para criar o arquivo .nupkg final, substitua os espaços reservados pelos valores apropriados.

Escolha um identificador de pacote exclusivo e defina o número da versão

O identificador do pacote (<id> elemento) e o número da versão (<version> elemento) são os dois valores mais importantes no manifesto, pois identificam exclusivamente o código exato contido no pacote.

Práticas recomendadas para o identificador de pacote

• Exclusividade: o identificador deve ser exclusivo na galeria que hospeda o pacote, como nuget.org. Antes de decidir sobre um identificador, pesquise na galeria aplicável para verificar se o nome já está em uso. Para evitar conflitos, um bom padrão é usar o nome da empresa como a primeira parte do identificador, como Contoso.
• Namespace-like names: siga um padrão semelhante aos namespaces em .NET, usando notação de ponto em vez de hifens. Por exemplo, use Contoso.Utility.UsefulStuff em vez de Contoso-Utility-UsefulStuff ou Contoso_Utility_UsefulStuff. Os consumidores também acham útil quando o identificador de pacote corresponde aos namespaces usados no código.
• Pacotes de exemplo: se você produzir um pacote de código de exemplo que demonstra como usar outro pacote, anexe-se .Sample como um sufixo ao identificador, como em Contoso.Utility.UsefulStuff.Sample. Um pacote de exemplo desse tipo depende do pacote que ele demonstra como usar. Ao criar um pacote de exemplo, use o método de diretório de trabalho baseado em convenção descrito anteriormente. Na pasta de conteúdo , organize o código de exemplo em uma pasta chamada \Samples\<identifier>, como em \Samples\Contoso.Utility.UsefulStuff.Sample.

Práticas recomendadas para a versão do pacote

• Em geral, defina a versão do pacote para corresponder à biblioteca. Essas diretrizes são recomendadas, mas não estritamente necessárias. Essa prática é simples quando você limita um pacote a um único assembly, conforme descrito anteriormente em Decidir quais assemblies empacotar. Em geral, lembre-se de que o NuGet em si lida com versões de pacote ao resolver dependências, não com versões de assembly.
• Ao usar um esquema de versão não padrão, considere as regras de controle de versão do NuGet, conforme explicado no controle de versão do Pacote.

Para outros recursos que são úteis para entender o controle de versão, consulte a seguinte série de breves postagens no blog:

• Parte 1: Enfrentando o Inferno da DLL
• Parte 2: O algoritmo principal
• Parte 3: Unificação por meio de redirecionamentos de vinculação

Adicionar um arquivo read-me e outros arquivos

Para especificar diretamente os arquivos que serão incluídos no pacote, utilize o nó <files> no arquivo .nuspec, que segue a tag .

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
    <metadata>
        <!-- ... -->
    </metadata>
    <files>
        <!-- Add files from an arbitrary folder that's not necessarily in the project. -->
        <file src="..\..\SomeRoot\**\*.*" target="" />
    </files>
</package>

Para incluir um arquivo de leitura-me no pacote, use o readme elemento de metadados para especificar o caminho de destino para o arquivo read-me. Use também um file elemento de metadados para especificar o caminho de origem e a pasta de destino do arquivo read-me. Para obter mais informações, consulte readme.

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
    <metadata>
        <!-- ... -->
        <readme>docs\readme.md</readme>
        <!-- ... -->
    </metadata>
    <files>
        <!-- Add a read-me file. -->
        <file src="..\readme.md" target="docs\" />
    </files>
</package>

Visual Studio exibe o conteúdo do arquivo read-me na interface do usuário do Gerenciador de Pacotes. Por exemplo, a captura de tela a seguir mostra o arquivo read-me do HtmlAgilityPack pacote:

Incluir props e alvos do MSBuild em um pacote

Em alguns casos, talvez você queira adicionar destinos ou propriedades de build personalizados a projetos que consomem seu pacote, como executar uma ferramenta personalizada ou um processo durante o build. Para obter mais informações sobre destinos e propriedades de build personalizados, consulte .props e .targets do MSBuild em um pacote.

Crie arquivos <package-id.targets> ou <package-id.props>, como Contoso.Utility.UsefulStuff.targets, nas pastas do build do projeto.

Em seguida, no arquivo .nuspec, consulte estes arquivos no elemento <files>:

<?xml version="1.0"?>
<package >
    <metadata minClientVersion="2.5">
    <!-- ... -->
    </metadata>
    <files>
        <!-- In the package build folder, include everything that's in the local build folder. -->
        <file src="build\**" target="build" />

        <!-- Other files -->
        <!-- ... -->
    </files>
</package>

Quando os pacotes são adicionados a um projeto, o NuGet inclui automaticamente essas propriedades e destinos.

Executar o pacote nuget para gerar o arquivo .nupkg

Ao usar um assembly ou o diretório de trabalho baseado em convenção, crie um pacote ao rodar nuget pack com o arquivo .nuspec. No seguinte comando, substitua <project-name> pelo nome do seu projeto:

nuget pack <project-name>.nuspec

Ao usar um projeto Visual Studio, execute nuget pack com o arquivo de projeto. Esse comando carrega automaticamente o arquivo .nuspec do projeto e substitui todos os tokens nele pelos valores correspondentes no arquivo de projeto:

nuget pack <project-name>.csproj

Em todos os casos, nuget pack exclui pastas que começam com um período, como .git ou .hg.

O NuGet indica se há erros no arquivo .nuspec que precisam ser corrigidos, como valores de espaço reservado no manifesto que precisam ser atualizados.

Depois que nuget pack for concluído com êxito, você terá um arquivo .nupkg que pode ser publicado em uma galeria apropriada, conforme descrito em Publicar pacotes NuGet.

Opções adicionais

Você pode usar várias opções de linha de comando com nuget pack para excluir arquivos, substituir o número de versão no manifesto e alterar a pasta de saída, entre outros recursos. Para obter uma lista completa, consulte o comando do pacote (CLI do NuGet).

As opções a seguir são algumas que são comuns com projetos Visual Studio:

• Projetos referenciados: se o projeto fizer referência a outros projetos, você poderá adicionar os projetos referenciados como parte do pacote ou como dependências usando a opção -IncludeReferencedProjects :

  nuget pack MyProject.csproj -IncludeReferencedProjects
  

  Esse processo de inclusão é recursivo. Por exemplo, se MyProject.csproj fizer referência aos projetos B e C, e esses projetos fizerem referência a D, E e F, os arquivos de B, C, D, E e F serão incluídos no pacote.

  Se um projeto referenciado incluir um arquivo .nuspec próprio, o NuGet adicionará esse projeto referenciado como uma dependência. Você precisa empacotar e publicar esse projeto separadamente.

• Configuração de build: por padrão, o NuGet usa a configuração de build padrão definida no arquivo de projeto, normalmente Debug. Para empacotar arquivos de uma configuração de build diferente, como Release, use a opção -properties com a configuração:

  nuget pack MyProject.csproj -properties Configuration=Release
  

• Símbolos: para incluir símbolos que possibilitam que os consumidores percorram o código do pacote no depurador, use as opções -Symbols e -SymbolPackageFormat. Para a opção -SymbolPackageFormat , especifique um formato de snupkg:

  nuget pack MyProject.csproj -symbols -SymbolPackageFormat snupkg
  

Testar a instalação do pacote

Antes de publicar um pacote, você normalmente deseja testar o processo de instalação do pacote em um projeto. Um teste ajuda a garantir que todos os arquivos necessários acabem no lugar correto no projeto.

Você pode testar instalações manualmente no Visual Studio ou na linha de comando usando as etapas de instalação padrão pacote.

Para testes automatizados, você pode usar o seguinte processo básico:

1. Copie o arquivo .nupkg para uma pasta local.
2. Adicione a pasta às fontes do pacote usando o nuget sources add -name <name> -source <path> comando. Para obter mais informações, consulte o comando de fontes (CLI do NuGet). Você precisa definir essa fonte local apenas uma vez em um determinado computador.
3. Instale o pacote dessa origem usando nuget install <package-ID> -source <name>. Neste comando, <name> deve corresponder ao nome da origem que você usa no nuget sources comando. Especificar a origem faz com que o NuGet instale o pacote apenas dessa fonte específica.
4. Examine o sistema de arquivos para verificar se os arquivos estão instalados corretamente.

Conteúdo relacionado

Depois de criar um pacote, que é um arquivo .nupkg , você pode publicá-lo na galeria de sua escolha. Para obter mais informações, consulte Publicar pacotes NuGet.

Você também pode estender os recursos do pacote ou dar suporte a outros cenários. Para obter mais informações, consulte os seguintes artigos:

• Controle de versão do pacote
• Support várias versões de .NET
• Transformando o código-fonte e os arquivos de configuração
• Criando pacotes NuGet localizados
• Criando pacotes de pré-lançamento
• Definir um tipo de pacote NuGet
• Criar pacotes NuGet que contêm assemblies de interoperabilidade COM

Para conhecer outros tipos de pacote, consulte os seguintes artigos:

• Criando pacotes nativos
• Criando pacotes de símbolos (.snupkg)