Oktatóanyag: REST API-ügyfél létrehozása

A REST API-t használó alkalmazások nagyon gyakori forgatókönyvek. Általában olyan ügyfélkódot kell létrehoznia, amellyel az alkalmazás meghívhatja a REST API-t. Ebben az oktatóanyagban megtanulhatja, hogyan hozhatja létre automatikusan a REST API-ügyfelet a buildelési folyamat során az MSBuild használatával. Használja majd az NSwageszközt, amely klienskódot generál egy REST API-hoz.

A teljes mintakód REST API-ügyfélgenerálási érhető el a GitHub .NET-minták adattárában.

A példa egy olyan konzolalkalmazást mutat be, amely a nyilvános Pet Store API-t használja, amely közzétesz egy OpenAPI specifikációt.

Az oktatóanyag alapszintű ismereteket feltételez az MSBuild kifejezésekről, például feladatokról, célokról, tulajdonságokról vagy futtatókörnyezetekről; a szükséges háttérért lásd MSBuild Concepts cikk.

Ha parancssori eszközt szeretne futtatni egy build részeként, két módszert kell figyelembe vennie. Az egyik az MSBuild Exec-feladathasználata, amely lehetővé teszi egy parancssori eszköz futtatását és paramétereinek megadását. A másik módszer egy egyéni feladat létrehozása ToolTaskalapján, amely nagyobb irányítást biztosít.

Előfeltételek

Ismernie kell az MSBuild fogalmait, például a feladatokat, a célokat és a tulajdonságokat. Lásd MSBuild fogalmakat.

A példákhoz az MSBuild szükséges, amely a Visual Studióval van telepítve, de külön is telepíthető. Lásd: Az MSBuild letöltése Visual Studionélkül.

1. lehetőség: Feladat végrehajtása

Az Exec-feladat egyszerűen meghívja a megadott folyamatot a megadott argumentumokkal, megvárja, amíg befejeződik, majd true ad vissza, ha a folyamat sikeresen befejeződött, és false, ha hiba történik.

Az NSwag-kódlétrehozás az MSBuildből használható; lásd: NSwag.MSBuild.

A teljes kód a PetReaderExecTaskExample mappában található; töltheti le és tekintheti meg. Ebben az oktatóanyagban lépésről lépésre haladva elsajátíthatja a fogalmakat.

Hozzon létre egy PetReaderExecTaskExamplenevű új konzolalkalmazást. Használja a .NET 6.0-s vagy újabb verzióját.
Hozzon létre egy másik projektet ugyanabban a megoldásban: PetShopRestClient (Ez a megoldás a létrehozott ügyfelet tárként fogja tartalmazni). Ehhez a projekthez használja a .NET Standard 2.1-et. A generált ügyfél nem kompilálható a .NET Standard 2.0-n.
A PetReaderExecTaskExample projektben, és adjon hozzá egy projektfüggőséget PetShopRestClient projekthez.
A PetShopRestClient projektben adja meg a következő NuGet-csomagokat:
- Nswag.MSBuild, amely lehetővé teszi a kódgenerátor elérését az MSBuild-ből
- A létrehozott kliens fordításához szükséges a Newtonsoft.Json
- A létrehozott kliens fordításához szükséges System.ComponentModel.Annotations
A PetShopRestClient projektben adjon hozzá egy mappát (PetShopRestClient) a kódgeneráláshoz, és törölje az automatikusan létrehozott Class1.cs.
Hozzon létre egy petshop-openapi-spec.json nevű szövegfájlt a projekt gyökerénél. Másolja ki az OpenAPI-specifikációt , és mentse a fájlba. A legjobb, ha a specifikációról készít egy másolatot ahelyett, hogy online olvassa a build során. Mindig olyan következetesen reprodukálható buildet szeretne, amely csak a bemenettől függ. Az API közvetlen felhasználása átalakíthat egy ma működő buildet egy olyan buildté, amely holnap ugyanabból a forrásból meghiúsul. A petshop-openapi-spec.json mentett pillanatkép lehetővé teszi, hogy még mindig legyen egy olyan verzió, amely akkor is buildel, ha a specifikáció megváltozik.
Ezután módosítsa a PetShopRestClient.csproj fájlt, és adjon hozzá egy MSBuild-célokat az ügyfél létrehozásához a buildelési folyamat során.

