Главная страница>Исходный код ASP>Другие категории
Скачать

Генераторы строго типизированных клиентских веб-API генерируют коды клиентских API на C# и TypeScript из веб-API ASP.NET (Core) напрямую, без использования Swagger/OpenAPI или Swashbuckle, что максимально увеличивает поддержку типов данных вашего подхода Code First в веб-API ASP.NET. .

Продукты

Этот проект предоставляет следующие продукты:

  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+, а также типизированных реактивных форм Angular.
  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.
  • WebApiClientGen не использует определения Swagger/OpenAPI, но генерирует коды на основе информации о типе времени выполнения работающего веб-API отладочной сборки, избавляясь от присущих OpenAPI ограничений по отношению к типам .NET и веб-API, чтобы обеспечить лучший опыт разработки для ASP. NET (Core) Разработчики веб-API.

Примечания:

  • Разработка началась в 2015 году с поддержкой .NET Framework, затем .NET Core 2. А тег «LastCore31» предназначен для обозначения последнего моментального снимка с поддержкой .NET Framework 4.6.2 и .NET Core 3.1.
  • Начиная с 10 февраля 2021 г., разработка будет поддерживать только .NET 5 и более поздние версии.
  • Содержимое Wiki о .NET Framework в обозримом будущем будет сохранено.

Ключевые особенности

  1. Создаваемые коды клиентского API напрямую сопоставляются с методами контроллера веб-API, примитивными типами .NET и классами POCO. Это похоже на то, что предлагает svcutil.exe в WCF.
  2. Копируются комментарии к документам методов контроллера и классов POCO.
  3. Некоторые атрибуты проверки используются для создания комментариев к документам для кодов TypeScript.

Ключевые преимущества для опыта разработчиков

  1. WebApiClientGen легко интегрируется с веб-API ASP.NET Core с минимальными затратами на настройку, обслуживание и синхронизацию между веб-API и клиентскими API во время RAD или гибкой разработки программного обеспечения.
  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. Веб-API
  3. Сгенерированные коды клиентского API C#
  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 года Babel поддерживает пространства имен, поэтому вы сможете программировать React TSX с сгенерированными кодами TypeScript.

Концепции

  1. Поставщики/разработчики веб-API должны предоставлять библиотеки клиентских API разработчикам клиентских программ, как это сделали бы Google, Amazon и т. д., чтобы веб-API RESTful мог эффективно охватить более широкий круг потребителей (внутренних и внешних).
  2. Для разработчиков клиентов классические прототипы функций, такие как ReturnType DoSomething(Type1 t1, Type2 t2 ...) являются функцией API, а остальное — это технические детали реализации транспорта: TCP/IP, HTTP, SOAP, ресурсоориентированный, CRUD- основанные на URI, RESTful, XML и JSON и т. д. Прототип функции и часть документа API должны быть достаточно хороши для вызова функции API.
  3. Чем лучше вы разделяете задачи при разработке вашего веб-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.

Ссылки:

  • Проверка модели в веб-API ASP.NET
  • Проверка модели на страницах ASP.NET Core MVC и Razor

Проверка модели через ApiControllerAttribute

Например: 

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

Коды состояния HTTP, отличные от 2xx, обрабатываемые промежуточным программным обеспечением, необязательно

Даже если вы явно пишете коды в функции API для обработки исключений и возврата кода состояния HTTP, отличного от 2xx, у вас должна быть надежная сеть для перехвата неперехваченных исключений и возврата кодов состояния HTTP.

Ссылки:

  • Промежуточное ПО ASP.NET Core

Предварительные условия

Серверная часть:

  1. .NET 7/8
  2. Добавьте CodeGenController.
  3. В кодах запуска службы добавьте следующее: 
 services . AddControllers (
	options =>
	{
#if DEBUG
		options . Conventions . Add ( new Fonlow . CodeDom . Web . ApiExplorerVisibilityEnabledConvention ( ) ) ;
#endif
	}
)

Примечания:

  • Microsoft выпускает крупное обновление .NET (Core) каждый год, начиная с 2016 года, библиотеки в этом репозитории обычно будут обновляться примерно через полгода.
  • Общедоступные библиотеки используют .NET на одну версию позже последней версии, а демонстрационное приложение ASP.NET и наборы интеграционных тестов с созданным клиентским API .NET используют текущую версию .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 для приложения Content-Type/json
  4. Инструменты сборки Microsoft 2015

NewtonSoft.Json или System.Text.Json

Начиная с .NET 7, для сериализации System.Text.Json повторно собирает более 95% NewtonSoft.Json. Есть лишь несколько крайних случаев сложных структур 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. Создайте клиентский API C# .NET для веб-API ASP.NET.
  4. Создание клиентского API TypeScript для веб-API ASP.NET
  5. Веб-API ASP.NET, Angular2, TypeScript и WebApiClientGen
  6. Создание клиентского API C# для веб-API ASP.NET Core.
  7. Предполагаемые решения для преднамеренных ограничений строго типизированных генераторов клиентов OpenAPI. В статье OpenApiClientGen используется только в качестве примера, а принципы и решения могут быть применены к кодам, сгенерированным WebApiClientGen для ваших клиентских приложений.
  8. DateOnly в ASP.NET Core 6

Демонстрационные приложения

Демонстрационные приложения в этом репозитории предназначены в основном для тестирования WebApiClientGen во время разработки. В следующих репозиториях есть и другие демонстрационные приложения, демонстрирующие, как реальные приложения могут использовать WebApiClientGen:

  1. Примеры WebApiClientGen для .NET Framework, .NET Standard, Xamarin и vue TS.
  2. Демонстрация .NET Core для ASP.NET Core MVC, веб-API, ASP.NET Core + Angular, MAUI, fetchAPI, vue TS и React TS.
  3. WebApiClientGen против Swagger

Эти демонстрационные приложения активно поддерживаются и обновляются с учетом новейших платформ. Если вы все еще используете некоторые старые платформы, такие как Angular 4 или 5 или .NET Core 2.0, вы можете перейти к соответствующим тегам репозиториев и оформить заказ.

Тур героев

Tour of Heroes — официальное демонстрационное приложение Angular для обучения.

Чтобы проиллюстрировать опыт использования WebApiClientGen программистами, следующие демонстрационные приложения созданы с похожим архитектурным дизайном для одних и тех же функциональных функций в различных средах разработки или библиотеках, однако они взаимодействуют с реальным серверным компонентом.

  1. Angular 2+ и типизированные реактивные формы
  2. Ксамарин
  3. МАУИ. Перенесено с Xamarin Heroes.
  4. Аурелия. Включен набор интеграционных тестов.
  5. Реагировать. Включен набор интеграционных тестов.
  6. Блазор Автономный

NewtonSoft.Json или System.Text.Json

Однако хотя WebApiClientGen поддерживает оба варианта, с 2024 года основная поддержка перешла на System.Text.Json.

NewtonSoft.Json по-прежнему имеет несколько преимуществ в определенных сценариях и контекстах:

  1. Если у вас есть много классов POCO, украшенных DataContractAttributes, из-за поддержки устаревших приложений или поддержки сериализации XML и JSON, NewtonSoft.Json предоставляет вам встроенную поддержку, а System.Text.Json обеспечивает некоторую неприятную и косвенную поддержку, начиная с .NET 7.
  2. Для некоторых типов массивов и динамических данных NewtonSoft.Json все же лучше.
Расширять
Дополнительная информация
Связанные приложения
Рекомендуем вам
Связанные новости Все