webapiclientgen

เครื่องสร้าง Client Web API ที่พิมพ์อย่างเข้มงวดจะสร้างโค้ด API ของไคลเอ็นต์ใน C# และ TypeScript จาก ASP.NET (Core) Web API โดยตรงโดยไม่ต้องเกี่ยวข้องกับ Swagger/OpenAPI หรือ Swashbuckle ดังนั้น จึงเพิ่มการสนับสนุนประเภทข้อมูลของโค้ดของคุณให้สูงสุด แนวทางแรกของ ASP.NET Web API .

สินค้า

โครงการนี้นำเสนอผลิตภัณฑ์เหล่านี้:

1. ตัวสร้างโค้ดสำหรับ API ไคลเอนต์ที่พิมพ์อย่างยิ่งใน C# ที่รองรับ .NET และ Xamarin.Forms
2. ตัวสร้างโค้ดสำหรับ API ไคลเอนต์ที่พิมพ์อย่างยิ่งใน TypeScript สำหรับ jQuery, Angular 2+, Aurelia, Axios และ Fetch API
3. TypeScript CodeDOM ซึ่งเป็นส่วนประกอบ .NET CodeDOM สำหรับ TypeScript สำหรับการพัฒนาตัวสร้างโค้ด TypeScript
4. POCO2TS.exe โปรแกรมบรรทัดคำสั่งที่สร้างอินเทอร์เฟซ TypeScript จากคลาส POCO
5. Fonlow.Poco2Ts ซึ่งเป็นส่วนประกอบที่สร้างอินเทอร์เฟซ TypeScript จากคลาส POCO
6. ปลั๊กอินสำหรับ jQuery, AXIOS, Fetch API, Aurelia, Angular 2+ รวมถึงแบบฟอร์มปฏิกิริยาเชิงมุม
7. Fonlow.DataOnlyExtensions พร้อมตัวแปลง JSON สำหรับจัดการวันที่เฉพาะสถานการณ์ระหว่างไคลเอนต์และเซิร์ฟเวอร์ที่อยู่ในเขตเวลาที่ต่างกัน นอกจากนี้ยังมีแพ็คเกจ .NET Framework อีกด้วย

กรณีการใช้งานและการดาวน์โหลด

ผลิตภัณฑ์ส่วนใหญ่เผยแพร่ผ่าน NuGet

1. สร้าง API ไคลเอ็นต์ C# จากนั้นใช้แพ็คเกจ Fonlow.WebApiClientGenCore
2. สร้าง API ไคลเอ็นต์ TypeScript จากนั้นใช้หนึ่งในปลั๊กอินของ Fonlow.WebApiClientGenCore:
   1. ไลบรารีตัวช่วย jQuery และ HttpClient
   2. เชิงมุม 6+
   3. Angular 6+ รวมถึงการสร้าง FormGroup สำหรับแบบฟอร์มโต้ตอบพร้อมคำอธิบาย
   4. แอกซิส
   5. ออเรเลีย
   6. ดึงข้อมูล API
3. พัฒนาตัวสร้างโค้ด TypeScript ด้วยวิธี CodeDOM จากนั้นใช้แพ็คเกจ Fonlow.TypeScriptCodeDOMCore
4. พัฒนาตัวสร้างโค้ด TypeScript ด้วยวิธี CodeDOM สำหรับ POCO และอื่นๆ จากนั้นใช้แพ็คเกจ Fonlow.Poco2TSCore หรือใช้สคริปต์ PowerShell 7
5. สร้างอินเทอร์เฟซประเภท TypeScript จากนั้นใช้ Poco2TSCore.exe ซึ่งเป็นแอปคอนโซล
6. พัฒนาคุณสมบัติที่อ่านเอกสาร XML ของแอสเซมบลี .NET จากนั้นใช้แพ็คเกจ Fonlow.DocCommentCore

คำแนะนำ:

