Incluindo um pacote NuGet no projetoIncluding a NuGet package in your project

O NuGet é o gerenciador de pacotes mais popular para desenvolvimento .NET e é interno no Visual Studio para Mac e no Visual Studio no Windows.NuGet is the most popular package manager for .NET development and is built in to Visual Studio for Mac and Visual Studio on Windows. Você pode pesquisar e adicionar pacotes aos seus projetos Xamarin.iOS e Xamarin.Android usando um dos IDE.You can search for and add packages to your Xamarin.iOS and Xamarin.Android projects using either IDE.

Este documento explica como incluir um pacote NuGet em um projeto e demonstra a cadeia de ferramenta que facilita tal processo.This document looks at how to include a NuGet package in a project and demonstrates the tool chain that makes the process seamless.

NuGet no Visual Studio para MacNuGet in Visual Studio for Mac

Para demonstrar a funcionalidade do pacote NuGet, vejamos primeiro como criar um novo aplicativo e adicionar um pacote a ele.To demonstrate the NuGet package functionality we'll first walk through creating a new application and adding a package to it. Em seguida, abordaremos os recursos do IDE que ajudam a gerenciar pacotes.Then we'll discuss the IDE features that help manage packages.

Criar um novo projetoCreate a new project

Primeiro, crie um projeto chamado HelloNuget conforme ilustrado abaixo.First, create a project named HelloNuget as illustrated below. Este exemplo mostra o modelo de Aplicativo de exibição única do iOS, mas funcionaria com qualquer tipo de projeto compatível:This example shows the iOS Single View Application template, but any supported project type would work:

Criar novo projeto do iOS

Adicionar um pacoteAdding a Package

Com o projeto aberto no Visual Studio para Mac, clique com o botão direito do mouse na pasta Pacotes no Painel de Soluções e selecione Adicionar pacotes...:With the project open in Visual Studio for Mac, right-click on the Packages folder in the Solution Pad and select Add Packages...:

Ação de contexto Adicionar novo pacote NuGet

Isso abre a janela Adicionar pacotes....This launches the Add Packages... window. Verifique se a lista suspensa Origem está definida como nuget.org:Ensure that the Source drop-down, is set to nuget.org:

Lista suspensa Origem

Quando a janela for aberta, ela carregará uma lista de pacotes da origem padrão de pacotes: nuget.org. Os primeiros resultados serão semelhantes a estes:When the window opens it will load a list of packages from the default package source: nuget.org. The initial results look like this:

Listar pacotes NuGet

Use a caixa de pesquisa no canto superior direito para localizar um pacote específico, como por exemplo azure.Use the search box in the top-right corner to find a specific package, for example azure. Quando você encontrar um pacote que deseja usar, selecione-o e clique no botão Adicionar pacote para iniciar a instalação.When you've found a package that you wish to use, select it and click the Add Package button to begin installation.

Adicionar o pacote Azure NuGetAdd Azure NuGet Package

Depois que o pacote for baixado, ele será adicionado ao seu projeto.Once the package has been downloaded it will be added to your project. A solução mudará da seguinte maneira:The solution will change as follows:

  • O nó Referências conterá uma lista de todos os assemblies que fazem parte de um pacote NuGet.The References node will contain a list of all the assemblies that are part of a NuGet package.
  • O nó Pacotes exibe cada pacote NuGet que você baixou.The Packages node displays each NuGet package that you have downloaded. Você pode atualizar ou remover um pacote da lista.You can update or remove a package from this list.
  • Um arquivo packages.config será adicionado ao projeto.A packages.config file will be added to the project. Esse arquivo XML é usado pelo IDE para controlar quais versões do pacote são referenciada neste projeto.This XML file is used by the IDE to track which package versions are referenced in this project. Esse arquivo não deve ser editado manualmente e deve ser mantido no controle de versão.This file should not be hand-edited, but you should keep it in version control. Observe que é possível usar um arquivo project.json em vez de um arquivo packages.config.Note that a project.json file can be used instead of a packages.config file. O arquivo project.json é um formato de arquivo de pacote novo introduzido com o NuGet 3, que dá suporte à restauração transitiva.The project.json file is a new package file format introduced with NuGet 3, which supports transitive restore. Informações mais detalhadas sobre o project.json podem ser encontradas na Documentação do NuGet.More detailed information on project.json can be found in the NuGet documentation. O arquivo project.json precisa ser adicionado manualmente e o projeto fechado e reaberto para que o arquivo possa ser usado no Visual Studio para Mac.The project.json file needs to be added manually and the project closed and re-opened before the project.json file is used in Visual Studio for Mac.

Usando pacotes NuGetUsing NuGet Packages

Depois que o pacote NuGet foi adicionado e as referências de projeto foram atualizadas, você pode programar as APIs como faria com qualquer referência de projeto.Once the NuGet package has been added and the project references updated you can program against the APIs as you would with any project reference.

