Öğretici: REST API istemcisi oluşturma

Makale
08/25/2023

REST API kullanan bir uygulama çok yaygın bir senaryodur. Genellikle, uygulamanızın REST API'yi çağırmak için kullanabileceği istemci kodu oluşturmanız gerekir. Bu öğreticide, MSBuild kullanarak derleme işlemi sırasında REST API istemcisini otomatik olarak oluşturmayı öğreneceksiniz. REST API için istemci kodu oluşturan NSwag aracını kullanacaksınız.

Örnek kodun tamamı, GitHub'daki .NET örnekleri deposunda REST API istemci oluşturma aşamasında kullanılabilir.

Örnekte, OpenAPI belirtimi yayımlayan genel Pet Store API'sini kullanan bir konsol uygulaması gösterilmektedir.

Öğreticide görevler, hedefler, özellikler veya çalışma zamanları gibi MSBuild terimleri hakkında temel bilgiler varsayılır; gerekli arka plan için MSBuild Kavramları makalesine bakın.

Derlemenin bir parçası olarak bir komut satırı aracı çalıştırmak istediğinizde, göz önünde bulundurmanız gereken iki yaklaşım vardır. Bunlardan biri, bir komut satırı aracı çalıştırmanıza ve parametrelerini belirtmenize olanak tanıyan MSBuild Exec görevini kullanmaktır. Diğer yöntem, ToolTask'ten türetilen ve size daha fazla denetim sağlayan özel bir görev oluşturmaktır.

Ön koşullar

Görevler, hedefler ve özellikler gibi MSBuild kavramlarını anlamanız gerekir. Bkz. MSBuild kavramları.

Örnekler, Visual Studio ile birlikte yüklenen ancak ayrı olarak da yüklenebilen MSBuild gerektirir. Bkz. Visual Studio olmadan MSBuild'i indirme.

Seçenek 1: Exec görevi

Exec görevi yalnızca belirtilen bağımsız değişkenlerle belirtilen işlemi çağırır, tamamlanmasını bekler ve işlem başarıyla tamamlanırsa ve false hata oluşursa döndürürtrue.

NSwag kod oluşturma MSBuild'den kullanılabilir; Bkz . NSwag.MSBuild.

Kodun tamamı PetReaderExecTaskExample klasöründedir; indirebilir ve bir göz atabilirsiniz. Bu öğreticide adım adım ilerleyip kavramları öğreneceksiniz.

adlı PetReaderExecTaskExampleyeni bir konsol uygulaması oluşturun. .NET 6.0 veya üzerini kullanın.
Aynı çözümde başka bir proje oluşturun: PetShopRestClient (Bu çözüm, oluşturulan istemciyi kitaplık olarak içerecektir). Bu proje için .NET Standard 2.1 kullanın. Oluşturulan istemci .NET Standard 2.0'da derlenmemiş.
projesine PetReaderExecTaskExample ve projeye bir proje bağımlılığı PetShopRestClient ekleyin.
PetShopRestClient Projeye aşağıdaki NuGet paketlerini ekleyin:
- MSBuild'den kod oluşturucuya erişim sağlayan Nswag.MSBuild
- Newtonsoft.Json, oluşturulan istemciyi derlemek için gerekli
- Oluşturulan istemciyi derlemek için gereken System.ComponentModel.Annotations
ProjedePetShopRestClient, kod oluşturma için bir klasör (adlıPetShopRestClient) ekleyin ve otomatik olarak oluşturulan Class1.cs dosyasını silin.
Projenin kökünde petshop-openapi-spec.json adlı bir metin dosyası oluşturun. Buradan OpenApi belirtimini kopyalayın ve dosyaya kaydedin. Derleme sırasında çevrimiçi okumak yerine belirtimin anlık görüntüsünü kopyalamak en iyisidir. Her zaman yalnızca girişe bağlı tutarlı bir şekilde yeniden üretilebilir bir derleme istiyorsunuz. API'yi doğrudan kullanmak, bugün çalışan bir derlemeyi aynı kaynaktan yarın başarısız olan bir derlemeye dönüştürebilir. Petshop-openapi-spec.json dosyasına kaydedilen anlık görüntü, belirtim değişse bile yine de derlenecek bir sürüme sahip olmamıza olanak sağlar.
Ardından, PetShopRestClient.csproj dosyasını değiştirin ve derleme işlemi sırasında istemciyi oluşturmak için bir MSBuild hedefleri ekleyin.

