Este artigo foi traduzido por máquina.
NuGet
Tornando-se um autor de NuGet
Na edição de novembro, Phil Haack introduziu NuGet, um novo ecossistema de gerenciamento de pacote para desenvolvedores (msdn.microsoft.com/magazine/hh547106). NuGet é um projeto da Fundação Outercurve, cujo objetivo é tornar-se um sistema de gerenciamento de pacote de primeira classe para a Microsoft.NET Framework. A equipe do projeto consiste principalmente de desenvolvedores da Microsoft trabalhando em colaboração com a Comunidade de desenvolvedores. A introdução do NuGet ao nosso ecossistema de desenvolvimento dá.NET desenvolvedores uma maneira para consumir, autor e publicar pacotes.
À primeira vista, NuGet parece ser uma ferramenta apenas para a Comunidade open source, mas isso é apenas parte de uma história maior. NuGet foi projetado especificamente para ajudar a distribuir pacotes dentro da Comunidade de código aberto, mas também para oferecer pacotes internos atrás do firewall em uma empresa. Isso significa que você pode usar o NuGet de uma forma multifacetada para instalar e atualizar pacotes da Microsoft e da Comunidade open source em geral, bem como servidores internos.
Neste artigo, vou explorar o que é preciso para se tornar um autor do pacote NuGet. Incorporando NuGet em seu ciclo de vida de desenvolvimento não é complicado, e ele vai render awesomeness substancial. Uma vez feito isso, seus problemas de consumo, a criação e distribuição de pacote irão desaparecer para uma memória distante. No mês que vem, vai aprofundar o que é preciso para hospedar seus próprios pacotes.
Ecossistema definida
Antes de iniciar a viagem para tornar-se um autor de pacote, vejamos brevemente novamente o maior ecossistema. NuGet, do ponto de vista do distribuidor de pacote, consiste de alguns componentes essenciais, principalmente um utilitário de linha de comando chamado NuGet.exe (nuget.codeplex.com/releases/view/58939) e um servidor para hospedar os pacotes, tais como o oficiais NuGet Gallery, nuget.org. Conforme demonstrado artigo do mês passado, você pode interagir com NuGet de três maneiras: usando NuGet.exe, e NuGet dentro do Visual Studio (a janela de Console do Gerenciador de pacotes (View | Outras janelas) e usando o Explorador de pacotes de NuGet (npe.codeplex.com). Esses utilitários interagem com um ou mais repositórios de NuGet. Por outro lado, nuget.org é uma galeria pública, você pode usar para armazenar, acolher e publicar pacotes NuGet. Nuget.org é construído usando outro projeto de código aberto conhecido como NuGetGallery, que você pode encontrar em github.com/nuget/nugetgallery. Falarei mais sobre como hospedar sua própria galeria de NuGet na próxima edição.
Como um autor de pacote, você pode publicar muitos pacotes diferentes para um repositório de NuGet e cada pacote pode ter várias versões. Nuget.org dá aos seus clientes a oportunidade de ler detalhes sobre um pacote, instale o pacote, entre em contato com o proprietário do pacote e, no que deve ser raros casos, relatar abuso.
Como o autor de pacote, você pode controlar itens tais como números de versão, dependências e como seu pacote será instalado.
Ficando configurado
Para publicar um pacote, supondo que você estará usando nuget.orgas o repositório, você precisa se inscrever para uma conta na Galeria NuGet. É fácil tornar-se um autor: Basta navegar até o Contribute a seção Galeria de NuGet na nuget.org/contribute/index e selecione Iniciar. Em seguida, clique em registe-se agora para obter o formulário de registro e preencha as informações necessárias para criar uma nova conta. Nuget.org enviará um e-mail com um URL onde você pode confirmar seu endereço de email e conta.
Após a confirmação de sua conta, você pode efetuar logon no site e obter sua chave de acesso, um símbolo exclusivo que identifica o repositório de nuget.org e permite que você automatizar várias tarefas de gerenciamento de pacotes, tais como empurrar uma atualização para seu pacote.
Neste artigo, demonstrarei a linha de comando NuGet.exe e o NuGet Package Explorer. Um ponto a ser observado: Depois de baixar a versão de linha de comando, você provavelmente vai querer atualizar a variável de ambiente path do sistema para incluir a sua localização. Isto torna mais fácil de usar NuGet de qualquer lugar no seu sistema.
Anatomia de um pacote
Como observado no último artigo, um pacote de NuGet é um arquivo de contêiner de Convenção de embalagem aberta (OPC) com a. extensão de arquivo de nupkg. O formato do pacote depende fortemente de convenções, com um arquivo de manifesto na raiz conhecido como o arquivo nuspec. Um exemplo de estrutura de diretório inicialmente pode parecer como este:
Root Folder
| package.manifest
+---lib
+---content
+---tools
Como você pode ver, há três pastas na raiz:
- lib contém todos os módulos (assemblies) a ser referenciada
- conteúdo contém arquivos e diretórios que são copiados para a raiz do seu projeto de destino
- ferramentas é um lugar de scripts personalizados do Windows PowerShell que pode ser executado na instalação do seu pacote ou sempre que o projeto de destino é carregado no Visual Studio
Destes, a pasta lib é a mais complexa. Ele contém as subpastas que correspondem às dependências do quadro, como mostrado aqui:
Root
| package.manifest
\---lib
| MyFirstAssembly.dll
\---net11
| MySecondAssembly.dll
\---net20
| MySecondAssembly.dll
\---sl
| MySecondAssembly.dll
\---netmf
| MySecondAssembly.dll
+---content
+---tools
Se seu assembly funciona em todas as versões da.NET Framework (raras na verdade!), que você precisa incluir apenas na raiz da pasta lib, com MyFirstAssembly.dll.
Dado como raro é que o cenário, a equipe NuGet desestimula fortemente a prática. É melhor fazer seu assembly dependente de uma versão específica do framework. Para fazer isso, adicionar uma pasta para essa versão do framework e incluem a versão correta do assembly nessa pasta. Como você pode ver na pasta de exemplo, MySecondAssembly.dll tem uma versão diferente para o.NET Framework 1.1, 2.0, Silverlight e o.NET MicroFramework. Isso garante a NuGet instala seu pacote corretamente para os quadros de destino.
Quando seu cliente instala seu pacote, NuGet irá instalar assemblies corretos com base na estrutura de destino para o projeto. No exemplo anterior, vamos supor que seu cliente está a tentar instalar o pacote em um projeto que destinos versão 4 da.NET Framework. Porque não está listado como um quadro na pasta lib amostra, NuGet vai ter a versão do framework mais próximo disponível e usá-lo. Neste exemplo, levaria os assemblies localizados na pasta net20 e usá-las.
A pasta de conteúdo é um clone de pasta raiz do projeto de destino. Nada encontrado nessa pasta será copiado como é para o projeto de destino. Por exemplo, se você quiser copiar algumas imagens na pasta de /images do destino, você precisará incluir essas imagens na pasta /content/images.
A pasta de ferramentas inclui quaisquer scripts do Windows PowerShell que NuGet invocará durante a instalação do pacote ou quando o projeto é aberto, ou que são usados mais tarde pelo cliente. Uma vez que a pasta é copiada para o projeto de destino, ele é adicionado para o '$ env: variável de ambiente Path (caminho) no Console do Gerenciador de pacotes do Visual Studio.
NuGet tem um mecanismo interno para automatizar o preenchimento de seu pacote — o nó de arquivos. O nó de arquivos é uma maneira de indicar expressamente os arquivos a serem copiados em sua estrutura de pacote ao criar o. arquivo nupkg. Isso ajuda a automatizar todo processo de embalagem. O elemento do arquivo é simples, definir atributos src, destino e excluir. Como você pode imaginar, src define o arquivo a que ser copiado; destino define o destino desejado copiados para; e excluir define o que você não quer copiada:
<files>
<file src="bin\Debug\*.dll" target="lib" />
<file src="bin\Debug\*.pdb" target="lib" />
<file src="tools\**\*.*" exclude="*.log" />
</files>
Se você tiver outro processo para criar seu pacote, você pode ignorar o nó de arquivos na. arquivo nuspec.
A. nuspec arquivo
O arquivo nuspec é seu manifesto de pacote. Ele é um arquivo XML simple que define seu pacote global e inclui coisas como nome, número da versão, referências de pacote e assim por diante. Para criar seu novo manifesto, NuGet.exe tem um comando chamado especificações que você pode usar como um ponto de partida:
> NuGet.exe spec
O especificações comando cria um novo arquivo chamado pacote. nuspec, um arquivo válido que contém dados de exemplo. Figura 1 mostra um exemplo de arquivo criado por spec.
Figura 1 amostra. nuspec arquivo
<?xml version="1.0"?>
<package >
<metadata>
<id>Package</id>
<version>1.0</version>
<authors>csell5</authors>
<owners>csell5</owners>
<licenseUrl>http://LICENSE_URL_HERE_OR_DELETE_THIS_LINE</licenseUrl>
<projectUrl>http://PROJECT_URL_HERE_OR_DELETE_THIS_LINE</projectUrl>
<iconUrl>http://ICON_URL_HERE_OR_DELETE_THIS_LINE</iconUrl>
<requireLicenseAcceptance>false</requireLicenseAcceptance>
<description>Package description</description>
<copyright>Copyright 2011</copyright>
<tags>Tag1 Tag2</tags>
<dependencies>
<dependency id="SampleDependency" version="1.0" />
</dependencies>
</metadata>
</package>
Depois que esse arquivo é criado, você substituir os valores de amostra. Para a maioria dos valores, você apenas fazer isso vez que, embora alguns vão mudar mais frequentemente. Por exemplo, a identificação do seu pacote não deve alterar depois que ele é publicado, mas o número da versão muda com cada lançamento.
Você também pode executar nuget.exe spec contra um arquivo de projeto do Visual Studio (como. csproj ou. vbproj). Neste caso, os valores padrão já estão preenchidos com base nos metadados no arquivo de projeto. Aqui estão alguns dos elementos mais simples do. arquivo nuspec:
- identificador exclusivo de identificação para o pacote.
- título do título humanos-amigável do pacote
- descrição detalhada descrição do pacote
- resumo breve descrição do pacote
- licenseURl um link para a licença
- direitos de autor copyright detalhes do pacote
Existem actualmente 28 diferentes elementos de nível superior. Enquanto o. arquivo nuspec é bastante auto-explicativo, você pode encontrar todos os detalhes em bit.ly/lgQ4J4. Agora vamos dar uma olhada em alguns dos mais complexos. nuspec elementos.
Dependências e referências
Todos sabemos que gerenciar dependências pode ser difícil, especialmente quando a Cadeia de dependências torna-se longo e inter-relacionada. Vamos dizer você construiu PackageA. Seu pacote acontece ao usar PackageB, que também pode ser encontrado em NuGet. Ao invés de incluindo PackageB dentro de seu pacote, você só precisa criar uma "dependência" nele. Quando alguém começa a instalar o pacote, NuGet primeiro inspeciona o arquivo nuspec para suas dependências. Em seguida, analisa cada pacote de dependência e examina suas dependências e assim por diante, até que ele constrói um gráfico de cada pacote precisa para fazer o download, para cumprir todas as dependências. Ele, em seguida, transfere todo o gráfico de pacotes e instala-los. Esse recurso de NuGet drasticamente simplifica a instalação e criação de pacotes.
Vejamos algumas dependências de pacotes definidas como mostrado no nó dependência aqui:
<package>
<metadata>
<dependencies>
<dependency id="SampleDependency" version="1.0" />
<dependency id="AnotherSampleDependency" version="[1.2,2.5)" />
</dependencies>
</metadata>
</package>
Você pode listar dependências quantos forem necessários. Em cada caso, o atributo id indica o pacote que você têm uma dependência e o atributo de versão representa o intervalo de versão que você exige. Meu exemplo aqui mostra uma dependência no projeto SampleDependency igual a versão 1.0 ou superior.
A especificação de intervalo de versão NuGet dá-lhe a capacidade de definir uma determinada gama de versões que você permite. Isso é algo como versão = "[1.2, 2.5)", onde o colchete define a inclusão e o parêntese, exclusão. Este exemplo indica que qualquer pacote igual ou superior a 1,2 e menos de 2.5 é permitido. NuGet terá a versão mais recente encontrada nesse intervalo. Para obter informações detalhadas sobre a especificação do intervalo de versão, visite bit.ly/qVXWxs.
Em alguns casos, a pessoa Instalando seu pacote pode precisar programar tipos em um.NET Framework assembly. Para adicionar a referência adequada, adicionar o nó de frameworkAssemblies para o. nuspec arquivo, detalhando a lista de assemblies do framework necessárias, da seguinte forma:
<package>
<metadata>
<frameworkAssemblies>
<frameworkAssembly assemblyName="System.Something" targetFramework="net40" />
<frameworkAssembly assemblyName="System.SomethingElse" />
</frameworkAssemblies>
</metadata>
</package>
Transformações
Muitos projectos requerem mais do que apenas uma referência de assembly para funcionar corretamente. Eles podem precisar de uma alteração no arquivo. config, ou mesmo algum código fonte modificado — e NuGet ambos os cenários suporta nativamente. Falarei sobre transformações de arquivo. config aqui. Para obter mais informações sobre transformações, por favor consulte bit.ly/jqzry2.
Durante a instalação do seu pacote de NuGet, NuGet será executado a transformação para adicionar seus novos valores. config. Para que isso aconteça, você precisa adicionar um arquivo de transformação para a pasta de conteúdo de seu pacote. Este é um arquivo XML válido com a extensão "transformação", cujo nome do arquivo coincide com o arquivo ao qual você deseja aplicar a transformação. Por exemplo, para aplicar uma transformação em um arquivo Web. config, você incluiria um arquivo chamado web.config.transformation.
Seu arquivo de transformação deve incluir apenas as seções do arquivo de configuração que você deseja adicionados ao arquivo de destino. Digamos que você deseja adicionar um novo módulo para seção de System. WebServer do seu cliente. Basta adicione essa seção em sua totalidade para o arquivo de transformação, como este:
<configuration>
<system.webServer>
<modules>
<add name="NewModule" type="My.NewModule" />
</modules>
<system.webServer>
</configuration>
NuGet não irá substituir seções existentes com as seções você adicionar mas sim mesclá-los juntos. Assim se seu destino já tinha uma seção de módulos com seu próprio módulo listado, o resultado dos dois arquivos sendo mesclados após a instalação poderia ser algo como isto:
<configuration>
<system.webServer>
<modules>
<add name="ExistingModule" type="Their.ExistingModule" />
<add name="NewModule" type="My.NewModule" />
</modules>
<system.webServer>
</configuration>
Como você pode ver, o módulo é adicionado ao final da pilha existente de módulos. Se um usuário quiser remover seu pacote, apenas as alterações serão removidas (supondo que você não fez quaisquer alterações a essas secções), deixando o resto como era em primeiro lugar.
Controle de versão
Controle de versão é o cerne de qualquer coisa que nós construímos. A versão do pacote NuGet refere-se para o pacote e não necessariamente os assemblies contidos dentro (embora seja costume de manter em sincronia, estas). Você define o número de versão do pacote na. arquivo de nuspec, com um formato de n.n.n. n, da seguinte forma.
<package>
<metadata>
<version>1.2.3.4</version>
</metadata>
</package>
Existem algumas propriedades na. arquivo de nuspec onde você pode usar um token de substituição em vez de apenas uma seqüência de caracteres estática. O elemento de versão é uma delas. Portanto, em vez de definir uma Cadeia de caracteres estática como 1.2.3.4, você pode inserir um token, [$$ versão], que mais tarde será substituído por NuGet.exe. Com esse token presente, a versão especificada no AssemblyVersionAttribute do assembly será executada por meio para o. arquivo nuspec:
<package>
<metadata>
<version>$version$</version>
</metadata>
</package>
Esta é uma ótima opção se você quiser manter os pacotes e versão em sincronia, apesar de existirem muitas razões por que você não pode optar por fazer isso.
O pacote de embalagem
Como mencionado anteriormente, um pacote de NuGet é um arquivo OPC com um. extensão de arquivo de nupkg. Para criar um pacote a partir da linha de comando você simplesmente chama NuGet.exe com o comando pack, passando-o. arquivo nuspec:
> NuGet.exe Pack YourPackage.
nuspec
Como spec, você pode executar pacote contra seu arquivo de projeto também. NuGet vai construir um pacote completo de NuGet (. arquivo nupkg) baseado unicamente em metadados encontrado dentro do arquivo. csproj ou. vbproj. Se você já tiver criado um. nuspec arquivo, pack usa que. arquivo nuspec:
> NuGet.exe pack [path]\MyProject.csproj
Você acabou de criar seu primeiro pacote NuGet, parabéns!
Suporte de símbolo
O Visual Studio tem uma grande característica que permite que a etapa de desenvolvedores por meio de código-fonte sob demanda. NuGet oferece suporte a isso, dando a autores de pacote a capacidade de criar e publicar um pacote de símbolo. Para criar um pacote de símbolo, use a opção de –symbols usando o pacote:
> NuGet.exe pack MyProject.
nuspec -symbols
> NuGet.exe pack MyProject.csproj –symbols
Pacote irá gerar dois. nupkg pacotes, MyProject. nupkg e MyProject.Symbols. nupkg. O .symbols. nupkg mais tarde pode ser empurrado para SymbolSource.org usando o comando NuGet.exe enviar. Para obter mais informações sobre como criar pacotes de símbolos com NuGet, consulte bit.ly/jqzry2.
Publicação em NuGet.org
Com seu pacote criado, é agora tempo para empurrá-lo. Push é o comando NuGet para publicar seu pacote para o servidor e ele é usado como mais modernos sistemas de controle de origem. Diferentemente dos comandos que eu mencionei anteriormente, push usa um número de argumentos:
> NuGet.exe push <package path> [API key] [options]
- Caminho do pacote o caminho para seu pacote
Exemplo c:\MyPackge\MyPackage.1.0. nupkg - O token de acesso exclusivo da chave API
Exemplo: ABFC2E12-40B3-41A1-A7CC-8FC9AB3A71E0
Opcional, pode ser definido usando o comando de setApiKey NuGet.exe - -fonte (src) O servidor onde o pacote está indo.
Exemplo: -http://packages de origem. nuget.org/V1/
Opcional, a menos que você está empurrando para um local alternativo - -CreateOnly (co) envia o pacote para Galeria mas não publica
Opcional, padrão = false
O comando de exemplo a seguir envia o pacote MyPackage para NuGet:
> NuGet.exe push MyPackage.1.0.
nupkg ABFC2E12-40B3-41A1-A7CC-8FC9AB3A71E0
Você também poderia usar NuGet Package Explorer, como mostrado na Figura 2.
.png)
Figura 2 publicação com o Explorador de pacotes NuGet
Se você criou um pacote de símbolo, NuGet automaticamente iria encontrá-lo e empurrá-lo para repositórios, nuget.org e symbolsource.org. Se o computador de destino estiver configurado para usar symbolsource.org como uma fonte de símbolo, o desenvolvedor pode agora entrar em seus arquivos de origem do pacote sob demanda de dentro do Visual Studio.
Você está publicado! Se esta é sua segunda versão de seu pacote, essa versão passará a ser agora a versão padrão. Conforme explicado no artigo do mês passado, quando alguém procura por atualizações de pacotes, seu pacote agora ser listado como um com uma atualização.
Resumindo
As chances são de que sua equipe de desenvolvimento tem algum tipo de construir e implantar o processo no lugar. Se você gosta de mim, você agora está começando a pensar em maneiras de integrar NuGet esse processo. Claramente você poderia quebrar todos os comandos que eu tenho mostrado aqui em seu processo de compilação, mas se você já estiver usando o Team Foundation Server (TFS), é uma maneira mais fácil.
TFS NuGetter (nugetter.codeplex.com) é um projeto open source que se estende do processo de compilação para 2010 TFS, realizando todas as funções necessárias de controle de versão, empacotamento e a implantação de uma forma personalizável e reproduzível, com NuGet em seu núcleo. Independentemente do destino do pacote, TFS NuGetter você vai economizar uma grande quantidade de tempo.
NuGet não é um conceito novo para a nossa indústria, mas para o.Desenvolvedor líquido bem parece inovador. NuGet fornece um recurso de gerenciamento pacote muito necessário, útil para todos de desenvolvedor de garagem para grandes empresas. Dá-lhe não só um lugar para publicar seus pacotes, mas também um lugar para os clientes a descobrir seu trabalho. Publicar seus pacotes para NuGet e obter encontrado!
Você pode encontrar todos os links usados no presente artigo e muito mais no on.csell.net/BeANuGetAuthor.
Clark Sell funciona como um divulgador sênior de Web para Microsoft fora de Chicago. Ele blogs em csell.net, podcasts no DeveloperSmackdown.com e pode ser encontrado no Twitter em twitter.com/csell5.
Graças aos seguintes especialistas técnicos para revisão deste artigo: David Ebbo, Phil Haack, Mark Nichols e Brandon Satrom