Öğretici: REST API istemcisi oluşturma

2025-06-12

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 bir araç olan NSwagkullanacaksınız.

GitHub'daki .NET örnekleri deposunda bulunan REST API istemci oluşturma altında tam örnek kodu mevcuttur.

Örnekte, OpenAPI belirtimini yayımlayan genelPet 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ı makalesinebakı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 MSBuildExec görevini kullanmaktır. Diğer yöntem, size daha fazla kontrol sağlayan ToolTasktüretilmiş özel bir görev oluşturmaktır.

Önkoş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. Visual Studio olmadan MSBuild'i indirmebölümüne bakın.

Seçenek 1: Yönetici görevi

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

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

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

PetReaderExecTaskExampleadlı yeni 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ş.
PetReaderExecTaskExample projesine bir proje bağımlılığı ekleyin ve PetShopRestClient projeye bir proje bağımlılığı ekleyin.
PetShopRestClient projesine 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
PetShopRestClient projesinde, kod oluşturma için bir klasör (PetShopRestClientadlı) ekleyin ve otomatik olarak oluşturulan Class1.cs silin.
Projenin kökünde petshop-openapi-spec.json adlı bir metin dosyası oluşturun. buradaki OpenAPI belirtimini kopyalayın ve dosyaya kaydedin. Derleme sırasında çevrimiçi okumak yerine spesifikasyonun anlık görüntüsünü kopyalamak daha iyidir. 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'ye kaydedilen anlık görüntü, belirtim değişse bile derlenebilecek bir sürümümüzün olmasını sağlar.
Ardından PetShopRestClient.csproj dosyasını değiştirin ve derleme işlemi sırasında istemciyi oluşturmak için 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. generatePetClient adlı ilk hedef, çekirdek derleme hedefine başlamadan önce yürütülecek, böylece derleyici çalıştırılmadan önce kaynak oluşturulacaktır. Giriş ve çıkış parametresi Artımlı Derlemeile 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 NSwag.MSBuild NuGet paketini yükledikten sonra, .csproj dosyanızdaki $(NSwagExe) değişkenini kullanarak MSBuild hedefinde NSwag komut satırı aracını çalıştırabilirsiniz. Bu şekilde, araçlar NuGet aracılığıyla kolayca güncelleştirilebilir. Burada, istemci Rest Api'sini oluşturmak için gerekli parametrelerle NSwag programını yürütmek için Exec MSBuild görevini kullanıyorsunuz. bkz. NSwag komutu ve parametreleri.

<Exec> <Exec> etiketinize ConsoleToMsBuild="true" ekleyip <Output> etiketindeki ConsoleOutput parametresini kullanarak çıkışı yakalayabilirsiniz. ConsoleOutput çıktıyı Itemolarak döndürür. Boşluk kırpıldı. ConsoleToMSBuild doğru olduğunda ConsoleOutput etkinleştirilir.

forceReGenerationOnRebuild adlı 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, CoreClean MSBuild önceden tanımlanmış hedef sonrasında çalışır.
Bir Visual Studio Çözümü yeniden derlemesi yürütür ve PetShopRestClient klasöründe oluşturulan istemciyi görürsünüz.

Şimdi oluşturulan istemciyi kullanın. İstemci Program.csdosyasına git 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}");
       }
   }
}

Not

Bu kod new HttpClient() kullanır çünkü gösterilmesi kolaydır, ancak gerçek kod için en iyi yöntem değildir. En iyi yöntem, HttpClientFactory kullanarak Kaynak Tükenmesi veya Eski DNS sorunları gibi bilinen HttpClient isteklerinin sorunlarını gideren bir HttpClient nesnesi oluşturmaktır. Dayanıklı HTTP isteklerini uygulamak için IHttpClientFactory kullanma, bkz. .

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

Birçok durumda, Exec görevini, REST API istemci kodu oluşturma gibi bir işlemin gerçekleştirilmesi için bir harici araç çalıştırmak amacıyla kullanmak yeterlidir. Ancak, yalnızca giriş olarak mutlak bir Windows yolu kullanmadığınızda REST API istemci kodu oluşturmasına izin vermek isterseniz ne yapmalısınız? Ya yürütülebilir dosyanın yerini hesaplamanız gerekiyorsa? 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 Task'den türetilen bir soyut sınıftır. Ö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. İlk olarak kod oluşturma için özel görev oluşturma öğreticisini okumalısınız.

