Cliente RESTREST client

Este tutorial ensina vários recursos no .NET Core e da linguagem C#.This tutorial teaches you a number of features in .NET Core and the C# language. Você aprenderá:You’ll learn:

  • As noções básicas do CLI do .NET Core.The basics of the .NET Core CLI.
  • Uma visão geral dos recursos da linguagem C#.An overview of C# Language features.
  • Gerenciamento de dependências com o NuGetManaging dependencies with NuGet
  • Comunicações HTTPHTTP Communications
  • Processamento de informações de JSONProcessing JSON information
  • Gerenciamento de configuração com Atributos.Managing configuration with Attributes.

Você compilará um aplicativo que emite solicitações HTTP para um serviço REST no GitHub.You’ll build an application that issues HTTP Requests to a REST service on GitHub. Você lerá informações no formato JSON e converterá esse pacote JSON em objetos C#.You'll read information in JSON format, and convert that JSON packet into C# objects. Por fim, você verá como trabalhar com objetos C#.Finally, you'll see how to work with C# objects.

Há muitos recursos neste tutorial.There are many features in this tutorial. Vamos compilá-los individualmente.Let’s build them one by one.

Se preferir acompanhar com o exemplo final para esse tópico, você poderá baixá-lo.If you prefer to follow along with the final sample for this topic, you can download it. Para obter instruções de download, consulte Exemplos e tutoriais.For download instructions, see Samples and Tutorials.

Pré-requisitosPrerequisites

Você precisará configurar seu computador para executar o .NET Core.You’ll need to set up your machine to run .NET core. Você pode encontrar as instruções de instalação na página de downloads do .NET Core .You can find the installation instructions on the .NET Core Downloads page. Execute esse aplicativo no Windows, Linux, macOS ou em um contêiner do Docker.You can run this application on Windows, Linux, macOS or in a Docker container. Será necessário instalar o editor de código de sua preferência.You’ll need to install your favorite code editor. As descrições a seguir usam o Visual Studio Code, que é uma software livre, no editor de plataforma.The descriptions below use Visual Studio Code, which is an open source, cross platform editor. No entanto, você pode usar quaisquer ferramentas que esteja familiarizado.However, you can use whatever tools you are comfortable with.

Criar o aplicativoCreate the Application

A primeira etapa é criar um novo aplicativo.The first step is to create a new application. Abra um prompt de comando e crie um novo diretório para seu aplicativo.Open a command prompt and create a new directory for your application. Torne ele o diretório atual.Make that the current directory. Digite o seguinte comando em uma janela de console:Enter the following command in a console window:

dotnet new console --name WebAPIClient

Isso cria os arquivos iniciais de um aplicativo "Olá, Mundo" básico.This creates the starter files for a basic "Hello World" application. O nome do projeto é "WebAPIClient".The project name is "WebAPIClient". Como esse é um novo projeto, nenhuma das dependências está em vigor.As this is a new project, none of the dependencies are in place. A primeira execução baixará o .NET Core Framework, instalará um certificado de desenvolvimento e executará o Gerenciador de pacotes NuGet para restaurar as dependências ausentes.The first run will download the .NET Core framework, install a development certificate, and run the NuGet package manager to restore missing dependencies.

Antes de começar a fazer modificações, digite dotnet run (veja a observação) no prompt de comando para executar seu aplicativo.Before you start making modifications, type dotnet run (see note) at the command prompt to run your application. dotnet run executará automaticamente dotnet restore se estiverem faltando dependências em seu ambiente.dotnet run automatically performs dotnet restore if your environment is missing dependencies. Ele também executará dotnet build se seu aplicativo precisar ser reconstruído.It also performs dotnet build if your application needs to be rebuilt. Após sua configuração inicial, você só precisará executar dotnet restore ou dotnet build quando fizer sentido para seu projeto.After your initial setup, you will only need to run dotnet restore or dotnet build when it makes sense for your project.

Adicionar novas dependênciasAdding New Dependencies