• OpenApiClientGen ที่ใช้ส่วนประกอบหลักของ WebApiClientGen เป็นการแยกส่วนสำหรับการสร้างโค้ด API ไคลเอ็นต์ใน C# และ TypeScript ตามไฟล์คำจำกัดความของ Swagger/Open API Specification
• WebApiClientGen ไม่ได้ใช้คำจำกัดความ Swagger / OpenAPI แต่สร้างโค้ดจากข้อมูลประเภทรันไทม์ของ Web API ที่ทำงานอยู่ของบิลด์ดีบัก กำจัดข้อจำกัดโดยธรรมชาติของ OpenAPI กับประเภท .NET และ Web API เพื่อมอบประสบการณ์นักพัฒนาที่ดีขึ้นให้กับ ASP นักพัฒนาเว็บ API NET (Core)

หมายเหตุ:

• การพัฒนาเริ่มต้นในปี 2558 โดยรองรับ .NET Framework จากนั้นเป็น .NET Core 2 และแท็ก "LastCore31" คือการทำเครื่องหมายสแน็ปช็อตสุดท้ายที่รองรับ .NET Framework 4.6.2 และ .NET Core 3.1
• เริ่มตั้งแต่ 10-02-2021 การพัฒนาจะรองรับเฉพาะ .NET 5 ขึ้นไป
• เนื้อหา Wiki เกี่ยวกับ .NET Framework จะถูกเก็บไว้ในอนาคตอันใกล้

คุณสมบัติที่สำคัญ

1. รหัส Client API ที่สร้างขึ้นจะถูกแมปโดยตรงจากวิธีการควบคุม Web API, ประเภทดั้งเดิมของ .NET และคลาส POCO สิ่งนี้คล้ายกับสิ่งที่ svcutil.exe ใน WCF นำเสนอ
2. ความคิดเห็นของเอกสารเกี่ยวกับวิธีการควบคุมและคลาส POCO จะถูกคัดลอก
3. คุณลักษณะการตรวจสอบความถูกต้องบางอย่างใช้เพื่อสร้างความคิดเห็นเกี่ยวกับเอกสารสำหรับรหัส TypeScript

ประโยชน์หลักสำหรับประสบการณ์ของนักพัฒนา

1. WebApiClientGen ผสานรวมกับ ASP.NET Core Web API ได้อย่างราบรื่น โดยมีขั้นตอน/ค่าใช้จ่ายเพียงเล็กน้อยในการตั้งค่า บำรุงรักษา และซิงโครไนซ์ระหว่าง Web API และ API ไคลเอนต์ ในระหว่าง RAD หรือการพัฒนาซอฟต์แวร์แบบ Agile
2. รองรับ .NET พื้นฐานทุกประเภทรวมถึงทศนิยม
3. รองรับ DataTime, DataTimeOffset, DateOnly, Array, Tuple, Dynamic Object, Dictionary และ KeyValuePair
4. รหัสที่สร้างด้วยการพิมพ์ที่เข้มงวดจะต้องได้รับการตรวจสอบประเภทเวลาออกแบบและการตรวจสอบประเภทเวลาคอมไพล์
5. ให้นามธรรมในระดับสูง ปกป้องนักพัฒนาแอปพลิเคชันจากรายละเอียดทางเทคนิคที่ซ้ำๆ ของแนวปฏิบัติ RESTful และโค้ดดั้งเดิมของการเรียก AJAX
6. ข้อมูลเมตาที่สมบูรณ์รวมถึงความคิดเห็นของเอกสารทำให้ IDE Intellisense มีประโยชน์มากขึ้น ดังนั้นนักพัฒนาแอปพลิเคชันจึงไม่จำเป็นต้องอ่านเอกสาร API ที่แยกจากกันน้อยลง
7. ความคิดเห็นของเอกสารที่สร้างขึ้นตามแอตทริบิวต์การตรวจสอบความถูกต้องของ .NET
8. ความคิดเห็นของเอกสารที่สร้างขึ้นตามประเภทตัวเลข DateOnly และ GUID สำหรับรหัส TypeScript
9. รหัส TypeScript ที่สร้างขึ้นสอดคล้องกับโหมดเข้มงวดของ TypeScript และโค้ด Angular 2+ ที่สร้างขึ้นสอดคล้องกับโหมดเข้มงวดของ Angular

ตัวอย่าง

