Tutorial: Gerar um cliente de API REST

Um aplicativo que consome uma API REST é um cenário muito comum. Normalmente, você precisa gerar o código do cliente que seu aplicativo pode usar para chamar a API REST. Neste tutorial, você aprenderá como gerar o cliente de API REST automaticamente durante o processo de compilação usando o MSBuild. Você usará NSwag, uma ferramenta que gera código de cliente para uma API REST.

O código de exemplo completo está disponível em geração de cliente de API REST no repositório de exemplos do .NET no GitHub.

O exemplo mostra uma aplicação de consola que consome a API pública da Pet Store , que publica uma especificação OpenAPI .

O tutorial pressupõe conhecimento básico de termos do MSBuild, como tarefas, destinos, propriedades ou tempos de execução; para obter o plano de fundo necessário, consulte artigo Conceitos do MSBuild.

Quando você deseja executar uma ferramenta de linha de comando como parte de uma compilação, há duas abordagens a serem consideradas. Uma delas é usar o de tarefas MSBuildExec , que permite executar uma ferramenta de linha de comando e especificar seus parâmetros. O outro método é criar uma tarefa personalizada derivada de ToolTask, o que lhe dá maior controle.

Pré-requisitos

Você deve ter uma compreensão dos conceitos do MSBuild, como tarefas, destinos e propriedades. Consulte os conceitos do MSBuild .

Os exemplos exigem MSBuild, que é instalado com o Visual Studio, mas também pode ser instalado separadamente. Consulte para baixar o MSBuild sem o Visual Studio.

Opção 1: Tarefa Executar

A tarefa Exec simplesmente invoca o processo especificado com os argumentos especificados, aguarda sua conclusão e, em seguida, retorna true se o processo for concluído com êxito e false se ocorrer um erro.

A geração de código NSwag pode ser usada a partir do MSBuild; consulte NSwag.MSBuild.

O código completo está na pasta PetReaderExecTaskExample; Você pode baixar e dar uma olhada. Neste tutorial, você passará pelo passo a passo e aprenderá os conceitos no caminho.

Crie um novo aplicativo de console chamado PetReaderExecTaskExample. Use o .NET 6.0 ou posterior.
Crie outro projeto na mesma solução: PetShopRestClient (Esta solução conterá o cliente gerado como uma biblioteca). Para este projeto, use o .NET Standard 2.1. O cliente gerado não compila no .NET Standard 2.0.
No projeto PetReaderExecTaskExample, adicione uma dependência ao projeto PetShopRestClient.
No projeto PetShopRestClient, inclua os seguintes pacotes NuGet:
- Nswag.MSBuild, que permite o acesso ao gerador de código do MSBuild
- Newtonsoft.Json, necessário para compilar o cliente gerado
- System.ComponentModel.Annotations, necessário para compilar o cliente gerado
No projeto PetShopRestClient, adicione uma pasta (chamada PetShopRestClient) para a geração de código e exclua o Class1.cs que foi gerado automaticamente.
Crie um arquivo de texto chamado petshop-openapi-spec.json na raiz do projeto. Copie a especificação OpenAPI de aqui e salve-a no arquivo. É melhor copiar uma cópia da especificação em vez de lê-la online durante a construção. Você sempre quer uma construção consistentemente reproduzível que depende apenas da entrada. Consumir a API diretamente pode transformar uma compilação que funciona hoje em uma compilação que falha amanhã da mesma fonte. A cópia salva no petshop-openapi-spec.json nos permitirá ainda ter uma versão que pode ser compilada, mesmo que a especificação mude.
Em seguida, modifique PetShopRestClient.csproj e adicione um targets MSBuild de forma a gerar o cliente durante a compilação.

Primeiro, adicione algumas propriedades úteis para a geração de clientes:
```
 <PropertyGroup>
     <PetOpenApiSpecLocation>petshop-openapi-spec.json</PetOpenApiSpecLocation>
     <PetClientClassName>PetShopRestClient</PetClientClassName>
     <PetClientNamespace>PetShopRestClient</PetClientNamespace>
     <PetClientOutputDirectory>PetShopRestClient</PetClientOutputDirectory>
 </PropertyGroup>
```
Adicione os seguintes destinos:
```
 <Target Name="generatePetClient" BeforeTargets="CoreCompile" Inputs="$(PetOpenApiSpecLocation)" Outputs="$(PetClientOutputDirectory)\$(PetClientClassName).cs">
     <Exec Command="$(NSwagExe) openapi2csclient /input:$(PetOpenApiSpecLocation)  /classname:$(PetClientClassName) /namespace:$(PetClientNamespace) /output:$(PetClientOutputDirectory)\$(PetClientClassName).cs" ConsoleToMSBuild="true">
     <Output TaskParameter="ConsoleOutput" PropertyName="OutputOfExec" />
   </Exec>
 </Target>
 <Target Name="forceReGenerationOnRebuild" AfterTargets="CoreClean">
    <Delete Files="$(PetClientOutputDirectory)\$(PetClientClassName).cs"></Delete>
 </Target>
```
Observe que esse destino usa os atributos BeforeTarget e AfterTarget como maneira de definir a ordem de compilação. O primeiro destino chamado generatePetClient será executado antes do destino de compilação principal, portanto, a fonte será criada antes que o compilador seja executado. Os parâmetros de entrada e saída estão relacionados ao Incremental Build. O MSBuild pode comparar os carimbos de data/hora dos ficheiros de entrada com os carimbos de data/hora dos ficheiros de saída e determinar se deve ignorar, compilar ou reconstruir parcialmente um alvo.