Uma das principais metas de design para o .NET Core é minimizar o tamanho da instalação do .NET.One of the key design goals for .NET Core is to minimize the size of the .NET installation. Se um aplicativo precisar de mais bibliotecas para alguns de seus recursos, adicione essas dependências ao seu arquivo de projeto de C# (*.csproj).If an application needs additional libraries for some of its features, you add those dependencies into your C# project (*.csproj) file. Para nosso exemplo, você precisará adicionar o System.Runtime.Serialization.Json pacote, para que seu aplicativo possa processar respostas JSON.For our example, you'll need to add the System.Runtime.Serialization.Json package, so your application can process JSON responses.

Você precisará do System.Runtime.Serialization.Json pacote para este aplicativo.You'll need the System.Runtime.Serialization.Json package for this application. Adicione-o ao seu projeto executando o seguinte comando da CLI do .net :Add it to your project by running the following .NET CLI command:

dotnet add package System.Text.Json

Como fazer solicitações da WebMaking Web Requests

Agora você está pronto para começar a obter dados da Web.Now you're ready to start retrieving data from the web. Neste aplicativo, você lerá informações da API do GitHub.In this application, you'll read information from the GitHub API. Vamos ler informações sobre os projetos em .NET Foundation.Let's read information about the projects under the .NET Foundation umbrella. Comece fazendo a solicitação à API do GitHub para recuperar informações sobre os projetos.You'll start by making the request to the GitHub API to retrieve information on the projects. O ponto de extremidade que você usará é: https://api.github.com/orgs/dotnet/repos.The endpoint you'll use is: https://api.github.com/orgs/dotnet/repos. Você quer obter todas as informações sobre esses projetos, portanto, use uma solicitação HTTP GET.You want to retrieve all the information about these projects, so you'll use an HTTP GET request. O navegador também usa solicitações HTTP GET, para que você possa colar essa URL em seu navegador e ver as informações que receberá.Your browser also uses HTTP GET requests, so you can paste that URL into your browser to see what information you'll be receiving and processing.

Use a classe HttpClient para fazer solicitações da Web.You use the HttpClient class to make web requests. Como todas as APIs .NET modernas, a HttpClient oferece suporte apenas aos métodos assíncronos para suas APIs de longa execução.Like all modern .NET APIs, HttpClient supports only async methods for its long-running APIs. Comece criando um método assíncrono.Start by making an async method. Você preencherá a implementação à medida que compila a funcionalidade do aplicativo.You'll fill in the implementation as you build the functionality of the application. Comece abrindo o arquivo program.cs no diretório do projeto e adicionando o seguinte método à classe Program:Start by opening the program.cs file in your project directory and adding the following method to the Program class:

private static async Task ProcessRepositories()
{
}

Você precisará adicionar uma using diretiva na parte superior do seu Main método para que o compilador C# reconheça o Task tipo:You'll need to add a using directive at the top of your Main method so that the C# compiler recognizes the Task type:

using System.Threading.Tasks;

Se você compilar o projeto neste momento, receberá um aviso gerado para esse método, pois ele não contém operadores await e executará de forma síncrona.If you build your project at this point, you'll get a warning generated for this method, because it does not contain any await operators and will run synchronously. Ignore isso por enquanto. Adicione os operadores await à medida que você preenche o método.Ignore that for now; you'll add await operators as you fill in the method.

Em seguida, atualize o Main método para chamar o ProcessRepositories método.Next, update the Main method to call the ProcessRepositories method. O ProcessRepositories método retorna uma tarefa e você não deve sair do programa antes que essa tarefa seja concluída.The ProcessRepositories method returns a task, and you shouldn't exit the program before that task finishes. Portanto, você deve alterar a assinatura de Main .Therefore, you must change the signature of Main. Adicione o async modificador e altere o tipo de retorno para Task .Add the async modifier, and change the return type to Task. Em seguida, no corpo do método, adicione uma chamada para ProcessRepositories .Then, in the body of the method, add a call to ProcessRepositories. Adicione a await palavra-chave a essa chamada de método:Add the await keyword to that method call:

static async Task Main(string[] args)
{
    await ProcessRepositories();
}

Agora, você tem um programa que não faz nada, mas o faz de forma assíncrona.Now, you have a program that does nothing, but does it asynchronously. Vamos melhorar isso.Let's improve it.

Primeiro você precisa de um objeto que é capaz de recuperar dados da Web; você pode usar um HttpClient para fazer isso.First you need an object that is capable to retrieve data from the web; you can use a HttpClient to do that. Esse objeto manipula a solicitação e as respostas.This object handles the request and the responses. Crie uma instância única desse tipo na Program classe dentro do arquivo Program.cs .Instantiate a single instance of that type in the Program class inside the Program.cs file.