1. คลาส POCO
2. เว็บเอพีไอ
3. รหัส C# ของไคลเอ็นต์ API ที่สร้างขึ้น
4. รหัสลูกค้าโดยใช้ไลบรารีที่สร้างขึ้นใน C #
5. สร้างโมเดลข้อมูลไคลเอ็นต์และ API ใน TypeScript สำหรับ jQuery, สำหรับ Angular 2, สำหรับ Aurelia และสำหรับ Axios
6. รหัสลูกค้าโดยใช้ไลบรารีที่สร้างขึ้นใน TypeScript
7. การสาธิตออนไลน์กับ Angular Heroes ที่โฮสต์ใน GitHub.IO พูดคุยกับแบ็กเอนด์จริง

หมายเหตุ:

1. รหัส JavaScript ที่คอมไพล์จากรหัส TypeScript ที่สร้างขึ้นสามารถนำมาใช้ในแอปพลิเคชัน JS ได้ อย่างไรก็ตาม เห็นได้ชัดว่าจะไม่มีข้อมูลประเภท ในขณะที่โปรแกรมเมอร์แอปพลิเคชันอาจยังคงเพลิดเพลินกับสติปัญญาและนามธรรมจากรายละเอียด AJAX
   1. โดยทั่วไปแอปพลิเคชัน React และ Vue.js จะใช้ Axios หรือ Fetch API สำหรับคำขอ HTTP ตั้งแต่เดือนมิถุนายน 2019 บาเบลได้รองรับเนมสเปซด้วยคำขอดึงนี้ ดังนั้นคุณควรจะสามารถทำการเขียนโปรแกรม React TSX ด้วยโค้ด TypeScript ที่สร้างขึ้นได้

แนวคิด

1. ผู้จำหน่าย / นักพัฒนา Web API ควรจัดเตรียมไลบรารี API ของไคลเอนต์ให้กับผู้พัฒนาโปรแกรมไคลเอนต์ เช่นเดียวกับที่ Google และ Amazon ฯลฯ จะทำเพื่อทำให้ RESTful Web API เข้าถึงผู้บริโภคในวงกว้าง (ภายในและภายนอก) ได้อย่างมีประสิทธิภาพ
2. สำหรับนักพัฒนาไคลเอนต์ ฟังก์ชันต้นแบบแบบคลาสสิกเช่น ReturnType DoSomething(Type1 t1, Type2 t2 ...) คือฟังก์ชัน API และส่วนที่เหลือเป็นรายละเอียดการใช้งานทางเทคนิคของการขนส่ง: TCP/IP, HTTP, SOAP, เน้นทรัพยากร, CRUD- URI พื้นฐาน, RESTful, XML และ JSON เป็นต้น ต้นแบบฟังก์ชันและเอกสาร API ส่วนหนึ่งควรจะดีเพียงพอสำหรับการเรียกใช้ฟังก์ชัน API
3. ยิ่งคุณแยกข้อกังวลในการออกแบบ Web API ได้ดีเท่าไร คุณจะยิ่งได้รับประโยชน์จากส่วนประกอบของโปรเจ็กต์นี้มากขึ้นเท่านั้น เพื่อส่งมอบคุณค่าทางธุรกิจได้เร็วยิ่งขึ้น ด้วยโค้ดที่จัดทำขึ้นด้วยมือน้อยลง งานซ้ำซ้อนน้อยลง และโอกาสที่จะผิดพลาดของมนุษย์น้อยลง

แนวทางปฏิบัติด้านการเขียนโปรแกรมที่คาดหวัง

ต้นแบบฟังก์ชันที่พิมพ์อย่างแน่นหนา

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

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

การตรวจสอบโมเดลผ่านมิดเดิลแวร์

แทนที่จะเขียนโค้ดที่ชัดเจนในการตรวจสอบเพย์โหลดของคำขอ เราคาดหวังให้คุณใช้มิดเดิลแวร์ในการตรวจสอบ ตัวอย่างเช่น:

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

อ้างอิง:

• การตรวจสอบโมเดลใน ASP.NET Web API
• การตรวจสอบความถูกต้องของโมเดลใน ASP.NET Core MVC และ Razor Pages

