Beranda>Kode sumber ASP>Kategori lainnya
Unduh

Generator API Web Klien yang Diketik dengan Kuat menghasilkan kode API klien dalam C# dan TypeScript dari ASP.NET (Core) Web API secara langsung tanpa melibatkan Swagger/OpenAPI atau Swashbuckle, sehingga memaksimalkan dukungan untuk tipe data pendekatan Code First Anda dari ASP.NET Web API .

Produk

Proyek ini menghasilkan produk-produk berikut:

  1. Generator kode untuk API klien yang diketik dengan kuat di C# yang mendukung .NET dan Xamarin.Forms.
  2. Generator kode untuk API klien yang diketik dengan kuat di TypeScript untuk jQuery, Angular 2+, Aurelia, Axios, dan Fetch API.
  3. TypeScript CodeDOM, komponen .NET CodeDOM untuk TypeScript untuk mengembangkan generator kode TypeScript.
  4. POCO2TS.exe, program baris perintah yang menghasilkan antarmuka TypeScript dari kelas POCO.
  5. Fonlow.Poco2Ts, komponen yang menghasilkan antarmuka TypeScript dari kelas POCO.
  6. Plugin untuk jQuery, AXIOS, Fetch API, Aurelia, Angular 2+ serta Angular Typed Reactive Forms.
  7. Fonlow.DataOnlyExtensions dengan konverter JSON untuk menangani skenario hanya tanggal antara klien dan server yang berada di zona waktu berbeda. Paket .NET Framework juga tersedia.

Paket

Kasus Penggunaan dan Unduhan

Produk-produk tersebut sebagian besar dirilis melalui NuGet.

  1. Hasilkan API klien C#, lalu gunakan paket Fonlow.WebApiClientGenCore
  2. Hasilkan API klien TypeScript, lalu gunakan salah satu plugin Fonlow.WebApiClientGenCore:
    1. perpustakaan pembantu jQuery dan HttpClient
    2. Sudut 6+
    3. Angular 6+, ditambah pembuatan FormGroup untuk Formulir Reaktif dengan Deskripsi
    4. aksio
    5. Aurelia
    6. Ambil API
  3. Kembangkan generator kode TypeScript melalui pendekatan CodeDOM, lalu gunakan paket Fonlow.TypeScriptCodeDOMCore.
  4. Kembangkan generator kode TypeScript melalui pendekatan CodeDOM untuk POCO dan lainnya, lalu gunakan paket Fonlow.Poco2TSCore , atau gunakan skrip PowerShell 7.
  5. Hasilkan antarmuka tipe TypeScript, lalu gunakan Poco2TSCore.exe, aplikasi konsol.
  6. Kembangkan fitur yang membaca dokumen XML rakitan .NET, lalu gunakan paket Fonlow.DocCommentCore.

Petunjuk:

  • OpenApiClientGen berdasarkan komponen utama WebApiClientGen adalah spin-off untuk menghasilkan kode API klien dalam C# dan TypeScript sesuai dengan file definisi Spesifikasi Swagger/Open API.
  • WebApiClientGen tidak menggunakan definisi Swagger/OpenAPI, tetapi menghasilkan kode dari info tipe run time dari API Web yang sedang berjalan dari build debug, menghilangkan batasan inheren OpenAPI terhadap tipe .NET dan API Web untuk memberikan pengalaman pengembang yang lebih baik pada ASP. Pengembang API Web NET (Inti).

Perkataan:

  • Pengembangan telah dimulai pada tahun 2015 mendukung .NET Framework, kemudian .NET Core 2. Dan Tag "LastCore31" untuk menandai snapshot terakhir yang mendukung .NET Framework 4.6.2 dan .NET Core 3.1.
  • Mulai 10-02-2021, pengembangan hanya akan mendukung .NET 5 dan seterusnya.
  • Konten Wiki tentang .NET Framework akan disimpan di masa mendatang.

Fitur Utama

  1. Kode API klien yang dihasilkan dipetakan langsung dari metode pengontrol API Web, tipe primitif .NET, dan kelas POCO. Ini mirip dengan apa yang ditawarkan svcutil.exe di WCF.
  2. Komentar dokumen tentang metode pengontrol dan kelas POCO disalin.
  3. Beberapa atribut validasi digunakan untuk menghasilkan komentar dokumen untuk kode TypeScript.