Depois de instalar o NSwag.MSBuild pacote NuGet em seu projeto, você pode usar a variável $(NSwagExe) em seu arquivo .csproj para executar a ferramenta de linha de comando NSwag em um destino MSBuild. Desta forma, as ferramentas podem ser facilmente atualizadas via NuGet. Aqui, você está usando a tarefa Exec MSBuild para executar o programa NSwag com os parâmetros necessários para gerar a API Rest do cliente. Consulte comando e parâmetros do NSwag.

Você pode capturar a saída de <Exec> adicionando ConsoleToMsBuild="true" à sua tag <Exec> e, em seguida, capturando a saída usando o parâmetro ConsoleOutput em uma tag <Output>. ConsoleOutput retorna a saída como um Item. O espaço em branco é cortado. ConsoleOutput é ativado quando ConsoleToMSBuild é verdadeiro.

O segundo destino chamado forceReGenerationOnRebuild exclui a classe gerada durante a limpeza para forçar a regeneração do código gerado durante a execução do destino de reconstrução. Este destino é executado após o destino predefinido MSBuild CoreClean.
Execute uma reconstrução da solução do Visual Studio e veja o cliente gerado na pasta PetShopRestClient.

Agora, use o cliente gerado. Vá para o Program.csdo cliente e copie o seguinte código:

using System;
using System.Net.Http;

namespace PetReaderExecTaskExample
{
   internal class Program
   {
       private const string baseUrl = "https://petstore.swagger.io/v2";
       static void Main(string[] args)
       {
           HttpClient httpClient = new HttpClient();
           httpClient.BaseAddress = new Uri(baseUrl);
           var petClient = new PetShopRestClient.PetShopRestClient(httpClient);
           var pet = petClient.GetPetByIdAsync(1).Result;
           Console.WriteLine($"Id: {pet.Id} Name: {pet.Name} Status: {pet.Status} CategoryName: {pet.Category.Name}");
       }
   }
}

Observação

Esse código usa new HttpClient() porque é simples de demonstrar, mas não é a prática recomendada para código do mundo real. A prática recomendada é usar HttpClientFactory para criar um objeto HttpClient que resolva os problemas conhecidos de HttpClient solicitação, como esgotamento de recursos ou problemas de DNS obsoleto. Consulte Usar IHttpClientFactory para implementar solicitações HTTP resilientes.

Parabéns;! Agora, você pode executar o programa para ver como ele funciona.

Opção 2: Tarefa personalizada derivada de ToolTask

Em muitos casos, usar a tarefa Exec é bom o suficiente para executar uma ferramenta externa para fazer algo como a geração de código do cliente da API REST, mas e se você quiser permitir a geração de código do cliente da API REST se e somente se você não usar um caminho absoluto do Windows como entrada? E se você precisar calcular de alguma forma onde está o executável? Quando há qualquer situação em que você precisa executar algum código para fazer trabalho extra, o MSBuild Tool Task é a melhor solução. A classe ToolTask é uma classe abstrata derivada do MSBuild Task. Você pode definir uma subclasse concreta, que cria uma tarefa MSBuild personalizada. Essa abordagem permite executar qualquer código necessário para se preparar para a execução do comando. Você deve ler o tutorial Criar uma tarefa personalizada para geração de código primeiro.

Você criará uma tarefa personalizada derivada de MSBuild ToolTask que gerará um cliente de API REST, mas ela será projetada para emitir um erro se você tentar fazer referência à especificação OpenAPI usando um endereço http. O NSwag suporta um endereço http como entrada de especificação OpenAPI, mas para os fins deste exemplo, vamos supor que haja um requisito de design para não permitir isso.

O código completo está nesta pasta PetReaderToolTaskExample; Você pode baixar e dar uma olhada. Neste tutorial, você passará pelo passo a passo e aprenderá alguns conceitos que você pode aplicar aos seus próprios cenários.