การตรวจสอบโมเดลผ่าน ApiControllerAttribute

ตัวอย่างเช่น:

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

รหัสสถานะ HTTP ที่ไม่ใช่ 2xx จัดการโดยมิดเดิลแวร์ เป็นทางเลือก

แม้ว่าคุณจะเขียนโค้ดอย่างชัดเจนในฟังก์ชัน API เพื่อจัดการกับข้อยกเว้นและส่งคืนรหัสสถานะ HTTP ที่ไม่ใช่ 2xx คุณก็ควรมีเครือข่ายที่ปลอดภัยในการตรวจจับข้อยกเว้นที่ไม่ถูกตรวจจับและส่งคืนรหัสสถานะ HTTP

อ้างอิง:

• ASP.NET คอร์มิดเดิลแวร์

ข้อกำหนดเบื้องต้น

ฝั่งเซิร์ฟเวอร์:

1. .NET 7/8
2. เพิ่ม CodeGenController
3. ในรหัสเริ่มต้นบริการ ให้เพิ่มข้อมูลต่อไปนี้:

 services . AddControllers (
	options =>
	{
#if DEBUG
		options . Conventions . Add ( new Fonlow . CodeDom . Web . ApiExplorerVisibilityEnabledConvention ( ) ) ;
#endif
	}
)

หมายเหตุ:

• Microsoft เปิดตัวการอัปเกรดครั้งใหญ่ของ .NET (Core) ทุกปีตั้งแต่ปี 2559 โดยทั่วไปไลบรารีในพื้นที่เก็บข้อมูลนี้จะตามมาด้วยการอัปเดตล่าสุดประมาณครึ่งปีหลังจากนั้น
• ห้องสมุดสาธารณะนั้นใช้ .NET เวอร์ชันหนึ่งซึ่งตามหลังเวอร์ชันล่าสุด ในขณะที่แอป ASP.NET Demo และชุดทดสอบการรวมที่มี .NET client API ที่สร้างขึ้นนั้นใช้กับ .NET เวอร์ชันปัจจุบัน

ฝั่งไคลเอ็นต์ .NET:

1. .NET Framework 4.5.2 หรือ Universal Windows หรือ Mono.Android หรือ Xamarin.iOS หรือ .NET Core 2.0/2.1/3 และ .NET 5
2. ไลบรารีไคลเอ็นต์ ASP.NET Web API 2.2
3. Json.NET ของ Newtonsoft สำหรับแอปพลิเคชันประเภทเนื้อหา/json
4. เครื่องมือสร้าง Microsoft 2015

NewtonSoft.Json หรือ System.Text.Json

ตั้งแต่ .NET 7 เป็นต้นมา สำหรับการทำให้เป็นอนุกรม System.Text.Json จะประกอบ NewtonSoft.Json มากกว่า 95% มีเพียงไม่กี่กรณีของโครงสร้าง POCO ที่ซับซ้อนที่ System.Text.Json ไม่สามารถจัดการได้

WebApiClientGen รองรับทั้งฝั่งเซิร์ฟเวอร์และฝั่งไคลเอ็นต์ C# สำหรับไคลเอนต์ C# คุณสามารถใช้ "UseSystemTextJson" ในการตั้งค่าโค้ดเจน

อย่างไรก็ตาม หากแอปพลิเคชันของคุณเกี่ยวข้องกับโครงสร้าง POCO ที่ซับซ้อน การใช้ NewtonSoft.Json ก็เป็นทางเลือกที่ปลอดภัยสำหรับ .NET 7

ฝั่งไคลเอ็นต์ TypeScript:

1. คอมไพเลอร์ TypeScript
2. jQuery
3. เชิงมุม 2-17
4. ออเรเลีย
5. แอ็กซิออส
6. ดึงข้อมูล API

สำหรับรายละเอียดเพิ่มเติม โปรดตรวจสอบ:

1. วิกิ
2. อธิบายการตั้งค่าแล้ว
3. สร้าง C# .NET Client API สำหรับ ASP.NET Web API
4. สร้าง TypeScript Client API สำหรับ ASP.NET Web API
5. ASP.NET เว็บ API, Angular2, TypeScript และ WebApiClientGen
6. สร้าง C# Client API สำหรับ ASP.NET Core Web API
7. โซลูชั่นที่ตั้งใจไว้สำหรับข้อจำกัดโดยเจตนาของตัวสร้างไคลเอนต์ OpenAPI ที่พิมพ์อย่างเข้มงวด บทความนี้ใช้ OpenApiClientGen เป็นตัวอย่าง ในขณะที่หลักการและวิธีแก้ปัญหาสามารถนำไปใช้กับโค้ดที่สร้างโดย WebApiClientGen สำหรับแอปไคลเอ็นต์ของคุณได้
8. วันที่เท่านั้นใน ASP.NET Core 6

แอปพลิเคชั่นสาธิต

แอปพลิเคชันสาธิตในพื้นที่เก็บข้อมูลนี้มีไว้สำหรับการทดสอบ WebApiClientGen ในระหว่างการพัฒนาเป็นหลัก และมีแอปพลิเคชันสาธิตอื่นๆ ในพื้นที่เก็บข้อมูลต่อไปนี้ ซึ่งสาธิตว่าแอปพลิเคชันในโลกแห่งความเป็นจริงสามารถใช้ WebApiClientGen ได้อย่างไร:

1. ตัวอย่าง WebApiClientGen สำหรับ .NET Framework, .NET Standard, Xamarin และ vue TS
2. การสาธิต .NET Core สำหรับ ASP.NET Core MVC, Web API, ASP.NET Core + Angular, MAUI, fetchAPI, vue TS และ React TS
3. WebApiClientGen กับ Swagger

แอปพลิเคชันสาธิตเหล่านี้ได้รับการดูแลและอัปเดตอยู่เสมอด้วยเฟรมเวิร์กล่าสุด หากคุณยังคงใช้เฟรมเวิร์กรุ่นเก่าเช่น Angular 4 หรือ 5 หรือ .NET Core 2.0 คุณสามารถนำทางไปยังแท็กที่เกี่ยวข้องของที่เก็บและชำระเงินได้

ทัวร์ฮีโร่

Tour of Heroes เป็นแอปสาธิตการสอนเชิงมุมอย่างเป็นทางการ

เพื่อแสดงให้เห็นประสบการณ์การใช้ WebApiClientGen ของโปรแกรมเมอร์ แอปสาธิตต่อไปนี้ได้รับการออกแบบทางสถาปัตยกรรมที่คล้ายคลึงกันสำหรับฟีเจอร์การทำงานที่เหมือนกันบนเฟรมเวิร์กหรือไลบรารีการพัฒนาต่างๆ อย่างไรก็ตาม เป็นการพูดคุยกับแบ็กเอนด์จริง

1. เชิงมุม 2+ และแบบฟอร์มปฏิกิริยาที่พิมพ์
2. ซามาริน
3. เมาอิ ย้ายมาจาก Xamarin Heroes
4. ออเรเลีย. รวมชุดทดสอบบูรณาการ
5. ตอบสนอง รวมชุดทดสอบบูรณาการ
6. เบลเซอร์ สแตนด์อโลน

NewtonSoft.Json หรือ System.Text.Json

แม้ว่า WebApiClientGen จะรองรับทั้งสองอย่าง แต่การสนับสนุนหลักได้เปลี่ยนไปเป็น System.Text.Json ตั้งแต่ปี 2024

NewtonSoft.Json ยังคงมีข้อได้เปรียบบางประการในบางสถานการณ์และบริบท:

1. หากคุณมีคลาส POCO จำนวนมากที่ตกแต่งโดย DataContractAttributes เนื่องจากรองรับแอปรุ่นเก่า หรือรองรับทั้งการทำให้เป็นอนุกรม XML และ JSON NewtonSoft.Json จะให้การสนับสนุนโดยธรรมชาติ ในขณะที่ System.Text.Json ให้การสนับสนุนที่ยุ่งยากและโดยอ้อมตั้งแต่ .NET 7
2. สำหรับอาร์เรย์และไดนามิกบางประเภท NewtonSoft.Json ยังดีกว่า