Manfaat Utama untuk Pengalaman Pengembang

  1. WebApiClientGen terintegrasi secara mulus dengan ASP.NET Core Web API dengan sedikit langkah/overhead untuk menyiapkan, memelihara, dan menyinkronkan antara API Web dan API klien, selama RAD atau Pengembangan Perangkat Lunak Agile.
  2. Mendukung semua tipe primitif .NET termasuk desimal.
  3. Mendukung DataTime, DataTimeOffset, DateOnly, Array, Tuple, Objek Dinamis, Kamus, dan KeyValuePair
  4. Kode yang dihasilkan dengan pengetikan kuat tunduk pada pemeriksaan jenis waktu desain dan pemeriksaan jenis waktu kompilasi.
  5. Memberikan abstraksi tingkat tinggi, melindungi pengembang aplikasi dari detail teknis berulang dari praktik RESTful dan kode tradisional panggilan AJAX.
  6. Info meta yang kaya termasuk komentar dokumen membuat IDE intellisense lebih bermanfaat, sehingga pengembang aplikasi tidak perlu lagi membaca dokumen API terpisah.
  7. Komentar dokumen yang dihasilkan berdasarkan atribut validasi .NET.
  8. Komentar dokumen yang dihasilkan berdasarkan tipe numerik, DateOnly, dan GUID untuk kode TypeScript.
  9. Kode TypeScript yang dihasilkan sesuai dengan mode ketat TypeScript, dan kode Angular 2+ yang dihasilkan sesuai dengan mode ketat Angular.

Contoh

  1. kelas POCO
  2. API Web
  3. Kode API C# klien yang dihasilkan
  4. Kode klien menggunakan perpustakaan yang dihasilkan di C#
  5. Model data klien dan API yang dihasilkan dalam TypeScript untuk jQuery, untuk Angular 2, untuk Aurelia dan untuk Axios
  6. Kode klien menggunakan perpustakaan yang dihasilkan di TypeScript
  7. Demo Online dengan Angular Heroes yang dihosting di GitHub.IO berbicara dengan backend nyata

Perkataan:

  1. Kode JavaScript yang dikompilasi dari kode TypeScript yang dihasilkan dapat digunakan dalam aplikasi JS, namun jelas tidak ada informasi tipe yang tersedia, sementara pemrogram aplikasi masih dapat menikmati kecerdasan dan abstraksi dari detail AJAX.
    1. Aplikasi React dan Vue.js biasanya menggunakan Axios atau Fetch API untuk permintaan HTTP. Sejak Juni 2019, babel telah mendukung namespace berkat permintaan tarik ini, jadi Anda seharusnya dapat melakukan pemrograman React TSX dengan kode TypeScript yang dihasilkan.

Konsep

  1. Vendor/pengembang API Web harus menyediakan pustaka API klien kepada pengembang program klien, seperti yang dilakukan Google, Amazon, dll. agar RESTful Web API menjangkau konsumen yang lebih luas (internal dan eksternal) secara efisien.
  2. Bagi pengembang klien, prototipe fungsi klasik seperti ReturnType DoSomething(Type1 t1, Type2 t2 ...) adalah fungsi API, dan sisanya adalah detail implementasi teknis transportasi: TCP/IP, HTTP, SOAP, berorientasi sumber daya, CRUD- berbasis URI, RESTful, XML dan JSON dll. Prototipe fungsi dan bagian dokumen API harus cukup baik untuk memanggil fungsi API.
  3. Semakin baik Anda memisahkan perhatian dalam desain API Web Anda, semakin banyak Anda akan mendapatkan manfaat dari komponen proyek ini untuk memberikan nilai bisnis lebih cepat, dengan lebih sedikit kode buatan tangan, lebih sedikit tugas yang berulang, dan lebih sedikit kemungkinan kesalahan manusia.

Praktik Pemrograman yang Diharapkan

Prototipe Fungsi yang Diketik dengan Kuat

ReturnType DoSomething(Type1 t1, Type2 t2 ...)

		[ HttpGet ]
		[ Route ( "getPerson/{id}" ) ]
		public Person GetPerson ( long id )

Validasi Model melalui Middleware