Először adjon hozzá néhány hasznos tulajdonságot az ügyfélgeneráláshoz:
```
 <PropertyGroup>
     <PetOpenApiSpecLocation>petshop-openapi-spec.json</PetOpenApiSpecLocation>
     <PetClientClassName>PetShopRestClient</PetClientClassName>
     <PetClientNamespace>PetShopRestClient</PetClientNamespace>
     <PetClientOutputDirectory>PetShopRestClient</PetClientOutputDirectory>
 </PropertyGroup>
```
Adja hozzá a következő célokat:
```
 <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>
```
Figyelje meg, hogy ez a cél a BeforeTarget és az AfterTarget attribútumokat használja a buildelési sorrend meghatározásához. Az első generatePetClient nevű cél az alapvető fordítási cél előtt lesz végrehajtva, így a forrás a fordító végrehajtása előtt jön létre. A bemeneti és kimeneti paraméterek a növekményes buildhezkapcsolódnak. Az MSBuild összehasonlíthatja a bemeneti fájlok időbélyegét a kimeneti fájlok időbélyegeivel, és meghatározhatja, hogy kihagyja, felépíti vagy részben újraépíti-e a célokat.

Miután telepítette a NSwag.MSBuild NuGet-csomagot a projektben, a $(NSwagExe) fájlban található változó .csproj használatával futtathatja az NSwag parancssori eszközt egy MSBuild-célhelyen. Így az eszközök egyszerűen frissíthetők a NuGet használatával. Itt az Exec MSBuild feladatot használja az NSwag program végrehajtásához az ügyfél Rest Api létrehozásához szükséges paraméterekkel. Lásd NSwag parancsot és paramétereket.

A kimenetet rögzítheti <Exec>ConsoleToMsBuild="true"<Exec> címkéhez való hozzáadásával, majd rögzítheti a kimenetet egy ConsoleOutput címke <Output> paraméterével. ConsoleOutput a kimenetet Itemadja vissza. A szóköz eltávolítva lett. ConsoleOutput akkor van engedélyezve, ha ConsoleToMSBuild igaz.

A második, forceReGenerationOnRebuild nevű cél törli a létrehozott osztályt a törlés során, hogy kényszerítse a létrehozott kód újragenerálását az újraépítési cél végrehajtása során. Ez a feladat a CoreClean MSBuild előre definiált cél után fut.
Hajtsa végre a Visual Studio-megoldás újraépítését, és tekintse meg a PetShopRestClient mappában létrehozott ügyfelet.

Most használja a létrehozott ügyfelet. Lépjen az ügyfél Program.cs, és másolja a következő kódot:

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

Jegyzet

Ez a kód a new HttpClient()-t használja, mert egyszerűen szemlélteti, de ez nem a legjobb gyakorlat a valós életbeli kódban. Az ajánlott eljárás a HttpClientFactory használata egy HttpClient objektum létrehozásához, amely a HttpClient kérés ismert problémáit, például az erőforrás-kimerülést vagy az elavult DNS-problémákat kezeli. Lásd Az IHttpClientFactory használata rugalmas HTTP-kérésekimplementálásához.

Gratulálok! Most végrehajthatja a programot, hogy lássa, hogyan működik.

2. lehetőség: Az ToolTask-ból származtatott egyéni feladat