namespace WebAPIClient
{
    class Program
    {
        private static readonly HttpClient client = new HttpClient();

        static async Task Main(string[] args)
        {
            //...
        }
    }
}

Vamos voltar ao método ProcessRepositories e preencher uma primeira versão dele:Let's go back to the ProcessRepositories method and fill in a first version of it:

private static async Task ProcessRepositories()
{
    client.DefaultRequestHeaders.Accept.Clear();
    client.DefaultRequestHeaders.Accept.Add(
        new MediaTypeWithQualityHeaderValue("application/vnd.github.v3+json"));
    client.DefaultRequestHeaders.Add("User-Agent", ".NET Foundation Repository Reporter");

    var stringTask = client.GetStringAsync("https://api.github.com/orgs/dotnet/repos");

    var msg = await stringTask;
    Console.Write(msg);
}

Você também precisará adicionar duas novas using diretivas na parte superior do arquivo para que isso seja compilado:You'll need to also add two new using directives at the top of the file for this to compile:

using System.Net.Http;
using System.Net.Http.Headers;

A primeira versão faz uma solicitação da Web para ler a lista de todos os repositórios na organização dotnet foundation.This first version makes a web request to read the list of all repositories under the dotnet foundation organization. (A ID do gitHub para o .NET Foundation é 'dotnet').(The gitHub ID for the .NET Foundation is 'dotnet'). As primeiras linhas configuram o HttpClient para essa solicitação.The first few lines set up the HttpClient for this request. Primeiro, ele é configurado para aceitar as respostas JSON do GitHub.First, it is configured to accept the GitHub JSON responses. Esse formato é simplesmente JSON.This format is simply JSON. A próxima linha adiciona um cabeçalho de agente do usuário para todas as solicitações deste objeto.The next line adds a User Agent header to all requests from this object. Esses dois cabeçalhos são verificados pelo código do servidor GitHub e são necessários para recuperar informações do GitHub.These two headers are checked by the GitHub server code, and are necessary to retrieve information from GitHub.

Depois de configurar o HttpClient, faça uma solicitação da Web e recupere a resposta.After you've configured the HttpClient, you make a web request and retrieve the response. Nesta primeira versão, você usa o método de conveniência HttpClient.GetStringAsync(String).In this first version, you use the HttpClient.GetStringAsync(String) convenience method. Este método prático inicia uma tarefa que faz a solicitação da Web e, depois, quando a solicitação retornar, ele lê o fluxo de resposta e extrai o conteúdo do fluxo.This convenience method starts a task that makes the web request, and then when the request returns, it reads the response stream and extracts the content from the stream. O corpo da resposta retorna como um String.The body of the response is returned as a String. A cadeia de caracteres fica disponível após a conclusão da tarefa.The string is available when the task completes.

As duas últimas linhas desse método aguardam a tarefa e, depois, imprimem a resposta no console.The final two lines of this method await that task, and then print the response to the console. Compilar o aplicativo e executá-lo.Build the app, and run it. O aviso de compilação desapareceu, pois agora o ProcessRepositories contêm um operador await.The build warning is gone now, because the ProcessRepositories now does contain an await operator. Você verá uma longa exibição do texto formatado em JSON.You'll see a long display of JSON formatted text.

Processar o resultado JSONProcessing the JSON Result

Neste ponto, você já escreveu o código para recuperar uma resposta de um servidor da Web e exibiu o texto contido nessa resposta.At this point, you've written the code to retrieve a response from a web server, and display the text that is contained in that response. Agora, vamos converter essa resposta em JSON em objetos de C#.Next, let's convert that JSON response into C# objects.

A System.Text.Json.JsonSerializer classe serializa objetos para JSON e DESSERIALIZA JSON em objetos.The System.Text.Json.JsonSerializer class serializes objects to JSON and deserializes JSON into objects. Comece definindo uma classe para representar o repo objeto JSON retornado da API do github:Start by defining a class to represent the repo JSON object returned from the GitHub API:

using System;

namespace WebAPIClient
{
    public class Repository
    {
        public string name { get; set; }
    }
}

