ASP.NET MVC e NuGet: Criando e utilizando um pacote em repositório local

Fabrício Sanchez

18/01/2011

Nesta semana a Microsoft anunciou a versão final do ASP.NET MVC 3, WebMatrix, IIS Express e o NuGet. Por isso, nestes últimos dias tenho escrito alguns artigos/tutoriais sobre estas tecnologias. Recentemente escrevi uma série de artigos abordando os principais conceitos relacionados ao WebMatrix e o ASP.NET Razor (nova view engine da Microsoft). Você pode acessar esta série de artigos clicando aqui. Seguindo esta tendência, escrevi também uma série introdutória sobre ASP.NET MVC, como pode ser visto aqui.

Hoje quero continuar a falar especificamente do NuGet (um poderoso gerenciador de dependências adicionado a versão 3 do ASP.NET MVC). Digo continuar porque já “bloguei” sobre este assunto há alguns dias, como pode ser visto aqui. Na verdade, neste último artigo apresentei os conceitos fundamentais relacionados ao NuGet e uma das formas possíveis de utilização com WebMatrix, através da instalação de um helper disponível em um feed oficial da Microsoft. Se você está chegando a este texto sem antes ter lido o artigo mencionado anteriormente, recomendo fortemente sua leitura antes de prosseguir com a deste texto.

No artigo de hoje, criaremos um novo helper (utilizando o Visual Studio 2010), encapsularemos este helper em um .nupkg (formato padrão de packages aceitos pelo NuGet), instalaremos o pacote e utilizaremos em uma aplicação ASP.NET MVC 3 com razor view engine.

Criando o Helper “InformacoesCreditosSite”

Para alcançar os objetivos deste artigo, vamos começar criando nosso helper e para isso, utilizaremos a versão final do WebMatrix. Se você não possui a ferramenta instalada, pode baixá-la gratuitamente aqui. Abra o WebMatrix e crie um projeto do tipo “Site from template > Empty site“. Nomeie o projeto conforme conveniência e clique em “OK”. A Figura 1 ilustra este processo.

Figura 1: Criando um projeto vazio no WebMatrix

A criação de helpers é extremamente simples, mas precisa seguir algumas pequenas regras. A seguir elas são listadas:

Pasta “App_Code”: por padrão os helpers precisam estar alojados na pasta “App_Code”, portanto, é necessário criá-la antes de criar o helper.
Obrigatoriedade de tag’s HTML: Quando for escrever o código helper, obrigatóriamente este deve estar encapsulado entre tag’s HTML. Quando apresentarmos o código do helper, este conceito ficará aparente.
Utilização da diretiva “@Helper“: para que um helper seja reconhecido pela framework é preciso que este tenha a diretiva “@Helper” antes de seu nome.

Para adicionar o diretório “App_Code” ao projeto, clique com o botão direito sobre o mesmo e selecione a opção “New folder“. Ao surgir a pasta na lista de arquivos, nomeie-a como “App_Code“. Em seguida, clique com o botão direito sobre a pasta “App_Code” e selecione a opção “New file“, conforme apresenta a Figura 2.

Figura 2: Selecionando o tipo de arquivo a ser criado e o nomeando

A Listagem 1 apresenta o código do nosso helper. A função de nosso helper é exibir as informações de créditos do site. Assim, sempre que precisarmos exibir tais informações, podemos lançar mão dele.

[html]
@{
Layout = null;
}

@helper InformacoesCreditosSite()
{

© @DateTime.Now.Year – Todos os direitos reservados – Desenvolvido por:
<a href=”https://fabriciosanchez.com.br//” target=”_blank”>Fabrício Sanchez</a>

}
[/html]

Listagem 1: Helper que exibe os créditos do site

O código é extremamente simples como você pode notar. Vale notar que um helper pode ter n métodos, portanto, o nome de nosso helper não é “InformacoesCreditosSite” e sim “HelpersEstaticos”, conforme ilustra a Figura 2.

Regras para criação e configuração de um pacote NuGet

Para que o NuGet possa aceitar um package algumas regras devem ser seguidas. Abaixo apresentamos todas elas de forma detalhada:

Instalar NuGet.exe: Para gerar um pacote NuGet é preciso baixar e instalar o Nuget Command Line Tool. Você pode efetuar o download desta ferramenta clicando aqui. Esta ferramenta é a responsável por encapsular os arquivos e diretórios da biblioteca que se deseja disponibilizar.
Respeitar a estrutura de diretórios:para que um pacote possa ser gerado corretamente, é preciso que se respeite a estrutura de diretórios da ferramenta. A estrutura deve ser como segue:
- O único arquivo a estar na base é o .nuspec. Todos os demais devem estar em subdiretórios de forma recursiva ao arquivo de manifesto (.nuspec, vamos falar dele daqui a pouco);
- O pacote consiste de três tipos de arquivos: “tools“, “assemblies” e “content“. O diretório “tools” tem o objetivo de referenciar aplicações que por ventura o pacote precise acessar via linha de comando. Esta referência é realizada via “$env:Path (PATH)“. Já a pasta “assemblies” aloja .dll’s a serem instaladas pelo NuGet. Finalmente, a pasta “content” aloja demais arquivos do pacote.
- Finalmente, temos o chamado “arquivo de manifesto”. Este é um arquivo construído no formato XML mas que possui a extensão .nuspec. Como mencionado anteriormente, ele deve encontrar-se obrigatóriamente na raíz do pacote. Este arquivo contém toda a especificação do pacote, como será visto na estrutura do mesmo apresentada pela Listagem 2. No momento que a instalação do pacote é solicitada, o NuGet busca em primeira instância este arquivo para obter as informações de que precisa para continuar com a instalação.

Agora que conhecemos as regras para criarmos nosso pacote, vamos então a criação de fato. O primeiro passo consiste na criação do diretório que será encapsulado pelo NuGet.exe. Você pode criar o diretório com o nome que achar mais interessante. No meu caso, criei o diretório “Fabricio.Package.Nuget” em “D:”. Agora, vamos criar nosso arquivo de manifesto. Como este arquivo possui uma estrutura XML simples, você pode utilizar qualquer editor de textos para o codificar. Como já estamos com o WebMatrix em execução, o utilizaremos para realizar esta operação.

[xml]
<?xml version=”1.0″?>
<package xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xmlns:xsd=”http://www.w3.org/2001/XMLSchema”>
<metadata xmlns=”http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd”>
<id>HelpersEstaticos.Nuget</id>
<version>4.0</version>
<authors>Fabrício Sanchez</authors>
<description>Helper que exibe os créditos dos sites desenvolvidos por Fabrício Sanchez.</description>
<summary>Helper para exibir créditos do site.</summary>
<language>pt-BR</language>
<licenseUrl>http://fabriciosanchez.codeplex.com/license</licenseUrl>
<projectUrl>http://fabriciosanchez.codeplex.com</projectUrl>
</metadata>
<files>
<file src=”content*.cshtml” target=”contentApp_Code” />
</files>
</package>
[/xml]

Listagem 2: A estrutura do arquivo nuspec

Após adicionar o código da Listagem 2 no arquivo XML, salve-o com o nome que achar mais conveniente na raíz do diretório que acabamos de criar, ou seja, “D:Fabricio.Package.Nuget“. No meu caso, chamei de “HelpersEstaticos.Nuget.nuspec”. Novamente é importante notar que, muito embora a estrutura do arquivo seja construída em XML, sua extensão é “.nuspec” correto?

Como mencionado anteriormente, a estrutura do arquivo de manifesto é extremamente simples. O que vale destacar na estrutura acima é a linha 14. Esta linha é especialmente importante no caso dos helpers, pois, para que os helpers funcionem no contexto de uma aplicação ASP.NET MVC é pré-requisito que ele esteja alojado na pasta “App_Code” e a linha 14, “diz” ao NuGet que o conteúdo da pasta “content” deve ser instalado na pasta “App_Code” do projeto. Caso a pasta “App_Code” ainda não exista, o NuGet criará a pasta para alojar o helper.

Instalando o NuGet Command Line Tool

A instalação do NuGet Command Line Tool é extremamente simples, pois, basta efetuar o download da mesma e hospedá-la no diretório que achar mais conveniente. Assim, baixe a ferramenta na página do projeto no Codeplex. Em meu caso, ela se encontra em “D:NuGet.exe“. Pronto, NuGet Command Line Tool instalado.

Criando o pacote Nuget (.nupkg)

Antes de criarmos nosso pacote .nupkg, precisamos adicionar o helper que criamos ao diretório específico do pacote. Assim, dentro de “Fabricio.Package.Nuget” crie um novo diretório chamado “content” e adicione o arquivo “HelpersEstaticos.cshtml” que criamos no WebMatrix a ele (via ctrl+c > ctrl+v mesmo :-)).

Pronto, agora estamos preparados para criação do pacote de fato. Abra o console de seu computador (você pode realizar esta operação digitando “cmd” em “Iniciar > Executar”). Navegue até a pasta onde se encontra o NuGet.exe e lá digite a seguinte linha de comando:

NuGet.exe pack caminho_arquivo_manifesto.nuspec

No meu caso, o caminho ficou da seguinte forma:

NuGet pack D:Fabricio.Package.NugetHelpersEstaticos.Nuget.nuspec

Ao pressionar “enter“, se tudo foi realizado corretamente, você deverá estar visualizando uma mensagem semelhante aquela apresentada pela Figura 3.

Figura 3: Pacote criado com sucesso

Navegue até sua estrutura de diretórios onde se encontra o diretório do pacote e você verá que um novo arquivo com a extensão .nupkg foi criado com o mesmo nome do arquivo de manifesto. Pronto, agora o pacote está pronto para ser utilizado em nossos projetos ASP.NET MVC através do NuGet. A Figura 4 apresenta o novo arquivo criado.

Figura 4: Pacote criado no mesmo nível de diretório de Fabricio.Package.NuGet

Utilizando o pacote criado em um projeto ASP.NET MVC 3

Vamos então aos testes. O que faremos é criar um novo projeto ASP.NET MVC 3 utilizando Razor view engine, adicionaremos um repositório local com o Visual Studio e, em seguida, instalaremos o pacote recém criado via NuGet. Por fim, utilizaremos o este helper em nossa aplicação.

Assim, crie um novo projeto do tipo ASP.NET MVC 3. Ao criar um projeto uma nova janela será apresentada. Nesta janela temos a opção de escolher a view engine que iremos utilizar em nossa aplicação. Note que por default, a opção Razor vem selecionada. Manteremos o razor e “diremos” que não queremos criar um projeto de testes unitários. A Figura 4 ilustra este procedimento.

Figura 4: Criando e configurando o projeto ASP.MVC 3

Muito bem, nosso projeto está devidamente criado e configurado. O que faremos primeiro é adicionar o repositório. Para isso, basta ir a “Tools > Options“. Na janela que se abre, selecione a guia “Package Manager“, dê um nome ao repositório e indique o caminho do mesmo. A Figura 5 ilustra este procedimento. Vale notar que o repositório é um ambiente no qual o NuGet buscará os pacotes a serem instalados em sua aplicação. Este repositório pode ser online ou local.

Figura 5: Adicionando o repositório local “Helpers Estáticos”

A seguir, utilizaremos o NuGet para que ele nos apresente todos os pacotes disponíveis para instalação no repositório que acabamos de adicionar. Vamos realizar esta tarefa via “Tools > Library Package Manager > Package Manager Console“. Na janela que se apresenta, no drop down list “Package source” selecione o repositório que acabamos de adicionar, ou seja, “Helpers Estáticos”. Na linha de comandos, digite o seguinte:

List-Package -Source D:

Com esta informação, o NuGet “olhará” para o repositório informado e exibirá todos os pacotes disponíveis para instalação. A Figura 6 apresenta o resultado desta digitação.

Figura 6: Pacotes disponíveis para instalação

Muito bem, o que faremos agora é instalar este pacote disponível. Para isso, na linha de comandos abaixo, digite a seguinte instrução:

Install-Package HelpersEstaticos.Nuget

O comando “Install-Package” como o próprio nome sugere, instalará o pacote ao qual você aponta em sua aplicação sem causar qualquer tipo de conflito com as demais bibliotecas e ferramentas já instaladas. O resultado da digitação deste comando pode ser visualizado na Figura 7.

Figura 7: Pacote instalado com sucesso

Note do lado direito que uma pasta “App_Code” foi adicionada ao projeto e, dentro dela, um arquivo com a extensão .cshtml chamado “HelpersEstaticos”, ou seja, o helper que criamos com o WebMatrix.

Finalmente, nos resta testar e verificar se o helper funciona corretamente. Para isso, vá até a Solution Explorer do projeto, na pasta “Views” e expanda a pasta “Home“. Em seguida, dê um duplo clique no arquivo “Index.cshtml” e em seu conteúdo, informe o trecho de código apresentado pela Listagem 3.

[html]

Testando o Helper criado e instalado:

@HelpersEstaticos.InformacoesCreditosSite()

[/html]

Listagem 3: Testando o helper recém instalado

Note na linha 6 que estamos apenas chamando o helper “HelpersEstaticos” cuja função específica é exibir “InformacoesCreditosSite”. Ao executar o projeto, se tudo foi realizado da forma correta, você deverá estar visualizando algo semelhante ao apresentado pela Figura 8.

Figura 8: Helper em perfeito funcionamento

Bom pessoal, por hora é isso. Continue acompanhando o site que em breve teremos novos artigos sobre NuGet. O próximo assunto a ser tratado será: como atualizar pacotes em nosso projeto com NuGet. Não perca!

Não se esqueça de deixar seu comentário. Ele é a única forma que possuímos de melhorar a qualidade dos textos. Seu feedback é extremamente importante para nós!