İlk olarak, istemci oluşturma için yararlı olan bazı özellikler ekleyin:
```
 <PropertyGroup>
     <PetOpenApiSpecLocation>petshop-openapi-spec.json</PetOpenApiSpecLocation>
     <PetClientClassName>PetShopRestClient</PetClientClassName>
     <PetClientNamespace>PetShopRestClient</PetClientNamespace>
     <PetClientOutputDirectory>PetShopRestClient</PetClientOutputDirectory>
 </PropertyGroup>
```
Aşağıdaki hedefleri ekleyin:
```
 <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>
```
Bu hedefin derleme sırasını tanımlamak için BeforeTarget ve AfterTarget özniteliklerini kullandığına dikkat edin. Adlı generatePetClient ilk hedef çekirdek derleme hedeflerinden önce yürütülür, bu nedenle kaynak derleyici yürütülmeden önce oluşturulur. Giriş ve çıkış parametresi Artımlı Derleme ile ilgilidir. MSBuild, giriş dosyalarının zaman damgalarını çıkış dosyalarının zaman damgalarıyla karşılaştırabilir ve hedefi atlayıp atlamayacağını, oluşturup oluşturmayacağını veya kısmen yeniden oluşturup oluşturmayacağını belirleyebilir.

Projenize NuGet paketini yükledikten NSwag.MSBuild sonra, dosyanızdaki .csproj değişkenini $(NSwagExe) kullanarak NSwag komut satırı aracını bir MSBuild hedefinde çalıştırabilirsiniz. Bu şekilde, araçlar NuGet aracılığıyla kolayca güncelleştirilebilir. Burada, istemci Rest Api'sini Exec oluşturmak için gerekli parametrelerle NSwag programını yürütmek için MSBuild görevini kullanıyorsunuz. Bkz. NSwag komutu ve parametreleri.

Etiketinize ekleme ConsoleToMsBuild="true" ve <Exec> ardından bir etiketteki <Output> parametresini kullanarak çıkışı yakalama çıkışını ConsoleOutput<Exec> yakalayabilirsiniz. ConsoleOutput çıktıyı olarak Itemdöndürür. Boşluk kırpıldı. ConsoleOutput doğru olduğunda ConsoleToMSBuild etkinleştirilir.

adlı forceReGenerationOnRebuild ikinci hedef, yeniden oluşturma hedef yürütmesi sırasında oluşturulan kodun yeniden oluşturulmasını zorlamak için temizleme sırasında oluşturulan sınıfı siler. Bu hedef, MSBuild önceden tanımlanmış hedef sonrasında CoreClean çalışır.
Bir Visual Studio Çözümü yeniden derlemesi yürütür ve klasörde oluşturulan istemciyi PetShopRestClient görürsünüz.

Şimdi oluşturulan istemciyi kullanın. Program.cs istemcisine gidin ve aşağıdaki kodu kopyalayın:

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

Dekont

Bu kod, gösterilmesi basit olduğundan kullanır new HttpClient() , ancak gerçek kod için en iyi yöntem değildir. En iyi yöntem, Kaynak Tükenmesi veya Eski DNS sorunları gibi isteklerin HttpClient bilinen sorunlarını gideren bir HttpClient nesne oluşturmak için kullanmaktırHttpClientFactory. Bkz . Dayanıklı HTTP isteklerini uygulamak için IHttpClientFactory kullanma.

Tebrikler! Şimdi, nasıl çalıştığını görmek için programı yürütebilirsiniz.

Seçenek 2: ToolTask'ten türetilen özel görev