Coloque o código acima em um novo arquivo chamado 'repo.cs'.Put the above code in a new file called 'repo.cs'. Esta versão da classe representa o caminho mais simples para processar os dados em JSON.This version of the class represents the simplest path to process JSON data. O nome da classe e o nome do membro corresponderem aos nomes usados no pacote JSON, em vez de seguir as convenções em C#.The class name and the member name match the names used in the JSON packet, instead of following C# conventions. Corrija isso mais tarde fornecendo alguns atributos de configuração.You'll fix that by providing some configuration attributes later. Essa classe demonstra outro recurso importante de serialização e desserialização em JSON: nem todos os campos no pacote JSON fazem parte dessa classe.This class demonstrates another important feature of JSON serialization and deserialization: Not all the fields in the JSON packet are part of this class. O serializador JSON ignorará as informações que não estão incluídas no tipo de classe que está sendo usado.The JSON serializer will ignore information that is not included in the class type being used. Esse recurso facilita a criação de tipos que funcionam apenas com um subconjunto dos campos no pacote JSON.This feature makes it easier to create types that work with only a subset of the fields in the JSON packet.

Agora que você criou o tipo, vamos desserializá-lo.Now that you've created the type, let's deserialize it.

Em seguida, você usará o serializador para converter JSON em objetos de C#.Next, you'll use the serializer to convert JSON into C# objects. Substitua a chamada para GetStringAsync(String) no seu ProcessRepositories método pelas seguintes linhas:Replace the call to GetStringAsync(String) in your ProcessRepositories method with the following lines:

var streamTask = client.GetStreamAsync("https://api.github.com/orgs/dotnet/repos");
var repositories = await JsonSerializer.DeserializeAsync<List<Repository>>(await streamTask);

Você está usando novos namespaces, portanto, você precisará adicioná-lo na parte superior do arquivo também:You're using new namespaces, so you'll need to add it at the top of the file as well:

using System.Collections.Generic;
using System.Text.Json;

Observe que agora você está usando GetStreamAsync(String) em vez de GetStringAsync(String).Notice that you're now using GetStreamAsync(String) instead of GetStringAsync(String). O serializador usa um fluxo, em vez de uma cadeia de caracteres, como sua fonte.The serializer uses a stream instead of a string as its source. Vamos explicar alguns recursos da linguagem C# que estão sendo usados na segunda linha do trecho de código anterior.Let's explain a couple features of the C# language that are being used in the second line of the preceding code snippet. O primeiro argumento para JsonSerializer.DeserializeAsync<TValue>(Stream, JsonSerializerOptions, CancellationToken) é uma await expressão.The first argument to JsonSerializer.DeserializeAsync<TValue>(Stream, JsonSerializerOptions, CancellationToken) is an await expression. (Os outros dois parâmetros são opcionais e são omitidos no trecho de código.) As expressões Await podem aparecer quase em qualquer lugar no seu código, embora até agora você as tenha visto apenas como parte de uma instrução de atribuição.(The other two parameters are optional and are omitted in the code snippet.) Await expressions can appear almost anywhere in your code, even though up to now, you've only seen them as part of an assignment statement. O Deserialize método é genérico, o que significa que você deve fornecer argumentos de tipo para o tipo de objeto que deve ser criado a partir do texto JSON.The Deserialize method is generic, which means you must supply type arguments for what kind of objects should be created from the JSON text. Neste exemplo, você está desserializando para um List<Repository> , que é outro objeto genérico, o System.Collections.Generic.List<T> .In this example, you're deserializing to a List<Repository>, which is another generic object, the System.Collections.Generic.List<T>. A List<> classe armazena uma coleção de objetos.The List<> class stores a collection of objects. O argumento Type declara o tipo de objetos armazenados no List<> .The type argument declares the type of objects stored in the List<>. O texto JSON representa uma coleção de objetos de repositório, portanto, o argumento de tipo é Repository .The JSON text represents a collection of repo objects, so the type argument is Repository.

Você está quase terminando esta seção.You're almost done with this section. Agora que você converteu o JSON em objetos C#, vamos exibir o nome de cada repositório.Now that you've converted the JSON to C# objects, let's display the name of each repository. Substitua as linhas que mostram:Replace the lines that read:

var msg = await stringTask;   //**Deleted this
Console.Write(msg);