A Exec feladat használata sok esetben elég jó ahhoz, hogy külső eszközt hajtsunk végre a REST API-ügyfélkód-létrehozáshoz hasonló műveletekhez, de mi a teendő, ha engedélyezni szeretnénk a REST API-ügyfélkódok létrehozását, ha és csak akkor, ha nem használunk abszolút Windows-elérési utat bemenetként? Vagy mi a teendő, ha valamilyen módon ki kell számítania, hogy hol található a végrehajtható fájl? Ha olyan helyzet áll fenn, amikor valamilyen kódot kell végrehajtania a további munkához, a MSBuild Tool Task a legjobb megoldás. A ToolTask osztály egy MSBuild Taskszármazó absztrakt osztály. Megadhat egy konkrét alosztályt, amely létrehoz egy egyéni MSBuild feladatot. Ezzel a módszerrel futtathat minden olyan kódot, amely a parancs végrehajtására való felkészüléshez szükséges. Először olvassa el az oktatóanyagot Egyéni feladat létrehozása a kódgeneráláshoz.

Létrehoz egy egyéni feladatot, amely a MSBuild ToolTask-ből van származtatva, és amely létrehoz egy REST API-ügyfelet, de úgy lesz kialakítva, hogy hibát jelezzen, ha http-címmel próbál hivatkozni az OpenAPI-specifikációra. Az NSwag OpenAPI-specifikációs bemenetként támogatja a HTTP-címet, de a példa alkalmazásában tegyük fel, hogy van egy tervezési követelmény, amelyet le kell tiltani.

A teljes kód ebben a PetReaderToolTaskExample mappában található; töltheti le és tekintheti meg. Ebben az oktatóanyagban lépésről lépésre haladva megismerhet néhány fogalmat, amelyeket saját forgatókönyveihez alkalmazhat.