Çoğu durumda, görevi kullanmak Exec REST API istemci kodu oluşturma gibi bir şey yapmak için bir dış araç yürütmek için yeterlidir, ancak yalnızca giriş olarak mutlak bir Windows yolu kullanmıyorsanız REST API istemci kodu oluşturma işlemine izin vermek istiyorsanız ne olur? Ya da yürütülebilir dosyanın bulunduğu bir şekilde hesaplamanız gerekiyorsa ne yapmanız gerekir? Ek iş yapmak için kod yürütmeniz gereken herhangi bir durum olduğunda, MSBuild Araç Görevi en iyi çözümdür. ToolTask sınıfı, MSBuild'den türetilen bir soyut sınıftırTask. Özel bir MSBuild görevi oluşturan somut bir alt sınıf tanımlayabilirsiniz. Bu yaklaşım, komut yürütmeye hazırlanmak için gereken tüm kodları çalıştırmanıza olanak tanır. Önce Kod oluşturma için özel görev oluşturma öğreticisini okumalısınız.

MSBuild ToolTask'ten türetilen ve REST API istemcisi oluşturacak özel bir görev oluşturacaksınız, ancak bir http adresi kullanarak OpenApi belirtimine başvurmaya çalışırsanız hata yayacak şekilde tasarlanır. NSwag, OpenApi belirtimi girişi olarak bir http adresini destekler, ancak bu örneğin amaçları doğrultusunda buna izin vermemeye yönelik bir tasarım gereksinimi olduğunu varsayalım.

Kodun tamamı bu PetReaderToolTaskExample klasördedir; indirebilir ve bir göz atabilirsiniz. Bu öğreticide adım adım ilerleyecek ve kendi senaryolarınıza uygulayabileceğiniz bazı kavramları öğreneceksiniz.