pelo seguinte:with the following:

foreach (var repo in repositories)
    Console.WriteLine(repo.name);

Compile e execute o aplicativo.Compile and run the application. Ele imprimirá os nomes dos repositórios que fazem parte do .NET Foundation.It will print out the names of the repositories that are part of the .NET Foundation.

Controle da serializaçãoControlling Serialization

Antes de adicionar mais recursos, vamos abordar a name propriedade usando o [JsonPropertyName] atributo.Before you add more features, let's address the name property by using the [JsonPropertyName] attribute. Faça as seguintes alterações na declaração do campo name em repo.cs:Make the following changes to the declaration of the name field in repo.cs:

[JsonPropertyName("name")]
public string Name { get; set; }

Para usar o [JsonPropertyName] atributo, será necessário adicionar o System.Text.Json.Serialization namespace às using diretivas:To use [JsonPropertyName] attribute, you will need to add the System.Text.Json.Serialization namespace to the using directives:

using System.Text.Json.Serialization;

Essa alteração significa que você precisa alterar o código que grava o nome de cada repositório em program.cs:This change means you need to change the code that writes the name of each repository in program.cs:

Console.WriteLine(repo.Name);

Execute dotnet run para certificar-se de que você tem os mapeamentos corretos.Execute dotnet run to make sure you've got the mappings correct. Você deve ver o mesmo resultado de antes.You should see the same output as before.

Vamos fazer mais uma alteração antes de adicionar novos recursos.Let's make one more change before adding new features. O método ProcessRepositories pode fazer o trabalho assíncrono e retornar uma coleção de repositórios.The ProcessRepositories method can do the async work and return a collection of the repositories. Vamos retornar o List<Repository> desse método e mover o código que grava as informações no método Main.Let's return the List<Repository> from that method, and move the code that writes the information into the Main method.

Altere a assinatura de ProcessRepositories para retornar uma tarefa cujo resultado é uma lista de objetos Repository:Change the signature of ProcessRepositories to return a task whose result is a list of Repository objects:

private static async Task<List<Repository>> ProcessRepositories()

Depois, basta retornar os repositórios depois de processar a resposta JSON:Then, just return the repositories after processing the JSON response:

var streamTask = client.GetStreamAsync("https://api.github.com/orgs/dotnet/repos");
var repositories = await JsonSerializer.DeserializeAsync<List<Repository>>(await streamTask);
return repositories;

O compilador gera o objeto Task<T> para o retorno porque você marcou esse método como async.The compiler generates the Task<T> object for the return because you've marked this method as async. Em seguida, vamos modificar o método Main para que ele capture esses resultados e grave cada nome de repositório no console.Then, let's modify the Main method so that it captures those results and writes each repository name to the console. Seu método Main terá a seguinte aparência:Your Main method now looks like this:

public static async Task Main(string[] args)
{
    var repositories = await ProcessRepositories();

    foreach (var repo in repositories)
        Console.WriteLine(repo.Name);
}

Ler mais informaçõesReading More Information

Vamos concluir isso processando mais algumas propriedades no pacote JSON que são enviadas da API do GitHub.Let's finish this by processing a few more of the properties in the JSON packet that gets sent from the GitHub API. Não convém capturar tudo, mas a adição de algumas propriedades demonstrará mais alguns recursos da linguagem C#.You won't want to grab everything, but adding a few properties will demonstrate a few more features of the C# language.

Vamos começar pela adição de alguns tipos mais simples para a definição de classe Repository.Let's start by adding a few more simple types to the Repository class definition. Adicione essas propriedades à classe:Add these properties to that class:

[JsonPropertyName("description")]
public string Description { get; set; }

[JsonPropertyName("html_url")]
public Uri GitHubHomeUrl { get; set; }

[JsonPropertyName("homepage")]
public Uri Homepage { get; set; }

[JsonPropertyName("watchers")]
public int Watchers { get; set; }

Essas propriedades têm conversões internas do tipo cadeia de caracteres (que é o que os pacotes JSON contêm) para o tipo de destino.These properties have built-in conversions from the string type (which is what the JSON packets contain) to the target type. O tipo Uri pode ser novidade para você.The Uri type may be new to you. Ele representa um URI, ou, nesse caso, uma URL.It represents a URI, or in this case, a URL. No caso dos tipos Uri e int, se o pacote JSON contiver dados que não são convertidos para o tipo de destino, a ação de serialização lançará uma exceção.In the case of the Uri and int types, if the JSON packet contains data that does not convert to the target type, the serialization action will throw an exception.