Daripada menulis kode eksplisit untuk memvalidasi payload permintaan, Anda diharapkan menggunakan middleware untuk memvalidasi. Misalnya: 

 public void ConfigureServices ( IServiceCollection services )
{
	services . AddControllers (
		options =>
		{
			options . Filters . Add ( new ValidateModelAttribute ( ) ) ; // wholesale style to check model binding for all API calls.

Referensi:

  • Validasi Model di ASP.NET Web API
  • Validasi Model di ASP.NET Core MVC dan Razor Pages

Validasi Model melalui ApiControllerAttribute

Misalnya: 

	[ ApiController ]
	[ Route ( "api/[controller]" ) ]
	public class HeroesController : ControllerBase
	{

Kode Status HTTP Non-2xx Ditangani oleh Middleware, opsional

Bahkan jika Anda secara eksplisit menulis kode dalam fungsi API untuk menangani pengecualian dan mengembalikan kode status HTTP non-2xx, Anda harus memiliki jaring pengaman untuk menangkap pengecualian yang tidak tertangkap dan mengembalikan kode status HTTP.

Referensi:

  • Middleware Inti ASP.NET

Prasyarat

Sisi server:

  1. .NET 7/8
  2. Tambahkan CodeGenController.
  3. Dalam kode startup layanan, tambahkan yang berikut ini: 
 services . AddControllers (
	options =>
	{
#if DEBUG
		options . Conventions . Add ( new Fonlow . CodeDom . Web . ApiExplorerVisibilityEnabledConvention ( ) ) ;
#endif
	}
)

Perkataan:

  • Microsoft telah merilis pemutakhiran besar .NET (Core) setiap tahun sejak 2016, perpustakaan dalam repositori ini umumnya akan mengikuti pemutakhiran terbaru sekitar setengah tahun setelahnya.
  • Perpustakaan umum menggunakan .NET satu versi di belakang versi terbaru, sedangkan aplikasi Demo ASP.NET dan rangkaian pengujian integrasi dengan API klien .NET yang dihasilkan menggunakan versi .NET saat ini.

Sisi klien .NET:

  1. .NET Framework 4.5.2, atau Universal Windows, atau Mono.Android, atau Xamarin.iOS, atau .NET Core 2.0/2.1/3 dan .NET 5
  2. Perpustakaan Klien ASP.NET Web API 2.2
  3. Json.NET dari Newtonsoft untuk aplikasi Tipe Konten/json
  4. Alat Bangun Microsoft 2015

NewtonSoft.Json atau System.Text.Json

Pada .NET 7, untuk serialisasi System.Text.Json merakit kembali lebih dari 95% NewtonSoft.Json. Hanya ada beberapa kasus tepi struktur POCO kompleks yang tidak dapat ditangani oleh System.Text.Json.

WebApiClientGen mendukung sisi server dan sisi klien C#. Untuk klien C#, Anda dapat menggunakan "UseSystemTextJson" di pengaturan codegen.

Namun demikian, jika aplikasi Anda melibatkan struktur POCO yang kompleks, menggunakan NewtonSoft.Json adalah pilihan yang aman mulai .NET 7.

Sisi klien TypeScript:

  1. Kompiler TypeScript
  2. jQuery
  3. Sudut 2-17
  4. Aurelia
  5. aksio
  6. Ambil API

Untuk lebih jelasnya, silakan periksa:

  1. WIKI
  2. Pengaturan Dijelaskan
  3. Hasilkan C# .NET Client API untuk ASP.NET Web API
  4. Hasilkan API Klien TypeScript untuk ASP.NET Web API
  5. API Web ASP.NET, Angular2, TypeScript, dan WebApiClientGen
  6. Hasilkan API Klien C# untuk ASP.NET Core Web API
  7. Solusi yang Dimaksudkan untuk Pembatasan yang Disengaja pada Generator Klien OpenAPI yang Diketik dengan Kuat. Artikel ini hanya menggunakan OpenApiClientGen sebagai contoh, sedangkan prinsip dan solusinya dapat diterapkan pada kode yang dihasilkan oleh WebApiClientGen untuk aplikasi klien Anda.
  8. DateOnly di ASP.NET Core 6

Aplikasi Demo

Aplikasi Demo dalam repositori ini terutama untuk menguji WebApiClientGen selama pengembangan. Dan ada aplikasi demo lainnya di repositori berikut, yang menunjukkan bagaimana aplikasi dunia nyata dapat memanfaatkan WebApiClientGen:

  1. Contoh WebApiClientGen untuk .NET Framework, .NET Standard, Xamarin, dan vue TS.
  2. Demo .NET Core untuk ASP.NET Core MVC, Web API, ASP.NET Core + Angular, MAUI, FetchAPI, vue TS, dan React TS.
  3. WebApiClientGen vs Kesombongan

Aplikasi demo ini dipelihara secara aktif dan selalu diperbarui dengan kerangka kerja terbaru. Jika Anda masih menggunakan beberapa kerangka kerja lama seperti Angular 4 atau 5 atau .NET Core 2.0, Anda dapat menavigasi ke masing-masing tag repositori dan melakukan pembayaran.

Tur Pahlawan

Tour of Heroes adalah aplikasi demo tutorial Angular resmi.

Untuk mengilustrasikan pengalaman pemrogram dalam menggunakan WebApiClientGen, aplikasi demo berikut dibuat dengan desain arsitektur serupa untuk fitur fungsional yang sama pada berbagai kerangka pengembangan atau pustaka, namun tetap terhubung dengan backend sebenarnya.

  1. Angular 2+, dan Formulir Reaktif yang Diketik
  2. Xamarin
  3. MAUI. Bermigrasi dari Xamarin Heroes.
  4. Aurelia. Paket pengujian integrasi disertakan.
  5. Bereaksi. Paket pengujian integrasi disertakan.
  6. Blazor Mandiri

NewtonSoft.Json atau System.Text.Json

Meskipun WebApiClientGen mendukung keduanya, dukungan utama telah beralih ke System.Text.Json sejak tahun 2024.

NewtonSoft.Json masih memiliki beberapa keunggulan pada skenario dan konteks tertentu:

  1. Jika Anda memiliki banyak kelas POCO yang didekorasi oleh DataContractAttributes, karena mendukung aplikasi lama, atau mendukung serialisasi XML dan JSON, NewtonSoft.Json memberi Anda dukungan bawaan, sementara System.Text.Json menyediakan beberapa dukungan yang merepotkan dan tidak langsung sejak .NET 7.
  2. Untuk beberapa tipe array dan dinamis, NewtonSoft.Json masih lebih baik.
Memperluas
Informasi Tambahan
Aplikasi Terkait
Direkomendasikan untuk Anda
Informasi Terkait Semua