Aprenda a criar seu primeiro pacote NuGet
O assunto NuGet está longe de ser novidade - aliás, hoje em dia é quase impossível criar um projeto .NET no Visual Studio que não tenha algum pacote NuGet em uso. Entretanto, por mais convenientes que esses pacotes possam ser, a verdade é que poucos times têm criado pacotes para compartilhar suas bibliotecas de uso interno por achar que dá muito trabalho. Sabia que criar um pacote NuGet para uns biblioteca de uso interno é mais simples do que parece? Veja neste post como criar seu primeiro pacote NuGet. A ideia deste post é te ajudar na criação do seu primeiro pacote NuGet. Isso significa que não iremos a fundo em nenhum dos aspectos da criação de pacotes. Por outro lado, o site oficial do NuGet tem uma documentação detalhada sobre a criação de pacotes, para quando você estiver pronto para se aprofundar. Enquanto isso, vamos começar com o básico. Todos os exemplos daqui por diante usarão uma hipotética biblioteca de validação de CPF feita em C#, criada por um time em uma empresa fictícia chamada Fabrikam, que deseja compartilhar essa biblioteca com outros times internos dentro da mesma empresa.
Conceitos básicos
Pacotes NuGet são um mecanismo conveniente para o compartilhamento de artefatos de software. Apesar de otimizados para compartilhar bibliotecas (assemblies) .NET, eles podem ser usados para muito mais que apenas.net, sendo usados para empacotar virtualmente qualquer coisa que precise ser versionada e distribuída de maneira conveniente. Quer um exemplo? Sabia que há vários casos de pacotes NuGet que contêm apenas scripts PowerShell? É uma maneira prática de empacotar e redistribuir scripts que são usados, por exemplo, durante o processo de build e deployment de uma aplicação. Tecnicamente falando, um pacote NuGet é apenas um arquivo ZIP que segue um padrão de nomenclatura e contém um arquivo de metadados descrevendo o conteúdo do dito arquivo. Significa que, desde que seguindo as convenções apropriadas, poderíamos criar um pacote NuGet usando apenas uma ferramenta de compactação como o 7-Zip! Vamos ver agora cada um desses três aspectos: nomenclatura, metadados e conteúdo.
Nome de um pacote NuGet
Pacotes NuGet devem seguir uma convenção ao serem nomeados. Você deve, obrigatoriamente, seguir a mesma convenção para que seu pacote seja reconhecido pelo NuGet: <Nome do pacote>.<Versão SemVer>.nupkg No nome do pacote, você pode usar letras, números e pontos. Uma estratégia comum parte evitar colisões de nome é usar o nome da empresa como prefixo no nome da biblioteca, tal como fazemos com assemblies .NET. No nosso exemplo, nosso pacote irá se chamar Fabrikam.ValidadorCPF. A extensão do arquivo, por sua vez, sempre deverá ser nupkg. Vamos falar agora sobre versionamento.
Versionamento de pacotes
O versionamento de pacotes é um aspecto central no NuGet. Afinal, um dos grandes benefícios de se usar o NuGet é poder gerenciar as diferentes dependências de um projeto, atualizando-as sempre que desejado ou necessário. Para isso, faz-se preciso usar um esquema para descrição da versão dos pacotes. O problema é um número de versão, por mais que seja algo corriqueiro em nossos dias, está longe de ser consistente. Afinal, se você chegar numa roda de amigos programadores e apresentar um número de versão como 1.0.3.257 e perguntar qual o significado de cada um dos segmentos (e em que circunstâncias eles devem ser incrementados) vai provavelmente ouvir explicações bem diferentes. Na tentativa de criar um algoritmo consistente para a definição de números de versão, nasceu a iniciativa de Versionamento Semântico (_ Semantic Versioning_), que descreve como criar um identificador de versão, qual o significado de cada segmento e em que circunstâncias incrementa-los. O NuGet, felizmente, segue o padrão definido no site semver.org, que é a fonte oficial de documentação para o Versionamento Semântico. É importante que você se familiarize com esse conceito; dê uma pausa na leitura deste post, vá até o semver.org e depois volte aqui. Eu espero ;-). Voltando ao nosso exemplo, escolhi decidi que meu primeiro pacote vai nascer com a versão 1.0. Dessa forma, o nome completo do meu pacote (agora com o número da versão) fica sendo: Fabrikam.ValidadorCPF.1.0.0.nupkg Simples, né? Agora vamos falar dos metadados necessários para descrever nosso pacote.
Metadados – o arquivo de manifesto
Quando você acessa a caixa de diálogo de Gestão de Pacotes do Visual Studio (ou quando navega pelo site NuGet.org) pode perceber que um pacote NuGet contém vários metadados que ajudam a descreve-lo. Informações como nome amigável, autor, descrição, dependências… Sem isso, outros programadores teriam dificuldade em entender para que seu pacote serve. Esses metadados fazem parte de um arquivo de especificação NuGet - um arquivo XML de manifesto, com um formato predeterminado e de extensão nuspec. Precisamos criar esse arquivo e incorpora-lo em nosso pacote (ou seja, coloca-lo dentro do arquivo zip). 
A definição completa do formato de arquivo nuspec está disponível no site oficial do NuGet, caso você queira se aprofundar depois. Vamos ver agora os elementos básicos para a criação de um manifesto para descrever o nosso pacote de validação de CPF:
1
<?xml version="1.0" encoding="utf-8"?> <package> <metadata> <id>Fabrikam.ValidadorCPF</id> <version>1.0.0</version> <authors>Time de Serviços Compartilhados da Fabrikam</authors> <description>Este pacote oferece rotinas de validação de CPF para aplicações .NET</description> <language>pt-BR</language> <projectUrl>http://intranet.fabrikam.com/componentes/Fabrikam.ValidadorCPF</projectUrl> <licenseUrl>http://intranet.fabrikam.com/componentes/Fabrikam.ValidadorCPF/license.htm</licenseUrl> </metadata> </package>
Exemplo do arquivo Fabrikam.ValidadorCPF.nuspec Este é o manifesto típico de um pacote NuGet. Nele você vê os elementos que, minimamente, precisam estar presentes num arquivo nuspec para descrever seu pacote. Os elementos são auto-explicativos, com exceção talvez dos dois URLs. O primeiro,
Conteúdo – definindo os arquivos a empacotar
Ainda no nosso arquivo nuspec, precisamos agora listar quais arquivos devem ser incluídos em nosso pacote. Para manter nosso exemplo simples, incluirei apenas um arquivo: o assembly da nossa biblioteca de validação de CPF. O conteúdo do pacote NuGet é definido a partir do elemento
1
<?xml version="1.0" encoding="utf-8"?> <package> <metadata> <id>Fabrikam.ValidadorCPF</id> <version>1.0.0</version> <authors>Time de Serviços Compartilhados da Fabrikam</authors> <description>Este pacote oferece rotinas de validação de CPF para aplicações .NET</description> <language>pt-BR</language> <projectUrl>http://intranet.fabrikam.com/componentes/Fabrikam.ValidadorCPF</projectUrl> <licenseUrl>http://intranet.fabrikam.com/componentes/Fabrikam.ValidadorCPF/license.htm</licenseUrl> </metadata> <files> <file src="bin\Release\Fabrikam.ValidadorCPF.dll" target="lib" /> <file src="bin\Release\Fabrikam.ValidadorCPF.xml" target="lib"/> </files> </package>
Nas linhas em destaque podemos que nossos dois arquivos são obtidos a partir da pasta Bin\Release do projeto e copiados para uma pasta chamada lib, através do atributo target do elemento
Gerando o arquivo .nupkg
Com o arquivo .nuspec criado, tudo fica bem fácil. Vamos usar a ferramenta de linha de comando do NuGet (nuget.exe; instruções para download aqui). A primeira coisa a fazer é compilar seu projeto em modo Release (pois é a configuração que estamos referenciando no arquivo nuspec de exemplo). Depois, abra o prompt de comando e, a partir da pasta onde estão os arquivos de projeto, execute: nuget pack Fabrikam.ValidadorCPF.nuspec O resultado é seu arquivo .nupkg, pronto para uso!  Pronto para testar? Então abra seu Visual Studio e siga os passos abaixo.  Em Tools |
Options, pesquise por “nuget” (1). Aí, selecione a opção Package Sources (2) e clique no botão para adicionar uma nova origem de pacotes NuGet (3). Dê um nome qualquer a essa nova origem (4), informe o diretório onde acabamos de gerar o arquivo .nupkg (5) e então clique em Update (6) e OK. Finalmente, crie um novo projeto .NET qualquer e selecione a opção “Manage NuGet Packages…”.  Na janela do NuGet, selecione a origem de pacotes (1) que acabamos de criar e veja o que acontece! |
Distribuindo os pacotes
Obviamente nada disso faz sentido se você não puder compartilhar seus pacotes com os outros desenvolvedores da empresa. Logo, vem a pergunta: onde hospedo meus pacotes para que outros desenvolvedores tenham acesso? Bem, isso depende se seu pacote é público ou privado.
Pacotes públicos
Para pacotes públicos (que podem ser livremente usados por desenvolvedores dentro e fora da sua empresa), a escolha óbvia é o nuget.org. Entretanto, por ser um repositório acessível ao público em geral, não é o melhor lugar para publicar pacotes de teste. Enquanto você estiver testando seus pacotes, utilize o serviço do site myget.org. O plano gratuito é suficiente para fins de testes.
Pacotes privados
Se seus pacotes são apenas para uso interno de sua empresa, um repositório público obviamente não é uma boa opção. Há um sem-número de opções para hospedar repositórios NuGet privados, seja na nuvem ou dentro de sua empresa:
- Nuvem (“NuGet-as-a-Service”)
- Visual Studio Team Services
- MyGet.org (apenas nos planos pagos)
- AppVeyor
- On-premises (servidor interno)
- Pasta de rede (simples mas inconveniente; você precisa clicar em Update na janela de opções “Package Sources” do Visual Studio para obter novos pacotes. Não recomendo)
- NuGet Server (muito rudimentar; não tem nenhuma interface Web. Não recomendo)
- Inedo ProGet
- JFrog Artifactory
- Sonatype Nexus
Na maioria dos casos (com exceção das pastas de rede e do AppVeyor), você precisa criar uma conta. Uma vez criada, sua conta conterá uma informação fundamental para o processo de publicação: sua chave de API (API Key). Essa chave será usada pelo comando push do NuGet, responsável por publicar seu pacote para seu repositório. O comando é:
nuget push -Source <URL do servidor de destino> -ApiKey <sua chave de API>Os desenvolvedores que forem usar seus pacotes precisam adicionar seu repositório ao Visual Studio. O processo é idêntico àquele que usamos logo acima para adicionar a pasta de testes; a diferença é que ao invés de apontar para um diretório local no computador, eles adicionariam o URL do seu feed NuGet. Cada repositório NuGet representa seus URLs de feed de uma maneira diferente. Verifique a documentação do seu repositório escolhido para saber qual URL deve ser adicionada ao Visual Studio.
Conclusão
Ufa! Sei que é bastante coisa para um post só, mas acho que com isso você já consegue iniciar a construção de seus primeiros pacotes. Ainda há muito mais para ser explorado neste assunto. Fique ligado nos próximos posts sobre NuGet! Ah, deixo um exercício para você, caro leitor: Se você reparar bem, verá que muitos dos metadados incluídos em nosso arquivo .nuspec tipicamente estão presentes também em nosso assembly .NET, através dos vários atributos de metadados de assembly. Informações como nome, descrição, autor, versão e outros provavelmente estarão duplicados. Não seria muito mais legal se, ao invés de digitar essas informações no arquivo .nuspec, pudéssemos instruir o NuGet a buscar isso dentro de nosso projeto em tempo de empacotamento? Assim poderíamos manter esses dados em um lugar só: no projeto .NET! O exercício, portanto, é: como fazer o NuGet reaproveitar os metadados de assembly que temos em nosso projeto, para que não precisemos redigitar esses mesmos dados no arquivo .nuspec? Bom exercício! Ah, e não deixe de compartilhar sua opinião nos comentários! Um abraço, Igor
02/03/2016 | Por Igor Abade V. Leite | Em Técnico | Tempo de leitura: 10 mins.
