Návod: Vygenerování klienta REST API

2025-06-12

Aplikace, která využívá rozhraní REST API, je velmi běžný scénář. Obvykle potřebujete vygenerovat klientský kód, který může vaše aplikace použít k volání rozhraní REST API. V tomto kurzu se dozvíte, jak automaticky vygenerovat klienta REST API během procesu sestavení pomocí nástroje MSBuild. Použijete NSwag, nástroj, který generuje klientský kód pro rozhraní REST API.

Kompletní ukázkový kód je k dispozici v úložišti ukázek .NET na GitHubu, konkrétně v části generování klienta REST API.

Příklad ukazuje konzolovou aplikaci, která využívá veřejné rozhraní API pro Pet Store, která publikuje specifikace OpenAPI.

Tento kurz předpokládá základní znalosti pojmů MSBuild, jako jsou úkoly, cíle, vlastnosti nebo runtime; potřebné informace najdete v článku Koncepty MSBuild .

Pokud chcete spustit nástroj příkazového řádku jako součást sestavení, je potřeba vzít v úvahu dva přístupy. Jedním z nich je použití úlohy MSBuild Exec, která umožňuje spustit nástroj příkazového řádku a zadat jeho parametry. Druhou metodou je vytvoření vlastní úlohy odvozené z ToolTask, což vám dává větší kontrolu.

Požadavky

Měli byste znát koncepty nástroje MSBuild, jako jsou úkoly, cíle a vlastnosti. Viz koncepty nástroje MSBuild.

Příklady vyžadují nástroj MSBuild, který je nainstalován se sadou Visual Studio, ale lze je nainstalovat také samostatně. Viz Stáhnout MSBuild bez sady Visual Studio.

Možnost 1: Spustit úlohu

Úloha Exec jednoduše vyvolá zadaný proces se zadanými argumenty, počká na dokončení a pak vrátí true, pokud se proces úspěšně dokončí, a false, pokud dojde k chybě.

Generování kódu NSwag lze použít z MSBuild; viz NSwag.MSBuild.

Úplný kód je ve složce PetReaderExecTaskExample; můžete si stáhnout a podívat se. V tomto kurzu si projdete krok za krokem a naučíte se koncepty na cestě.

Vytvořte novou konzolovou aplikaci s názvem PetReaderExecTaskExample. Použijte .NET 6.0 nebo novější.
Ve stejném řešení vytvořte jiný projekt: PetShopRestClient (toto řešení bude obsahovat vygenerovaného klienta jako knihovnu). Pro tento projekt použijte .NET Standard 2.1. Vygenerovaný klient se nekompiluje ve verzi .NET Standard 2.0.
V projektu PetReaderExecTaskExample a přidejte závislost na projektu PetShopRestClient.
V projektu PetShopRestClient zahrňte následující balíčky NuGet:
- Nswag.MSBuild, který umožňuje přístup k generátoru kódu z MSBuild
- Newtonsoft.Json, potřebný ke kompilaci vygenerovaného klienta
- System.ComponentModel.Annotations, potřebné ke kompilaci vygenerovaného klienta
V projektu PetShopRestClient přidejte složku (pojmenovanou PetShopRestClient) pro generování kódu a odstraňte Class1.cs, která se automaticky vygenerovala.
Vytvořte textový soubor s názvem petshop-openapi-spec.json v kořenovém adresáři projektu. Zkopírujte specifikaci OpenAPI z sem a uložte ji do souboru. Nejlepší je zkopírovat snímek specifikace místo toho, abyste ho během sestavování četli online. Vždy chcete konzistentně reprodukovatelný build, který závisí pouze na vstupu. Přímé využívání rozhraní API by mohlo transformovat sestavení, které dnes funguje na sestavení, které zítra selže ze stejného zdroje. Snímek uložený na petshop-openapi-spec.json nám umožní stále mít verzi, která se sestaví i v případě, že se specifikace změní.
Dále upravte PetShopRestClient.csproj a přidejte cíle MSBuild pro generování klienta během procesu sestavení.

Nejprve přidejte některé vlastnosti užitečné pro generování klienta:
```
 <PropertyGroup>
     <PetOpenApiSpecLocation>petshop-openapi-spec.json</PetOpenApiSpecLocation>
     <PetClientClassName>PetShopRestClient</PetClientClassName>
     <PetClientNamespace>PetShopRestClient</PetClientNamespace>
     <PetClientOutputDirectory>PetShopRestClient</PetClientOutputDirectory>
 </PropertyGroup>
```
Přidejte následující cíle:
```
 <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>
```
Všimněte si, že tento cíl používá atributy BeforeTarget a AfterTarget jako způsob definování pořadí sestavení. První cíl s názvem generatePetClient se spustí před cílem kompilace jádra, takže zdroj se vytvoří před spuštěním kompilátoru. Vstupní a výstupní parametry souvisí s přírůstkovou sestavou. Nástroj MSBuild může porovnat časová razítka vstupních souborů s časovými razítky výstupních souborů a určit, zda se má přeskočit, sestavit nebo částečně znovu sestavit cíl.