Hozzon létre egy új Visual Studio-projektet az egyéni feladathoz. Hívja meg RestApiClientGenerator, és használja a Osztálytár (C#) sablont a .NET Standard 2.0-val. Nevezze el a megoldást PetReaderToolTaskExample.
Törölje az automatikusan létrehozott Class1.cs.

Adja hozzá a Microsoft.Build.Utilities.Core NuGet-csomagokat:

RestApiClientGenerator nevű osztály létrehozása

Örökölje az MSBuild ToolTask és implementálja az absztrakt metódust az alábbi kódban látható módon:

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

Adja hozzá a következő paramétereket:
- InputOpenApiSpec, ahol a specifikáció
- ClientClassName, a létrehozott osztály neve
- ClientNamespaceName, névtér, ahol az osztály létre van hozva
- FolderClientClass, az osztály helyét tartalmazó mappa elérési útja
- NSwagCommandFullPath, teljes elérési út ahhoz a könyvtárhoz, ahol NSwag.exe található
```
     [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; }
```
Telepítse a NSwag parancssori eszközt. Szükséges a könyvtár teljes elérési útja, ahol NSwag.exe található.

Az absztrakt módszerek implementálása:

   protected override string ToolName => "RestApiClientGenerator";

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

Számos módszer van, amit felülbírálhatsz. A jelenlegi implementációhoz adja meg a következő kettőt:

Adja meg a parancsparamétert:

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

Paraméter érvényesítése:

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

Jegyzet

Ez az egyszerű ellenőrzés más módon is elvégezhető az MSBuild fájlban, de ajánlott C#-kódban elvégezni, és beágyazni a parancsot és a logikát.

Hozza létre a projektet.

Konzolalkalmazás létrehozása az új MSBuild feladat használatához

A következő lépés egy olyan alkalmazás létrehozása, amely a feladatot használja.

Hozzon létre egy konzol alkalmazás projektet, és nevezze el PetReaderToolTaskConsoleApp. Válassza ki a kívánt .NET-verziót. Jelölje meg indítási projektként.
Hozzon létre egy osztálytárat projektet a PetRestApiClientnevű kód létrehozásához. Használja a .NET Standardot.
A PetReaderToolTaskConsoleApp projektben állítson be egy projektfüggőséget PetRestApiClient-hez.
A PetRestApiClient projektben hozzon létre egy mappát PetRestApiClient. Ez a mappa tartalmazza a létrehozott kódot.
Törölje az automatikusan létrehozott Class1.cs.
A PetRestApiClient-re adja hozzá a következő NuGet-csomagokat:
- A létrehozott kliens fordításához szükséges a Newtonsoft.Json
- A létrehozott kliens fordításához szükséges System.ComponentModel.Annotations
A PetRestApiClient projektben hozzon létre egy petshop-openapi-spec.json nevű szövegfájlt (a projektmappában). Az OpenAPI-specifikáció hozzáadásához másolja a tartalmat innen a fájlba. Szeretjük a reprodukálható buildet, amely csak a bemenettől függ, ahogy azt korábban említettük. Ebben a példában buildelési hibát fog jelezni, ha egy felhasználó egy URL-címet választ OpenAPI-specifikáció bemenetként.

Fontos

Az általános újraépítés nem fog működni. Olyan hibaüzeneteket fog látni, amelyek azt jelzik, hogy nem lehet másolni vagy törölni RestApiClientGenerator.dll-t. Ennek az az oka, hogy ugyanabban a buildelési folyamatban próbálják létrehozni az MBuild egyéni feladatot, amelyben azt használják. Válassza ki a PetReaderToolTaskConsoleApp, és csak azt a projektet építse újra. A másik megoldás az egyéni feladatot egy teljesen független Visual Studio-megoldásba helyezi, ahogyan az oktatóanyagban is tette: Egyéni feladat létrehozása példa.

Másolja a következő kódot a Program.csfájlba:

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

Módosítsa az MSBuild utasítást a feladat meghívásához és a kód létrehozásához. Az alábbi lépések végrehajtásával szerkessze PetRestApiClient.csproj:

Regisztrálja az MSBuild egyéni feladat használatát:

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

Adjon hozzá néhány olyan tulajdonságot, amely a feladat végrehajtásához szükséges:

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

Fontos

Válassza ki a megfelelő NSwagCommandFullPath értéket a rendszer telepítési helye alapján.

Adjon hozzá MSBuild célpontot az ügyfél generálásához a build folyamat során. Ezt a célt kell végrehajtani az CoreCompile végrehajtása előtt, hogy létrehozzuk a fordításban használt kódot.

<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 és Outputnövekményes buildelésikapcsolódnak, és a forceReGenerationOnRebuild cél törli a létrehozott fájlt CoreCleanután, ami az újraépítési művelet során újragenerálásra kényszeríti az ügyfelet.

Válassza ki a PetReaderToolTaskConsoleApp, és csak azt a projektet építse újra. Most jön létre az ügyfélkód, és a kód lefordítódik. Végrehajthatja, és megtekintheti, hogyan működik. Ez a kód egy fájlból hozza létre a kódot, és ez engedélyezett.
Ebben a lépésben a paraméterérvényesítést mutatja be. A PetRestApiClient.csprojfájlban módosítsa a $(PetClientInputOpenApiSpec) tulajdonságot, hogy az URL-t használja.
```
  <PetClientInputOpenApiSpec>https://petstore.swagger.io/v2/swagger.json</PetClientInputOpenApiSpec>
```
Válassza ki a PetReaderToolTaskConsoleApp, és csak azt a projektet építse újra. A "URL-cím nem engedélyezett" hibaüzenet jelenik meg a tervezési követelményeknek megfelelően.

A kód letöltése

Telepítse az NSwag parancssori eszközt. Ezután szükség lesz a teljes elérési útra ahhoz a könyvtárhoz, ahol NSwag.exe található. Ezután szerkessze PetRestApiClient.csproj, és válassza ki a megfelelő $(NSwagCommandFullPath) értéket a számítógép telepítési útvonala alapján. Most válassza ki a RestApiClientGenerator, és csak azt a projektet hozza létre, majd végül válassza ki és építse újra PetReaderToolTaskConsoleApp. Végrehajthatja PetReaderToolTaskConsoleApp. annak ellenőrzéséhez, hogy minden a várt módon működik-e.

Következő lépések

Érdemes lehet az egyéni feladatot NuGet-csomagként közzétenni.

oktatóanyag: Egyéni feladat létrehozása

Vagy megtudhatja, hogyan tesztelhet egyéni feladatokat.

egyéni MSBuild-feladat tesztelése

Visszacsatolás

Hasznos volt ez az oldal?

Last updated on 2025-12-12