Verifique se você adicionou as diretivas using necessárias na parte superior do arquivo:Ensure that you add any required using directives to the top of your file:

using Newtonsoft.Json;

A maioria dos NuGet fornecem informações adicionais, como um LEIAME ou um link da página do Projeto para a fonte do Nuget.Most NuGet provide additional information, such as a README or Project page link to the Nuget source. Normalmente, um link para isso é encontrado na sinopse do pacote na página Adicionar pacotes:You can normally find a link to this in the package blurb on the Add Packages page:

Link Exibir de página do projetoView Project Page link

Atualizações de PacotePackage Updates

As atualizações de pacote podem ser feitas ao mesmo tempo, clicando com o botão direito do mouse no nó Pacotes ou individualmente em cada componente.Package updates can be done either all at once, by right-clicking on the Packages node, or individually on each component.

Clique com o botão direito do mouse em Pacotes para acessar o menu de contexto:Right-click on Packages to access the context menu:

Menu Pacotes

  • Adicionar pacotes –Abre a janela para adicionar mais pacotes ao projeto.Add Packages - Opens the window to add more packages to the project.
  • Atualizar – Verifica o servidor de origem de cada pacote e baixa as versões mais recentes.Update - Checks the source server for each package and downloads any newer versions.
  • Restaurar – Baixa todos os pacotes ausentes (sem atualizar os pacotes existentes para as versões mais recentes).Restore - Downloads any missing packages (without updating existing packages to newer versions).

As opções Atualizar e Restaurar também estão disponíveis no nível da Solução, afetando todos os projetos na solução.Update and Restore options are also available at the Solution level, and affect all the projects in the solution.

Também é possível clicar com o botão direito do mouse em pacotes individuais para acessar um menu de contexto:You can also right-click on individual packages to access a context menu:

Menu Pacotes

  • Número de versão – O número de versão é um item de menu desabilitado, sendo informado apenas para fins informativos.Version Number - The version number is a disabled menu item - it is provided for informational purposes only.
  • Atualizar – Verifica o servidor de origem e baixa uma versão mais recente (se houver).Update - Checks the source server and downloads a newer version (if it exists).
  • Remover – Remove o pacote desse projeto e os assemblies relevantes das Referências do projeto.Remove - Removes the package from this project and removes the relevant assemblies from the project's References.

Adicionando origens de pacotesAdding Package Sources

Os pacotes disponíveis para instalação são recuperados inicialmente de nuget.org. No entanto, você pode adicionar outros locais de pacotes para o Visual Studio para Mac.Packages available for installation are initially retrieved from nuget.org. However, you can add other package locations to Visual Studio for Mac. Isso pode ser útil para testar seus próprios pacotes NuGet em desenvolvimento ou para usar um servidor NuGet privado dentro de sua empresa ou organização.This can be useful for testing your own NuGet packages under development, or to use a private NuGet server inside your company or organization.

No Visual Studio para Mac, navegue para Visual Studio > Preferências... > NuGet > Origens para exibir e editar a lista de origens de pacotes.In Visual Studio for Mac, navigate to Visual Studio > Preferences... > NuGet > Sources to view and edit the list of package sources. Observe que as origens podem ser um servidor remoto (especificado por uma URL) ou um diretório local.Note that sources can be a remote server (specified by a URL) or a local directory.

Origens dos pacotes

Clique em Adicionar para configurar uma nova origem.Click Add to set-up a new source. Insira um nome amigável e a URL (ou caminho de arquivo) para a origem do pacote.Enter a friendly name and the URL (or file path) to the package source. Se a origem for um servidor Web seguro, insira também o nome de usuário e a senha, caso contrário, deixe essas entradas em branco:If the source is a secure web server, enter the username and password as well, otherwise leave these entries blank:

Adicionar origens de pacotes

É possível selecionar diferentes origens ao procurar pacotes:Different sources can then be selected when searching for packages:

Adicionar origens de pacotes

Controle de versãoVersion Control

A documentação do NuGet aborda como usar NuGet sem confirmar pacotes no controle do código-fonte.The NuGet documentation discusses using NuGet without committing packages to source control. Se você preferir não armazenar binários e informações não utilizadas no controle do código-fonte, configure o Visual Studio para Mac para restaurar automaticamente os pacotes do servidor.If you prefer not to store binaries and unused information in source control, you can configure the Visual Studio for Mac to automatically restore packages from the server. Isso significa que, quando um desenvolvedor recuperar o projeto do controle do código-fonte pela primeira vez, o Visual Studio para Mac baixará e instalará os pacotes necessários automaticamente.This means that when a developer retrieves the project from source control for the first time, the Visual Studio for Mac will automatically download and install the required packages.

Restaurar os pacotes automaticamente

Consulte a documentação do controle do código-fonte específico para ver detalhes sobre como excluir o diretório packages do rastreamento.Refer to your particular source control documentation for details on how to exclude the packages directory from being tracked.