Crie um novo projeto do Visual Studio para a tarefa personalizada. Chame-o de RestApiClientGenerator e use o modelo de Biblioteca de Classes (C#) com .NET Standard 2.0. Nomeie a solução PetReaderToolTaskExample.
Exclua Class1.cs, que foi gerado automaticamente.

Adicione os Microsoft.Build.Utilities.Core pacotes NuGet:

Crie uma classe chamada RestApiClientGenerator

Herdar do MSBuild ToolTask e implementar o método abstrato como mostrado no código a seguir:

using Microsoft.Build.Utilities;

namespace RestApiClientGenerator
{
    public class RestApiClientGenerator : ToolTask
    {
        protected override string ToolName => throw new System.NotImplementedException();

        protected override string GenerateFullPathToTool()
        {
            throw new System.NotImplementedException();
        }
    }
}

Adicione os seguintes parâmetros:

InputOpenApiSpec, onde a especificação é
ClientClassName, nome da classe gerada
ClientNamespaceName, namespace onde a classe é gerada
FolderClientClass, caminho para a pasta onde a classe estará localizada
NSwagCommandFullPath, caminho completo para o diretório onde NSwag.exe está localizado

     [Required]
     public string InputOpenApiSpec { get; set; }
     [Required]
     public string ClientClassName { get; set; }
     [Required]
     public string ClientNamespaceName { get; set; }
     [Required]
     public string FolderClientClass { get; set; }
     [Required]
     public string NSwagCommandFullPath { get; set; }

Instale ferramenta de linha de comando NSwag. Você precisará do caminho completo para o diretório onde NSwag.exe está localizado.

Implemente os métodos abstratos:

   protected override string ToolName => "RestApiClientGenerator";

   protected override string GenerateFullPathToTool()
   {
       return $"{NSwagCommandFullPath}\\NSwag.exe";
   }

Há muitos métodos que você pode substituir. Para a implementação atual, defina estes dois:

Defina o parâmetro de comando:

  protected override string GenerateCommandLineCommands()
  {
      return $"openapi2csclient /input:{InputOpenApiSpec}  /classname:{ClientClassName} /namespace:{ClientNamespaceName} /output:{FolderClientClass}\\{ClientClassName}.cs";
  }

Validação de parâmetros:

protected override bool ValidateParameters()
{
      //http address is not allowed
      var valid = true;
      if (InputOpenApiSpec.StartsWith("http:") || InputOpenApiSpec.StartsWith("https:"))
      {
          valid = false;
          Log.LogError("URL is not allowed");
      }

      return valid;
}

Observação

Essa validação simples poderia ser feita de outra forma no arquivo MSBuild, mas é recomendável fazê-lo em código C# e encapsular o comando e a lógica.

Construa o projeto.

Criar um aplicativo de console para usar a nova tarefa do MSBuild

A próxima etapa é criar um aplicativo que use a tarefa.

Crie um projeto de aplicativo de console e chame-o de PetReaderToolTaskConsoleApp. Escolha a versão .NET desejada. Marque-o como projeto de inicialização.
Crie uma biblioteca de classes projeto para gerar o código, chamado PetRestApiClient. Utilize o .NET Standard.
No projeto PetReaderToolTaskConsoleApp, crie uma dependência de projeto para PetRestApiClient.
No projeto PetRestApiClient, crie uma pasta PetRestApiClient. Esta pasta conterá o código gerado.
Exclua Class1.cs, que foi gerado automaticamente.
Em PetRestApiClient, adicione os seguintes pacotes NuGet:
- Newtonsoft.Json, necessário para compilar o cliente gerado
- System.ComponentModel.Annotations, necessário para compilar o cliente gerado
No projeto PetRestApiClient, crie um arquivo de texto chamado petshop-openapi-spec.json (na pasta do projeto). Para adicionar a especificação OpenAPI, copie o conteúdo do aqui para o arquivo. Gostamos de uma construção reprodutível que depende apenas da entrada, como discutido anteriormente. Neste exemplo, você gerará um erro de compilação se um usuário escolher uma URL como a entrada de especificação OpenAPI.

Importante

Uma reconstrução geral não funcionará. Você verá erros que indicam que não é possível copiar ou excluir RestApiClientGenerator.dll'. Isso ocorre porque ele está tentando criar a tarefa personalizada do MBuild no mesmo processo de compilação que a usa. Selecione PetReaderToolTaskConsoleApp e reconstrua apenas esse projeto. A outra solução é colocar a tarefa personalizada em uma solução completamente independente do Visual Studio, como você fez em Tutorial: Criar uma tarefa personalizada exemplo.

Copie o seguinte código para Program.cs:

 using System;
 using System.Net.Http;
 namespace PetReaderToolTaskConsoleApp
 {
   internal class Program
   {
       private const string baseUrl = "https://petstore.swagger.io/v2";
       static void Main(string[] args)
       {
           HttpClient httpClient = new HttpClient();
           httpClient.BaseAddress = new Uri(baseUrl);
           var petClient = new PetRestApiClient.PetRestApiClient(httpClient);
           var pet = petClient.GetPetByIdAsync(1).Result;
           Console.WriteLine($"Id: {pet.Id} Name: {pet.Name} Status: {pet.Status} CategoryName: {pet.Category.Name}");
       }
   }
 }

Altere as instruções do MSBuild para chamar a tarefa e gerar o código. Edite PetRestApiClient.csproj seguindo estas etapas:

Registre o uso da tarefa personalizada do MSBuild:

<UsingTask TaskName="RestApiClientGenerator.RestApiClientGenerator" AssemblyFile="..\RestApiClientGenerator\bin\Debug\netstandard2.0\RestApiClientGenerator.dll" />

Adicione algumas propriedades necessárias para executar a tarefa:

 <PropertyGroup>
    <!--The place where the OpenAPI spec is in-->
   <PetClientInputOpenApiSpec>petshop-openapi-spec.json</PetClientInputOpenApiSpec>
   <PetClientClientClassName>PetRestApiClient</PetClientClientClassName>
   <PetClientClientNamespaceName>PetRestApiClient</PetClientClientNamespaceName>
   <PetClientFolderClientClass>PetRestApiClient</PetClientFolderClientClass>
   <!--The directory where NSawg.exe is in-->
   <NSwagCommandFullPath>C:\Nsawg\Win</NSwagCommandFullPath>
  </PropertyGroup>

Importante

Selecione o valor de NSwagCommandFullPath adequado com base no local de instalação no seu sistema.

Adicione um alvo de MSBuild para gerar o cliente durante o processo de compilação. Esse destino deve ser executado antes de CoreCompile executar para gerar o código usado na compilação.

<Target Name="generatePetClient" BeforeTargets="CoreCompile" Inputs="$(PetClientInputOpenApiSpec)" Outputs="$(PetClientFolderClientClass)\$(PetClientClientClassName).cs">
  <!--Calling our custom task derivated from MSBuild Tool Task-->
  <RestApiClientGenerator InputOpenApiSpec="$(PetClientInputOpenApiSpec)" ClientClassName="$(PetClientClientClassName)" ClientNamespaceName="$(PetClientClientNamespaceName)" FolderClientClass="$(PetClientFolderClientClass)" NSwagCommandFullPath="$(NSwagCommandFullPath)"></RestApiClientGenerator>
</Target>

<Target Name="forceReGenerationOnRebuild" AfterTargets="CoreClean">
  <Delete Files="$(PetClientFolderClientClass)\$(PetClientClientClassName).cs"></Delete>
</Target>

Input e Output estão relacionados ao Incremental Build, e o destino forceReGenerationOnRebuild exclui o arquivo gerado após CoreClean, o que força o cliente a ser regenerado durante a operação de reconstrução.

Selecione PetReaderToolTaskConsoleApp e reconstrua apenas esse projeto. Agora, o código do cliente é gerado e o código é compilado. Você pode executá-lo e ver como ele funciona. Esse código gera o código de um arquivo, e isso é permitido.
Nesta etapa, você demonstrará a validação do parâmetro. Em PetRestApiClient.csproj, altere a propriedade $(PetClientInputOpenApiSpec) para usar a URL:
```
  <PetClientInputOpenApiSpec>https://petstore.swagger.io/v2/swagger.json</PetClientInputOpenApiSpec>
```
Selecione PetReaderToolTaskConsoleApp e reconstrua apenas esse projeto. Você receberá o erro "URL não é permitido" de acordo com o requisito de design.

Faça o download do código

Instale a ferramenta de linha de comando NSwag. Em seguida, você precisará do caminho completo para o diretório onde NSwag.exe está localizado. Depois disso, edite PetRestApiClient.csproj e selecione o valor de $(NSwagCommandFullPath) adequado com base no caminho de instalação no seu computador. Agora, selecione RestApiClientGenerator e construa apenas esse projeto e, finalmente, selecione e reconstrua PetReaderToolTaskConsoleApp. Você pode executar PetReaderToolTaskConsoleApp. para verificar se tudo funciona conforme o esperado.

Próximos passos

Talvez você queira publicar sua tarefa personalizada como um pacote NuGet.

Tutorial: Criar uma tarefa personalizada

Ou saiba como testar uma tarefa personalizada.

Testar uma tarefa personalizada do MSBuild

Feedback

Esta página foi útil?

Last updated on 2025-12-12