Özel görev için yeni bir Visual Studio Projesi oluşturun. Bunu çağırın RestApiClientGeneratorve .NET Standard 2.0 ile Sınıf Kitaplığı (C#) şablonunu kullanın. Çözümü PetReaderToolTaskExampleolarak adlandırın.
Otomatik olarak oluşturulan Class1.cs dosyasını silin.

Microsoft.Build.Utilities.Core NuGet paketlerini ekleyin:

adlı bir sınıf oluşturma RestApiClientGenerator

MSBuild'den ToolTask devralın ve aşağıdaki kodda gösterildiği gibi soyut yöntemi uygulayın:

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

Aşağıdaki parametreleri ekleyin:

InputOpenApiSpec, burada belirtim
ClientClassName, oluşturulan sınıfın adı
ClientNamespaceName, sınıfın oluşturulduğu ad alanı
FolderClientClass, sınıfın bulunacağı klasörün yolu
NSwagCommandFullPath, NSwag.exe dosyasının bulunduğu dizinin tam yolu

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

NSwag komut satırı aracını yükleyin. NSwag.exe dosyasının bulunduğu dizinin tam yolunu kullanmanız gerekir.

Soyut yöntemleri uygulayın:

   protected override string ToolName => "RestApiClientGenerator";

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

Geçersiz kılabileceğiniz birçok yöntem vardır. Geçerli uygulama için şu ikisini tanımlayın:

Komut parametresini tanımlayın:

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

Parametre doğrulama:

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

Dekont

Bu basit doğrulama, MSBuild dosyasında başka bir şekilde yapılabilir, ancak bunu C# kodunda yapmanız ve komutu ve mantığı kapsüllemeleri önerilir.

Projeyi derleyin.

Yeni MSBuild görevini kullanmak için bir konsol uygulaması oluşturma

Sonraki adım, görevi kullanan bir uygulama oluşturmaktır.

Bir Konsol Uygulaması projesi oluşturun ve adlı bir proje oluşturun PetReaderToolTaskConsoleApp. .NET 6.0'ı seçin. Başlangıç projesi olarak işaretleyin.
adlı PetRestApiClientkodu oluşturmak için bir Sınıf Kitaplığı projesi oluşturun. .NET Standard 2.1 kullanın.
Projede PetReaderToolTaskConsoleApp , öğesine PetRestApiClientbir proje bağımlılığı oluşturun.
Projede PetRestApiClient bir klasör PetRestApiClientoluşturun. Bu klasör, oluşturulan kodu içerir.
Otomatik olarak oluşturulan Class1.cs dosyasını silin.
üzerinde PetRestApiClientaşağıdaki NuGet paketlerini ekleyin:
- Newtonsoft.Json, oluşturulan istemciyi derlemek için gerekli
- Oluşturulan istemciyi derlemek için gereken System.ComponentModel.Annotations
Projede PetRestApiClient petshop-openapi-spec.json adlı bir metin dosyası oluşturun (proje klasöründe). OpenApi belirtimini eklemek için buradaki içeriği dosyaya kopyalayın. Daha önce açıklandığı gibi yalnızca girişe bağlı olan yeniden üretilebilir bir derlemeyi seviyoruz. Bu örnekte, kullanıcı OpenApi belirtimi girişi olarak bir URL seçerse derleme hatası oluşturacaksınız.

Önemli

Genel bir yeniden derleme işe yaramaz. .dll' dosyasını kopyalayamadı veya silemiyor RestApiClientGeneratorhatalarıyla karşılaşırsınız. Bunun nedeni, MBuild özel görevini kullanan aynı derleme işleminde derlemeye çalışmasıdır. Yalnızca bu projeyi seçin PetReaderToolTaskConsoleApp ve yeniden oluşturun. Başka bir çözüm, Öğretici: Özel görev örneği oluşturma bölümünde yaptığınız gibi özel görevi tamamen bağımsız bir Visual Studio çözümüne yerleştirmektir.

Aşağıdaki kodu Program.cs dosyasına kopyalayın:

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

GÖREVI çağırmak ve kodu oluşturmak için MSBuild yönergelerini değiştirin. Şu adımları izleyerek PetRestApiClient.csproj dosyasını düzenleyin:

MSBuild özel görevinin kullanımını kaydedin:

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

Görevi yürütmek için gereken bazı özellikleri ekleyin:

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

Önemli

Sisteminizdeki yükleme konumuna göre uygun NSwagCommandFullPath değeri seçin.

Derleme işlemi sırasında istemciyi oluşturmak için bir MSBuild hedefi ekleyin. Bu hedef, derlemede kullanılan kodu oluşturmak için yürütülmeden önce CoreCompile yürütülmelidir.

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

Inputve Output Artımlı Derleme ile ilişkilidir veforceReGenerationOnRebuild hedef, yeniden oluşturma işlemi sırasında istemciyi yeniden oluşturulmaya zorlayan ve sonrasında oluşturulan dosyayı CoreCleansiler.

Yalnızca bu projeyi seçin PetReaderToolTaskConsoleApp ve yeniden oluşturun. Şimdi, istemci kodu oluşturulur ve kod derler. Yürütebilir ve nasıl çalıştığını görebilirsiniz. Bu kod, kodu bir dosyadan oluşturur ve buna izin verilir.
Bu adımda parametre doğrulamasını göstereceksiniz. PetRestApiClient.csproj dosyasında url'yi kullanmak için özelliğini $(PetClientInputOpenApiSpec) değiştirin:
```
  <PetClientInputOpenApiSpec>https://petstore.swagger.io/v2/swagger.json</PetClientInputOpenApiSpec>
```
Yalnızca bu projeyi seçin PetReaderToolTaskConsoleApp ve yeniden oluşturun. Tasarım gereksinimine uygun olarak "URL'ye izin verilmiyor" hatasını alırsınız.

Kodu indirme

NSwag komut satırı aracını yükleyin. Ardından, NSwag.exe dosyasının bulunduğu dizinin tam yolunu kullanmanız gerekir. Bundan sonra PetRestApiClient.csproj dosyasını düzenleyin ve bilgisayarınızdaki yükleme yoluna göre uygun $(NSwagCommandFullPath) değeri seçin. Şimdi yalnızca bu projeyi seçip RestApiClientGenerator derleyin ve son olarak öğesini seçip yeniden derleyin PetReaderToolTaskConsoleApp. komutunu yürütebilirsiniz PetReaderToolTaskConsoleApp. her şeyin beklendiği gibi çalıştığını doğrulayın.

Sonraki adımlar

Özel görevinizi NuGet paketi olarak yayımlamak isteyebilirsiniz.

Öğretici: Özel görev oluşturma

İsterseniz özel bir görevi test etmeyi de öğrenebilirsiniz.

Özel bir MSBuild görevini test edin

Aracılığıyla paylaş