MSBuild ToolTask'den türetilmiş özel bir görev oluşturacaksınız, bu görev bir REST API istemcisi oluşturacak ancak bir http adresi kullanarak OpenAPI belirtimine başvurmaya çalışırsanız bir hata vermek üzere tasarlanmıştı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öründedir; uygulamasını indirip 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. RestApiClientGenerator olarak adlandırın ve .NET Standard 2.0 ile Sınıf Kitaplığı (C#) şablonunu kullanın. Çözümü PetReaderToolTaskExampleolarak adlandırın.
Otomatik olarak oluşturulan Class1.cssil.

Microsoft.Build.Utilities.Core NuGet paketlerini ekleyin:

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

MSBuild 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 belirtimidir
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, yani NSwag.exe'ı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'ın bulunduğu dizinin tam yolunu bilmeniz 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;
}

Not

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 oluşturun.

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 PetReaderToolTaskConsoleAppolarak adlandırın. .NET 6.0'ı seçin. Başlangıç projesi olarak işaretleyin.
PetRestApiClientadlı kodu oluşturmak için bir Sınıf Kitaplığı projesi oluşturun. .NET Standard 2.1 kullanın.
PetReaderToolTaskConsoleApp projesinde PetRestApiClientiçin bir proje bağımlılığı oluşturun.
PetRestApiClient projesinde PetRestApiClientbir klasör oluşturun. Bu klasör, oluşturulan kodu içerir.
Şu otomatik olarak oluşturulan Class1.csdosyasını sil.
PetRestApiClientüzerinde aşağıdaki NuGet paketlerini ekleyin:
- Newtonsoft.Json, oluşturulan istemciyi derlemek için gerekli
- Oluşturulan istemciyi derlemek için gereken System.ComponentModel.Annotations
PetRestApiClient projesinde 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 bir derleme hatası oluşturacaksınız.

Önemli

Genel bir yeniden derleme işe yaramaz. 'RestApiClientGenerator.dll'in kopyalanamaması veya silinememesiyle ilgili hatalar görürsünüz.' Bunun nedeni, MBuild özel görevini kullanan aynı derleme işleminde derlemeye çalışmasıdır. PetReaderToolTaskConsoleApp seçin ve yalnızca bu projeyi yeniden oluşturun. Bir diğer çözüm de özel görevi, Öğreticisi: Özel görev oluşturma örnekte yaptığınız gibi tamamen bağımsız bir Visual Studio çözümüne yerleştirmektir.

Aşağıdaki kodu Program.cskopyalayı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 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ğerini seçin.

Derleme süreci sırasında istemciyi oluşturmak için bir MSBuild hedefi ekleyin. Derlemede kullanılan kodu oluşturmak için CoreCompile yürütülmeden önce bu hedef 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>

Input ve Output, Artımlı Derlemeile ilişkilidir ve forceReGenerationOnRebuild hedefi, oluşturulan dosyayı CoreCleansonra siler, bu da istemcinin yeniden oluşturma işlemi sırasında yeniden oluşturulmasını zorunlu kılar.

PetReaderToolTaskConsoleApp seçin ve yalnızca bu projeyi yeniden oluşturun. Şimdi istemci kodu oluşturulur ve kod derlenir. 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.csprojiçinde, URL kullanmak için özellik $(PetClientInputOpenApiSpec)'yi değiştirin.
```
  <PetClientInputOpenApiSpec>https://petstore.swagger.io/v2/swagger.json</PetClientInputOpenApiSpec>
```
PetReaderToolTaskConsoleApp seçin ve yalnızca bu projeyi 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 bulunduğu dizinin tam yoluna ihtiyacınız olacaktır. Bundan sonra, PetRestApiClient.csproj düzenleyin ve bilgisayarınızdaki yükleme yoluna göre uygun $(NSwagCommandFullPath) değerini seçin. Şimdi RestApiClientGenerator seçin ve yalnızca bu projeyi derleyin ve son olarak PetReaderToolTaskConsoleAppöğesini seçip yeniden derleyin. PetReaderToolTaskConsoleAppçalıştırabilirsiniz. her şeyin beklendiği gibi çalıştığını doğrulayın.

Sonraki adımlar

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

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

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

Özelleştirilmiş bir MSBuild görevi test et