Kurz: Vygenerování klienta ROZHRANÍ REST API

Článek
08/25/2023

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ý vygeneruje klientský kód pro rozhraní REST API.

Kompletní ukázkový kód je k dispozici při generování klienta REST API v úložišti ukázek .NET na GitHubu.

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

Tento kurz předpokládá základní znalosti termínů NÁSTROJE MSBuild, jako jsou úlohy, cíle, vlastnosti nebo moduly runtime; potřebné informace naleznete v článku o konceptech nástroje 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.

Předpoklady

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 Stažení nástroje MSBuild bez sady Visual Studio.

Možnost 1: Úloha Exec

Ú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 NÁSTROJE MSBuild; viz NSwag.MSBuild.

Kompletní kód je ve složce PetReaderExecTaskExample . Můžete si stáhnout a podívat se na ně. 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.
PetReaderExecTaskExample V projektu a přidejte do projektu závislost projektuPetShopRestClient.
PetShopRestClient V projektu 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
PetShopRestClient V projektu přidejte složku (pojmenovanouPetShopRestClient) pro generování kódu a odstraňte soubor Class1.cs, který se automaticky vygeneroval.
V kořenovém adresáři projektu vytvořte textový soubor petshop-openapi-spec.json . Odtud zkopírujte specifikaci OpenApi 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 vygenerová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, jak definovat pořadí sestavení. První zavoláný generatePetClient cíl 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í parametr souvisí s přírůstkovým sestavením. 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 NSwag.MSBuild balíčku NuGet do projektu můžete pomocí proměnné $(NSwagExe) v .csproj souboru 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. Tady používáte Exec úlohu MSBuild ke spuštění programu NSwag s požadovanými parametry pro vygenerování rozhraní REST API klienta. Viz příkaz a parametry NSwag.

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

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

Teď použijte vygenerovaného klienta. Přejděte do souboru Client Program.cs a 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 se používá new HttpClient() , protože je jednoduchý k předvedení, ale není osvědčeným postupem pro skutečný kód. Osvědčeným postupem je vytvořit HttpClientFactoryHttpClient objekt, který řeší známé problémy HttpClient s požadavky, jako jsou vyčerpání prostředků nebo zastaralé problémy DNS. Viz Použití IHttpClientFactory k implementaci odolný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í Exec úlohy dostatečně dobré ke spuštění externího nástroje pro generování kódu, jako je generování kódu klienta REST API, ale co když chcete povolit generování kódu klienta REST API, pokud a jenom v případě, že 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 se udělala další práce, je nejlepším řešením úloha nástroje MSBuild. Třída ToolTask 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. Měli byste si přečíst kurz Vytvoření vlastní úlohy pro generování kódu jako první.

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 PetReaderToolTaskExample složce. Můžete si stáhnout a podívat se na ně. 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#) s .NET Standard 2.0. Pojmenujte řešení PetReaderToolTaskExample.
Odstraňte soubor Class1.cs, který se automaticky vygeneroval.

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

Vytvoření volané třídy 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 NSwag.exe je umístěn

     [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 zavolejte ho PetReaderToolTaskConsoleApp. Zvolte .NET 6.0. Označte ho jako spouštěný projekt.
Vytvořte projekt knihovny tříd pro vygenerování kódu s názvem PetRestApiClient. Použijte .NET Standard 2.1.
PetReaderToolTaskConsoleApp V projektu vytvořte závislost projektu na PetRestApiClient.
PetRestApiClient V projektu vytvořte složku PetRestApiClient. Tato složka bude obsahovat vygenerovaný kód.
Odstraňte soubor Class1.cs, který se automaticky vygeneroval.
Přidejte PetRestApiClientnásledující balíčky NuGet:
- Newtonsoft.Json, potřebný ke kompilaci vygenerovaného klienta
- System.ComponentModel.Annotations, potřebné ke kompilaci vygenerovaného klienta
PetRestApiClient V projektu vytvořte textový soubor s názvem petshop-openapi-spec.json (ve složce projektu). Pokud chcete přidat specifikaci OpenApi, zkopírujte obsah odsud 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 jako vstup specifikace OpenApi zvolí adresu URL.

Důležité

Obecné opětovné sestavení nebude fungovat. Zobrazí se chyby, které značí, že nejde zkopírovat nebo odstranit RestApiClientGeneratorknihovnu .dll. Je to proto, že se pokouší sestavit vlastní úlohu MBuild ve stejném procesu sestavení, který ho 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ího příkladu úlohy .

Do souboru Program.cs zkopí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 pomocí následujícího postupu:

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 NSwagCommandFullPath hodnotu na základě umístění instalace ve vašem systému.

Přidejte cíl NÁSTROJE MSBuild pro vygenerování klienta během procesu sestavení. Tento cíl by se měl provést před CoreCompile spuštěním, 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 souvisí s přírůstkovým sestavením aforceReGenerationOnRebuild cíl odstraní vygenerovaný soubor po CoreClean, který vynutí opětovné 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.csproj změň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.

Stáhněte si kód

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 $(NSwagCommandFullPath) hodnotu na základě instalační cesty v počítači. Nyní vyberte RestApiClientGenerator a sestavte pouze tento projekt a nakonec vyberte a znovu sestavit PetReaderToolTaskConsoleApp. Můžete provést 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í úlohy

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

Testování vlastní úlohy MSBuild