Po instalaci balíčku NuGet NSwag.MSBuild do projektu můžete pomocí proměnné $(NSwagExe) v souboru .csproj spustit nástroj příkazového řádku NSwag v cíli MSBuild. Díky tomu je možné nástroje snadno aktualizovat prostřednictvím NuGetu. V této části používáte úlohu Exec MSBuild ke spuštění programu NSwag s požadovanými parametry pro vygenerování rozhraní REST API klienta. Viz příkaz NSwag a parametry.

Můžete zachytit výstup z <Exec> přidáním ConsoleToMsBuild="true" do značky <Exec> a následným zachycením výstupu pomocí parametru ConsoleOutput ve značce <Output>. ConsoleOutput vrátí výstup jako hodnotu Item. Prázdné znaky jsou oříznuté. ConsoleOutput je povolena, pokud je ConsoleToMSBuild true.

Druhý cíl, který se nazývá forceReGenerationOnRebuild odstraní vygenerovanou třídu během čištění, aby vynutila regeneraci generovaného kódu během opětovného sestavení cílového spuštění. Tento cíl se spustí po předdefinovaném cíli CoreClean MSBuild.
Spusťte opětovné sestavení řešení sady Visual Studio a prohlédněte si klienta vygenerovaného ve složce PetShopRestClient.

Teď použijte vygenerovaného klienta. Přejděte do klientského Program.csa zkopírujte následující kód:

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}");
       }
   }
}

Poznámka

Tento kód používá new HttpClient(), protože je jednoduchý k předvedení, ale nejedná se o osvědčený postup pro skutečný kód. Osvědčeným postupem je použít HttpClientFactory k vytvoření objektu HttpClient, který řeší známé problémy s HttpClient požadavky, jako jsou vyčerpání prostředků nebo zastaralé problémy DNS. Viz Použijte IHttpClientFactory k implementaci spolehlivých požadavků HTTP.

Blahopřejeme! Teď můžete program spustit a podívat se, jak funguje.

Možnost 2: Vlastní úloha odvozená z ToolTask

V mnoha případech je použití úlohy Exec dostatečně dobré ke spuštění externího nástroje, aby provedl něco jako generování kódu klienta REST API, ale co když chcete povolit generování kódu klienta REST API, pokud a pouze pokud jako vstup nepoužíváte absolutní cestu Windows? Nebo co když potřebujete vypočítat nějakým způsobem, kde je spustitelný soubor? Pokud je situace, kdy potřebujete spustit nějaký kód, aby provedl další práci, MSBuild Tool Task je nejlepším řešením. ToolTask třída je abstraktní třída odvozená z MSBuild Task. Můžete definovat konkrétní podtřídu, která vytvoří vlastní úlohu MSBuild. Tento přístup umožňuje spustit jakýkoli kód, který je potřeba k přípravě na spuštění příkazu. Nejprve byste si měli přečíst kurz Vytvoření vlastní úlohy pro generování kódu.

Vytvoříte vlastní úlohu odvozenou z nástroje MSBuild ToolTask, která vygeneruje klienta rozhraní REST API, ale bude navržena tak, aby vygenerovala chybu, pokud se pokusíte odkazovat na specifikaci OpenAPI pomocí adresy HTTP. NSwag podporuje adresu HTTP jako vstup specifikace OpenAPI, ale pro účely tohoto příkladu předpokládejme, že existuje požadavek na návrh, který by to nepovolil.

Kompletní kód je v této složce PetReaderToolTaskExample; můžete si stáhnout a podívat se. V tomto kurzu si projdete krok za krokem a seznámíte se s některými koncepty, které můžete použít ve vlastních scénářích.

Vytvořte nový projekt sady Visual Studio pro vlastní úkol. Zavolejte ji RestApiClientGenerator a použijte šablonu knihovny tříd (C#) se standardem .NET Standard 2.0. Pojmenujte řešení PetReaderToolTaskExample.
Odstraňte Class1.cs, který se automaticky vygeneroval.

Přidejte balíčky NuGet Microsoft.Build.Utilities.Core:

Vytvoření třídy s názvem RestApiClientGenerator

Dědí z msBuild ToolTask a implementuje abstraktní metodu, jak je znázorněno v následujícím kódu:

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();
        }
    }
}

Přidejte následující parametry:

InputOpenApiSpec, kde je specifikace
ClientClassName, název vygenerované třídy
ClientNamespaceName, obor názvů, ve kterém je třída generována
FolderClientClass, cesta ke složce, ve které se třída nachází
NSwagCommandFullPath, úplná cesta k adresáři, kde se nachází NSwag.exe

     [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; }

Nainstalujte nástroj příkazového řádku NSwag. Budete potřebovat úplnou cestu k adresáři, kde se nachází NSwag.exe.

Implementace abstraktních metod:

   protected override string ToolName => "RestApiClientGenerator";

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

Existuje mnoho metod, které můžete přepsat. Pro aktuální implementaci definujte tyto dva:

Definujte parametr příkazu:

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

Ověření parametru:

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;
}

Poznámka

Toto jednoduché ověření lze provést jiným způsobem v souboru MSBuild, ale doporučuje se to v kódu jazyka C# a zapouzdření příkazu a logiky.

Sestavte projekt.

Vytvoření konzolové aplikace pro použití nové úlohy MSBuild

Dalším krokem je vytvoření aplikace, která tuto úlohu používá.

Vytvořte projekt konzolové aplikace a pojmenujte jej PetReaderToolTaskConsoleApp. Zvolte .NET 6.0. Označte ho jako spouštěný projekt.
Vytvořte knihovnu tříd projektu pro vygenerování kódu, který se nazývá PetRestApiClient. Použijte .NET Standard 2.1.
V projektu PetReaderToolTaskConsoleApp vytvořte závislost projektu pro PetRestApiClient.
V projektu PetRestApiClient vytvořte složku PetRestApiClient. Tato složka bude obsahovat vygenerovaný kód.
Odstraňte Class1.cs, který se automaticky vygeneroval.
Na PetRestApiClientpřidejte následující balíčky NuGet:
- Newtonsoft.Json, potřebný ke kompilaci vygenerovaného klienta
- System.ComponentModel.Annotations, potřebné ke kompilaci vygenerovaného klienta
V projektu PetRestApiClient vytvořte textový soubor s názvem petshop-openapi-spec.json (ve složce projektu). Pokud chcete přidat specifikaci OpenAPI, zkopírujte obsah z sem do souboru. Líbí se nám reprodukovatelné sestavení, které závisí pouze na vstupu, jak je popsáno dříve. V tomto příkladu vyvoláte chybu sestavení, pokud uživatel zvolí adresu URL jako vstup specifikace OpenAPI.

Důležitý

Celkové opětovné sestavení nebude fungovat. Zobrazí se chyby, které značí, že nejde kopírovat nebo odstraňovat RestApiClientGenerator.dll'. Je to proto, že se pokouší sestavit vlastní úlohu MBuild ve stejném procesu sestavení, který ji používá. Vyberte PetReaderToolTaskConsoleApp a znovu sestavte pouze tento projekt. Dalším řešením je umístit vlastní úlohu do zcela nezávislého řešení sady Visual Studio, jak jste to udělali v kurzu : Vytvoření vlastní úlohy příkladu.

Do Program.cszkopírujte následující kód:

 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}");
       }
   }
 }

Změňte pokyny nástroje MSBuild tak, aby volala úlohu a vygenerovala kód. Upravte PetRestApiClient.csproj následujícím postupem:

Zaregistrujte použití vlastní úlohy MSBuild:

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

Přidejte některé vlastnosti potřebné ke spuštění úlohy:

 <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>

Důležitý

Vyberte správnou hodnotu NSwagCommandFullPath na základě umístění instalace ve vašem systému.

Přidejte cílový nástroje MSBuild pro vygenerování klienta během procesu sestavení. Tento cíl by se měl spustit před spuštěním CoreCompile, aby se vygeneroval kód použitý v kompilaci.

<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 a Output souvisejí s přírůstkovým sestaveníma cíl forceReGenerationOnRebuild odstraní vygenerovaný soubor po CoreClean, což vynutí nové vygenerování klienta během operace opětovného sestavení.

Vyberte PetReaderToolTaskConsoleApp a znovu sestavte pouze tento projekt. Teď se vygeneruje klientský kód a kód se zkompiluje. Můžete ho spustit a podívat se, jak funguje. Tento kód vygeneruje kód ze souboru a je povolený.
V tomto kroku předvedete ověření parametru. V PetRestApiClient.csprojzměňte vlastnost $(PetClientInputOpenApiSpec) tak, aby používala adresu URL:
```
  <PetClientInputOpenApiSpec>https://petstore.swagger.io/v2/swagger.json</PetClientInputOpenApiSpec>
```
Vyberte PetReaderToolTaskConsoleApp a znovu sestavte pouze tento projekt. Zobrazí se chyba "Adresa URL není povolená" v souladu s požadavkem na návrh.

Stažení kódu

Nainstalujte nástroj příkazového řádku NSwag. Pak budete potřebovat úplnou cestu k adresáři, kde se nachází NSwag.exe. Potom upravte PetRestApiClient.csproj a vyberte správnou hodnotu $(NSwagCommandFullPath) na základě instalační cesty v počítači. Nyní vyberte RestApiClientGenerator a sestavte pouze tento projekt a nakonec vyberte a znovu sestavte PetReaderToolTaskConsoleApp. Můžete spustit PetReaderToolTaskConsoleApp. a ověřte, že všechno funguje podle očekávání.

Další kroky

Vlastní úlohu můžete publikovat jako balíček NuGet.

kurz : Vytvoření vlastního úkolu

Nebo se dozvíte, jak otestovat vlastní úlohu.

Otestovat vlastní úkol MSBuild

Sdílet prostřednictvím