Depois de adicioná-los, atualize o método Main para exibir esses elementos:Once you've added these, update the Main method to display those elements:

foreach (var repo in repositories)
{
    Console.WriteLine(repo.Name);
    Console.WriteLine(repo.Description);
    Console.WriteLine(repo.GitHubHomeUrl);
    Console.WriteLine(repo.Homepage);
    Console.WriteLine(repo.Watchers);
    Console.WriteLine();
}

Como etapa final, vamos adicionar as informações para a última operação de envio por push.As a final step, let's add the information for the last push operation. Essas informações são formatadas dessa maneira na resposta JSON:This information is formatted in this fashion in the JSON response:

2016-02-08T21:27:00Z

Esse formato está em UTC (tempo Universal Coordenado), portanto, você obterá um DateTime valor cuja Kind propriedade é Utc .That format is in Coordinated Universal Time (UTC) so you'll get a DateTime value whose Kind property is Utc. Se você preferir uma data representada em seu fuso horário, precisará escrever um método de conversão personalizado.If you prefer a date represented in your time zone, you'll need to write a custom conversion method. Primeiro, defina uma public propriedade que conterá a representação UTC da data e hora em sua Repository classe e uma LastPush readonly propriedade que retorna a data convertida para a hora local:First, define a public property that will hold the UTC representation of the date and time in your Repository class and a LastPush readonly property that returns the date converted to local time:

[JsonPropertyName("pushed_at")]
public DateTime LastPushUtc { get; set; }

public DateTime LastPush => LastPushUtc.ToLocalTime();

Vamos examinar as novas construções que acabamos de definir.Let's go over the new constructs we just defined. A LastPush propriedade é definida usando um membro expression-apto para para o get acessador.The LastPush property is defined using an expression-bodied member for the get accessor. Não há nenhum acessador set.There is no set accessor. Omitir o set acessador é como você define uma propriedade somente leitura em C#.Omitting the set accessor is how you define a read-only property in C#. (Sim, você pode criar propriedades somente gravação em C#, mas o valor delas é limitado.)(Yes, you can create write-only properties in C#, but their value is limited.)

Por fim, adicione mais uma instrução de saída no console, e você estará pronto para compilar e executar esse aplicativo novamente:Finally, add one more output statement in the console, and you're ready to build and run this app again:

Console.WriteLine(repo.LastPush);

Agora, sua versão deve corresponder ao exemplo finalizado.Your version should now match the finished sample.

ConclusãoConclusion

Este tutorial mostrou como fazer solicitações da Web, analisar o resultados e exibir as propriedades dos resultados.This tutorial showed you how to make web requests, parse the result, and display properties of those results. Você também adicionou novos pacotes como dependências em seu projeto.You've also added new packages as dependencies in your project. Você viu alguns dos recursos da linguagem C# que dão suporte a técnicas orientadas a objeto.You've seen some of the features of the C# language that support object-oriented techniques.

Você não precisa executar dotnet restore o porque ele é executado implicitamente por todos os comandos que exigem a ocorrência de uma restauração, como,,,, dotnet new dotnet build dotnet run dotnet test dotnet publish e dotnet pack .You don't have to run dotnet restore because it's run implicitly by all commands that require a restore to occur, such as dotnet new, dotnet build, dotnet run, dotnet test, dotnet publish, and dotnet pack. Para desabilitar a restauração implícita, use a --no-restore opção.To disable implicit restore, use the --no-restore option.

O dotnet restore comando ainda é útil em determinados cenários em que a restauração explícita faz sentido, como compilações de integração contínua em Azure DevOps Services ou em sistemas de compilação que precisam controlar explicitamente quando a restauração ocorre.The dotnet restore command is still useful in certain scenarios where explicitly restoring makes sense, such as continuous integration builds in Azure DevOps Services or in build systems that need to explicitly control when the restore occurs.

Para obter informações sobre como gerenciar feeds do NuGet, consulte a dotnet restore documentação.For information about how to manage NuGet feeds, see the dotnet restore documentation.