Reinforced.Typings — Angular-сервисы на TypeScript прямо из ваших MVC-контроллеров

Всем привет
И вот, еще одна (и последняя) статья-пример по моему фреймворку для генерации TypeScript-ового glue-кода: Reinforced.Typings (перед этим была ещё одна и ещё). Сегодня мы научися автоматически генерировать TypeScript-обертки для вызовов методов MVC-контроллеров, снабжать их документацией и раскладывать по разным файлам. Надеюсь, вас порадует насколько быстро и легко решаются такие задачи с использованием RT. В рамках моего туториала мы реализуем генерацию класса-хэлпера для вызовов методов контроллеров с использованием jQuery и promise-ов, а так же сервис для angular.js, который готов для встраивания в ваше приложение и привнесения в него прозрачных обращений к методам сервера. Далее мы включим в генерируемый TypeScript документацию для этого дела (импортируем из XMLDOC) и разложим по файлам, чтобы не перемешивалось. Всем заинтересованным и желающим заиметь такую штуку в своих проектах, добро пожаловать под кат.

Пролог

Если коротко, то RT использует систему кодогенераторов для генерации исходного TypeScript-кода. С недавних пор (версия 1.2.0) я отказался от практики писать TypeScript-код прямо в открытый текстовый поток (что было неудобно, зато весьма быстро) и пришел к практике использования очень несложного AST (Abstract Syntax Tree). В самом деле, это дерево очень базовое, далеко не полное и ориентировано оно на декларационные элементы TypeScript-а. Ну то есть без выражений, операторов, switch-ей, созданий переменных и т.п. Только классы/интерфейсы, методы, поля, модули. После введения AST, не скрою, стало легче. В том числе и форматировать выводимый код, в противовес старому решению, когда пользователю приходилось заботиться о форматировании самостоятельно. Да, конечно в определенном смысле это компромисс в ушерб гибкости, но в прибыль удобству использования, но в целом, как мне кажется, игра стоит свеч. К тому же в основных местах вас никто не ограничивает в типе узлов дерева. Что это значит? А это значит, что вставить в середину класса прямым текстом матерный комментарий (даже многострочный) через AST вы сможете. Да-да, и ему еще и корректно выставят табуляцию в начале строки. Ну что ж, приступим.

С места в карьер

Давайте я объясню на простом примере — генерации jQuery-оберток с промисами для вызовов контроллеров. Потому что angular-way может оказаться чужд для кого-то, а с jQuery в общем-то все понятно.

Итак, дано: простое ASP.NET MVC-приложение, jQuery, контроллер с методами, которые хочется дергать из клиентского TypeScript-а, несколько View-моделек и ваши чешущиеся руки.
Задача: выставить серверный API в TypeScript-класс, чтобы не парится с постоянными $.post/$.load, или, чего доброго, $.ajax.
Решение:

Шаг 0. Инфраструктура

Я обозначу здесь тестовый код, который мы имеем, чтобы было от чего отталкиваться.

Моделька:

1.  
2. public class SampleResponseModel
3. {
4.     public string Message { get; set; }
5.     public bool Success { get; set; }
6.     public string CurrentTime { get; set; }
7. }
8.  

Контроллер:

1.  
2. public class JQueryController : Controller
3. {
4.     public ActionResult SimpleIntMethod()
5.     {
6.         return Json(new Random().Next(100));
7.     }
8.  
9.     public ActionResult MethodWithParameters(int num, string s, bool boolValue)
10.     {
11.         return Json(string.Format("{0}-{1}-{2}", num, s, boolValue));
12.     }
13.  
14.     public ActionResult ReturningObject()
15.     {
16.         var result = new SampleResponseModel()
17.         {
18.             CurrentTime = DateTime.Now.ToLongTimeString(),
19.             Message = "Hello!",
20.             Success = true
21.         };
22.         return Json(result);
23.     }
24.  
25.     public ActionResult ReturningObjectWithParameters(string echo)
26.     {
27.         var result = new SampleResponseModel()
28.         {
29.             CurrentTime = DateTime.Now.ToLongTimeString(),
30.             Message = echo,
31.             Success = true
32.         };
33.         return Json(result);
34.     }
35.  
36.     public ActionResult VoidMethodWithParameters(SampleResponseModel model)
37.     {
38.         return null;
39.     }
40. }
41.  

К тому же мы заведем TypeScript-файл (он у меня лежит в /Scripts/IndexPage.ts) для тестирования. Вот такой (да простят меня адепты MVVM, для вас будет материал ниже):

1.  
2. module Reinforced.Typings.Samples.Difficult.CodeGenerators.Pages{
3.     export class IndexPage {
4.         constructor() {
5.             $('#btnSimpleInt').click(this.btnSimpleIntClick.bind(this));
6.             $('#btnMethodWithParameters').click(this.btnMethodWithParametersClick.bind(this));
7.             $('#btnReturningObject').click(this.btnReturningObjectClick.bind(this));
8.         }
9.  
10.         private btnSimpleIntClick() {       }
11.  
12.         private btnMethodWithParametersClick() {        }
13.  
14.         private btnReturningObjectClick() {         }
15.     }
16. }
17.  

Важно! Не забудьте поставить себе тайпинги для jQuery из NuGet от DefinitelyTyped. В противном случае с компиляцией TS будут проблемы.

Ну и грех не сделать тестовую въюху (предполагается что jQuery у вас уже подключен). Перепишите ваш Index.cshtml, например, так:

1.  
2. <span id="loading"></span>
3. Результат: <strong id="result"></strong>
4. <button class="btn btn-primary" id="btnSimpleInt">Тынц</button>
5. <button class="btn btn-default" id="btnMethodWithParameters">Клац</button>
6. <button class="btn btn-default" id="btnReturningObject">Бумс</button>
7. <button class="btn btn-default" id="btnReturningObjectWithParameters">Бдыщ</button>
8. <button class="btn btn-default" id="btnVoidMethodWithParameters">Кря!</button>
9. @section Scripts
10. {
11.     <script type="text/javascript" src="/Scripts/IndexPage.js"></script>
12.     <script type="text/javascript" src="/Scripts/query.js"></script>
13.     <script type="text/javascript">
14.         $(document).ready(function () {
15.             var a = new Reinforced.Typings.Samples.Difficult.CodeGenerators.Pages.IndexPage();
16.         })
17.     </script>
18. }
19.  

Вы, должно быть, заметили включение query.js в документ. Не пугайтесь — так надо, в следующем же разделе я объясню что к чему.

Все, это была портянка тестовой инфраструктуры. Дальше будет легче.

Шаг 1. Запросы

Первым делом давайте вынесем в отдельный TypeScript-класс всего один метод, который мы будем использовать для запросов к серверу. Просто jQuery в этом плане несколько громоздок и мне бы не хотелось повторять весь этот шаблонный код в каждом методе в угоду читабельности. Итак, маленький класс с маленьким методом для того, чтобы делать запросы к серверу:

/Scripts/query.ts

1.  
2. class QueryController {
3.     public static query<T>(url: string, data: any, progressSelector: string, disableSelector:string = ''): JQueryPromise<T> {
4.         var promise = jQuery.Deferred();
5.         var query = {
6.             data: JSON.stringify(data),
7.             type: 'post',
8.             dataType: 'json',
9.             contentType:'application/json',
10.             timeout: 9000000,
11.             traditional: false,
12.             complete: () => {
13.                 if (progressSelector && progressSelector.length > 0) {
14.                     $(progressSelector).find('span[data-role="progressContainer"]').remove();
15.                 }
16.                 if (disableSelector && disableSelector.length > 0) {
17.                     $(disableSelector).prop('disabled', false);
18.                 }
19.             },
20.             success: (response: T) => {
21.                 promise.resolve(response);
22.             },
23.             error: (request, status, error) => {
24.                 promise.reject({ Success: false, Message: error.toString(), Data: error });
25.             }
26.         };
27.  
28.         if (progressSelector && progressSelector.length > 0) {
29.             $(progressSelector).append('<span data-role="progressContainer"> Loading ... </span>');
30.         }
31.  
32.         if (disableSelector && disableSelector.length > 0) {
33.             $(disableSelector).prop('disabled',true);
34.         }
35.  
36.         $.ajax(url,<any>query);
37.         return promise;
38.     }
39. }
40.  

Как видим, метод предельно прост, принимает на вход URL для запроса, данные (любой JS-объект), а так же, чтобы было удобнее использовать я сделал два параметра: один для обозначения селектора HTML-элемента, кой надлежит отключать на время запроса, и один… Ну, примерно то же самое, только для элемента, к которому будет подписываться надпись «Loading…». Полагаю самоочевидным, что надпись «Loading…» вы без труда можете заменить на что-нибудь свое. Возвращает этот метод jQuery-евский Promise, к которому вы можете дописать .then/.fail/.end и другие. Впрочем, я полагаю что целевая аудитория этой статьи и без меня в курсе как работать с промисами.:)

Шаг 2. Атрибуты

Так как через reflection невозможно определить что возвращают наши методы контроллера, мы сделаем атрибут, которым будем помечать все методы нашего JQueryController-а, для которых необходимо сгенерировать обертку. Выглядеть он будет, например, так:

1.  
2. public class JQueryMethodAttribute : TsFunctionAttribute
3. {
4.     public JQueryMethodAttribute(Type returnType)
5.     {
6.         StrongType = returnType;
7.         CodeGeneratorType = typeof (JQueryActionCallGenerator);
8.     }
9. }
10.  

Здесь мы убиваем двух зайцев сразу и указываем CodeGeneratorType для этого метода. Не волнуйтесь что его пока нет — мы напишем его в следующем разделе. В остальном — имеющийся атрибут можно разместить над нашими методами контроллера. Заодно мы поставим [TsClass], не отходя от кассы:

1.  
2. [TsClass]
3. public class JQueryController : Controller
4. {
5.     [JQueryMethod(typeof(int))]
6.     public ActionResult SimpleIntMethod()
7.     {
8.         // fold
9.     }
10.  
11.     [JQueryMethod(typeof(string))]
12.     public ActionResult MethodWithParameters(int num, string s, bool boolValue)
13.     {
14.         // fold
15.     }
16.  
17.     [JQueryMethod(typeof(SampleResponseModel))]
18.     public ActionResult ReturningObject()
19.     {
20.         // fold
21.     }
22.    
23.     [JQueryMethod(typeof(SampleResponseModel))]
24.     public ActionResult ReturningObjectWithParameters(string echo)
25.     {
26.         // fold
27.     }
28.  
29.     [JQueryMethod(typeof(void))]
30.     public ActionResult VoidMethodWithParameters(SampleResponseModel model)
31.     {
32.         // fold
33.     }
34. }
35.  

Так же не забудем поставить [TsInterface] над моделькой. Иначе, как говаривал Амаяк Акопян, «никакого чуда не произойдет“.

1.  
2. [TsInterface]
3. public class SampleResponseModel
4. {
5.     // fold
6. }
7.  

Шаг 3. Кодогенератор

Теория сравнительно проста. RT собирает в кучу информацию о том, что из своих C#-типов вы хотите видеть в результирующем TypeScript-е и в каком виде, потом начинает это добро обходить в глубину, начиная с неймспейсов и спускаясь к членам класса и параметрам декларируемых методов. Встречая на своем пути ту или иную сущность, RT вызывает соответствующий кодогенератор (экземпляры кодогенераторов он инстанциирует лениво, с лайфтаймом «1 экземпляр на весь процесс экспорта»). На этот процесс можно повлиять, указав какой кодогенератор вы хотите использовать. Сделать это можно с помощью атрибутной конфигурации (поле CodeGeneratorType, которое есть в любом атрибуте RT) — тут нет «защиты от дурака», но предполагается что вы укажете typeof наследника интерфейса Reinforced.Typings.Generators.ITsCodeGenerator с правильным T, соответствующим сущности, над которой размещается атрибут. А еще можно использовать Fluent-вызов .WithCodeGenerator. Там уже есть «защита от дурака» и указать неподходящий кодогенератор у вас не получится.
Есть в наличии несколько встроенных кодогенераторов. Все они расположены в пространстве имен Reinforced.Typings.Generators. Имеются кодогенераторы для интерфейса, класса, конструктора, перечисления, поля, свойства, метода и параметра метода. Самый простой способ сделать свой кодогенератор — унаследоваться от существующего. Далее (по возрастанию сложности) — унаследоваться от TsCodeGeneratorBase<T1, T2>, где T1 — тип входной reflection-сущности, а T2 — тип результата в синтаксическом дереве (наследник RtNode). Ну и сложный вариант — реализовать интерейс ITsCodeGenerator самостоятельно, что в большинстве случаев делать не рекомендуется, ибо требует знания некоторых тонкостей и чтения исходнико, да и незачем.
Мы сделаем наш JQueryActionCallGenerator просто унаследовавшись от встроенного кодогенератора для методов. Итак, вот наш кодогенератор с детальными комментариями:

1.  
2. using System;
3. using System.Linq;
4. using System.Reflection;
5. using Reinforced.Typings.Ast;
6. using Reinforced.Typings.Generators;
7.  
8.  
9. /// <summary>
10. /// Наш кодогенератор для оберток на вызовы метода контроллера.
11. /// Он заточен на то, чтобы брать на вход MethodInfo и продуцировать на выходе
12. /// экземпляр RtFunction, который представляет собой кусок синтаксического дерева
13. /// с TypeScript-ом.
14. /// Как уже было сказано выше, мы наследуемся от встроенного в RT MethodCodeGenerator,
15. /// который в обычных условиях генерирует метод с сигнатурой и пустой реализацией
16. /// </summary>
17. public class JQueryActionCallGenerator : MethodCodeGenerator
18. {
19.     /// <summary>
20.     /// Естественно, мы перегружаем метод GenerateNode. Собственно, это почти что единственный
21.     /// и основной метод в кодогенераторе.
22.     /// </summary>
23.     /// <param name="element">Метод, для которого будет сгенерирован код в виде MethodInfo</param>
24.     /// <param name="result">
25.     /// Результирующая AST-нода (RtFunction).
26.     /// Мы не создаем ноду "с нуля". И честно говоря, я забыл почему принял такое архитектурное решение :)
27.     /// Но мы все еще можем вернуть null, чтобы исключить ноду/метод из конечного TypeScript-файла
28.     /// </param>
29.     /// <param name="resolver">
30.     /// А это - экземпляр TypeResolver-а. Это специальный класс, который мы можем использовать
31.     /// для вывода типов в результирующем TypeScript-е, чтобы не делать ничего руками.    
32.     /// </param>
33.     /// <returns>RtFunction (она же нода синтаксического дерева, она же AST-нода)</returns>
34.     public override RtFuncion GenerateNode(MethodInfo element, RtFuncion result, TypeResolver resolver)
35.     {
36.         // Для начала сгенерируем обертку метода "как обычно"
37.         // Далее мы будем её расширять и дополнять
38.         result =  base.GenerateNode(element, result, resolver);
39.        
40.         // Если по каким-то причинам сгенерирована пустая нода - значит так надо
41.         // не будем вмешиваться в этот процесс
42.         if (result == null) return null;
43.  
44.         // Делаем наш метод статическим
45.         result.IsStatic = true;
46.  
47.         // А так же добавляем к методу пару лишних параметров для указания
48.         // элемента, который будет отключен, пока будет идти вызов серверного метода,
49.         // а так же элемента, в который надо будет добавлять индикатор загрузки
50.         result.Arguments.Add(
51.             new RtArgument()
52.             {
53.                 Identifier = new RtIdentifier("loadingPlaceholderSelector"),
54.                 Type = resolver.ResolveTypeName(typeof(string)),
55.                 DefaultValue = "''"
56.             });
57.  
58.         result.Arguments.Add(
59.            new RtArgument()
60.            {
61.                Identifier = new RtIdentifier("disableElement"),
62.                Type = resolver.ResolveTypeName(typeof(string)),
63.                DefaultValue = "''"
64.            });
65.  
66.         // Сохраняем оригинальное возвращаемое значение метода
67.         // ибо дальше нам потребуется параметризовать им JQueryPromise
68.         var retType = result.ReturnType;
69.        
70.         // ... и если возвращаемый тип - void, мы просто оставим JQueryPromise<any>
71.         bool isVoid = (retType is RtSimpleTypeName) && (((RtSimpleTypeName) retType).TypeName == "void");
72.  
73.         // здесь я использую TypeResolver чтобы получить AST-ноду для имени типа "any"
74.         // просто чтобы продемонстрировать применение TypeResolver-а
75.         // (ну и еще потому что я достаточно ленив чтобы создавать any руками)
76.         if (isVoid) retType = resolver.ResolveTypeName(typeof (object));
77.  
78.         // Окей, переопределяем возвращаемое значение нашего метода, оборачивая его
79.         // в JQueryPromise
80.         // Мы используем класс RtSimpleType, передавая ему generic-аргументы,
81.         // чтобы не писать угловые скобки руками
82.         result.ReturnType = new RtSimpleTypeName("JQueryPromise", new[] { retType });
83.  
84.         // Теперь дело за параметрами. Достаем их через reflection.
85.         // Далее мы используем экстеншн .GetName() чтобы достать имя параметра
86.         // Этот экстеншн поставляется с Reinforced.Typings и возвращает имя параметра
87.         // метода со всеми потенциальными перегрузками через Fluent-конфигурацию или
88.         // атрибут [TsParameter]
89.         var p = element.GetParameters().Select(c => string.Format("'{0}': {0}", c.GetName()));
90.  
91.         // Сцепляем параметры для генерации кода тела метода
92.         var dataParameters = string.Join(", ", p);
93.  
94.         // Достаем путь к контроллеру
95.         // Здесь у нас простое решение, которое требует наличия MVC-маршрута на /{controller}/{action}
96.         // предполагается что он есть (хотя кого я обманываю, он есть в 90% приложений)
97.         string controller = element.DeclaringType.Name.Replace("Controller", String.Empty);
98.         string path = String.Format("/{0}/{1}", controller, element.Name);
99.  
100.         // Теперь лепим glue-код с вызовом QueryController, который мы определили в query.ts
101.         string code = String.Format(
102. @"return QueryController.query<{2}>(
103.    '{0}',
104.    {{ {1} }},
105.    loadingPlaceholderSelector,
106.    disableElement
107. );",
108.    path, dataParameters, retType);
109.  
110.         // Оборачиваем код в RtRaw и запихиваем в качестве тела в наш результат
111.         result.Body = new RtRaw(code);
112.  
113.         // Теперь давайте добавим немного JSDOC-а, чтобы результаты нашей работы были очевиднее
114.         result.Documentation = new RtJsdocNode(){Description = String.Format("Wrapper method for call {0} of {1}",element.Name,element.DeclaringType.Name)};
115.  
116.         // Собственно, на этом все. Возвращаем RtFunction
117.         // Согласно дефолтным настройкам конфига, это добро будет записано в project.ts
118.         return result;
119.     }
120. }
121.  

Кодогенератор готов. Осталось только сделать нашему проекту Rebuild. Если у вас возникают какие-либо сложности с отладкой генераторов, то вы можете использовать свойство генератора Context типа ExportContext. У того наличествует свойство Warnings, представляющее собой коллекцию RtWarning-ов. Добавьте туда свой — он выведется в окошко Warnings в студии при билде (эта фича была добавлена буквально недавно, в версии 1.2.2).

Для тех, кому не терпится, привожу результат работы кодогенратора:

1.  
2. module Reinforced.Typings.Samples.Difficult.CodeGenerators.Models {
3.         export interface ISampleResponseModel
4.         {
5.                 Message: string;
6.                 Success: boolean;
7.                 CurrentTime: string;
8.         }
9. }
10. module Reinforced.Typings.Samples.Difficult.CodeGenerators.Controllers {
11.         export class JQueryController
12.         {
13.                 /** Wrapper method for call SimpleIntMethod of JQueryController */
14.                 public static SimpleIntMethod(loadingPlaceholderSelector: string = '', disableElement: string = '') : JQueryPromise<number>
15.                 {
16.                         return QueryController.query<number>(
17.                                 '/JQuery/SimpleIntMethod',
18.                                 {  },
19.                                 loadingPlaceholderSelector,
20.                                 disableElement
21.                             );
22.                 }
23.                 /** Wrapper method for call MethodWithParameters of JQueryController */
24.                 public static MethodWithParameters(num: number, s: string, boolValue: boolean, loadingPlaceholderSelector: string = '', disableElement: string = '') : JQueryPromise<string>
25.                 {
26.                         return QueryController.query<string>(
27.                                 '/JQuery/MethodWithParameters',
28.                                 { 'num': num, 's': s, 'boolValue': boolValue },
29.                                 loadingPlaceholderSelector,
30.                                 disableElement
31.                             );
32.                 }
33.                 /** Wrapper method for call ReturningObject of JQueryController */
34.                 public static ReturningObject(loadingPlaceholderSelector: string = '', disableElement: string = '') : JQueryPromise<Reinforced.Typings.Samples.Difficult.CodeGenerators.Models.ISampleResponseModel>
35.                 {
36.                         return QueryController.query<Reinforced.Typings.Samples.Difficult.CodeGenerators.Models.ISampleResponseModel>(
37.                                 '/JQuery/ReturningObject',
38.                                 {  },
39.                                 loadingPlaceholderSelector,
40.                                 disableElement
41.                             );
42.                 }
43.                 /** Wrapper method for call ReturningObjectWithParameters of JQueryController */
44.                 public static ReturningObjectWithParameters(echo: string, loadingPlaceholderSelector: string = '', disableElement: string = '') : JQueryPromise<Reinforced.Typings.Samples.Difficult.CodeGenerators.Models.ISampleResponseModel>
45.                 {
46.                         return QueryController.query<Reinforced.Typings.Samples.Difficult.CodeGenerators.Models.ISampleResponseModel>(
47.                                 '/JQuery/ReturningObjectWithParameters',
48.                                 { 'echo': echo },
49.                                 loadingPlaceholderSelector,
50.                                 disableElement
51.                             );
52.                 }
53.                 /** Wrapper method for call VoidMethodWithParameters of JQueryController */
54.                 public static VoidMethodWithParameters(model: Reinforced.Typings.Samples.Difficult.CodeGenerators.Models.ISampleResponseModel, loadingPlaceholderSelector: string = '', disableElement: string = '') : JQueryPromise<any>
55.                 {
56.                         return QueryController.query<any>(
57.                                 '/JQuery/VoidMethodWithParameters',
58.                                 { 'model': model },
59.                                 loadingPlaceholderSelector,
60.                                 disableElement
61.                             );
62.                 }
63.         }
64. }
65.  

Так же важный момент — если ваш кодогенератор отработал неправильно и выдал ошибку, которая сделала ваши TypeScript-ы несобираемыми и теперь у вас не собирается солюшен, чтобы сгенерировать новые тайпинги — пойдите в Reinforced.Typings.settings.xml, что в корне вашего проекта и установите там RtBypassTypeScriptCompilation в true. Это сместит MSBuild-задачу сборки TypeScript-ов так, чтобы она вызывалась после сборки проекта (а не до, как происходит по умолчанию). Однако, не забудьте вернуть потом обратно, ибо как будучи активным в ходе выполнения задач паблишинга, этот параметр может привести к тому, что тайпскрипты не будут пересобираться перед публикацией. И это не особо весело.

Шаг 4. Использование

На этом моменте вы можете вернуться в ваш IndexPage.ts и использовать статические вызовы из сгенерированного нами класса JQueryController. В целом все достаточно прозаично и монотонно, поэтому я порекомендую вам самостоятельно этим заняться и испытать как работает IntelliSense. Код всего IndexPage.ts приведен ниже:

1.  
2. module Reinforced.Typings.Samples.Difficult.CodeGenerators.Pages {
3.     import JQueryController = Reinforced.Typings.Samples.Difficult.CodeGenerators.Controllers.JQueryController;
4.  
5.     export class IndexPage {
6.         constructor() {
7.             $('#btnSimpleInt').click(this.btnSimpleIntClick.bind(this));
8.             $('#btnMethodWithParameters').click(this.btnMethodWithParametersClick.bind(this));
9.             $('#btnReturningObject').click(this.btnReturningObjectClick.bind(this));
10.             $('#btnReturningObjectWithParameters').click(this.btnReturningObjectWithParametersClick.bind(this));
11.             $('#btnVoidMethodWithParameters').click(this.btnVoidMethodWithParametersClick.bind(this));
12.         }
13.  
14.         private btnSimpleIntClick() {
15.             JQueryController.SimpleIntMethod('#loading', '#btnSimpleInt')
16.                 .then(r => $('#result').html('Server tells us ' + r));
17.         }
18.  
19.         private btnMethodWithParametersClick() {
20.             JQueryController.MethodWithParameters(Math.random(), 'string' + Math.random(), Math.random() > 0.5, '#loading', '#btnMethodWithParameters')
21.                 .then(r => {
22.                 $('#result').html(r);
23.             });
24.         }
25.  
26.         private btnReturningObjectClick() {
27.             JQueryController.ReturningObject('#loading', '#btnReturningObject')
28.                 .then(r => {
29.                 var s = "<pre> { <br/>";
30.                 for (var key in r) {
31.                     s += `  ${key}: ${r[key]},\n`;
32.                 }
33.                 s += '} </pre>';
34.                 $('#result').html(s);
35.             });
36.         }
37.  
38.         private btnReturningObjectWithParametersClick() {
39.             var str = 'Random number: ' + Math.random() * 100;
40.             JQueryController.ReturningObjectWithParameters(str, '#loading', '#btnReturningObjectWithParameters')
41.                 .then(r => {
42.                 var s = "<pre> { <br/>";
43.                 for (var key in r) {
44.                     s += `  ${key}: ${r[key]},\n`;
45.                 }
46.                 s += '} </pre>';
47.                 $('#result').html(s);
48.             });
49.         }
50.  
51.         private btnVoidMethodWithParametersClick() {
52.             JQueryController.VoidMethodWithParameters({
53.                 Message: 'Hello',
54.                 Success: true,
55.                 CurrentTime: null
56.             }, '#loading', '#btnVoidMethodWithParameters')
57.                 .then(() => {
58.                 $('#result').html('Void method executed but it does not return result');
59.             });
60.         }
61.     }
62. }
63.  

Для любителей Angular

В принципе все то же самое. Однако, помимо генератора методов, нам понадобится генератор для всего класса, ибо как в лучших традициях ангуляра, неплохо будет экспортировать наш серверный контроллер в angular-сервис. Итак, поставьте DefinitelyTyped для angular.js, подключите сам angular через NuGet и давайте глянем на код генератора методов. Он немного отличается от jQuery-евского в силу того, что надо использовать другие промисы, а так же использовать $http.post вместо $.ajax:

1.  
2. using System;
3. using System.Linq;
4. using System.Reflection;
5. using Reinforced.Typings.Ast;
6. using Reinforced.Typings.Generators;
7.  
8. /// <summary>
9. /// Генератор оберток методов для angular.js
10. /// </summary>
11. public class AngularActionCallGenerator : MethodCodeGenerator
12. {
13.     public override RtFuncion GenerateNode(MethodInfo element, RtFuncion result, TypeResolver resolver)
14.     {
15.         result = base.GenerateNode(element, result, resolver);
16.         if (result == null) return null;
17.  
18.         // перегружаем тип метода под наш промис
19.         var retType = result.ReturnType;
20.         bool isVoid = (retType is RtSimpleTypeName) && (((RtSimpleTypeName)retType).TypeName == "void");
21.  
22.         // точно такой же трюк с void-методами
23.         if (isVoid) retType = resolver.ResolveTypeName(typeof(object));
24.  
25.         // используем angular.IPromise вместо JQueryPromise
26.         result.ReturnType = new RtSimpleTypeName(new[] { retType }, "angular", "IPromise");
27.  
28.         // параметры метода - по такому же принципу
29.         var p = element.GetParameters().Select(c => string.Format("'{0}': {0}", c.GetName()));
30.         var dataParameters = string.Join(", ", p);
31.  
32.         // Достаем путь к контроллеру
33.         string controller = element.DeclaringType.Name.Replace("Controller", String.Empty);
34.         string path = String.Format("/{0}/{1}", controller, element.Name);
35.  
36.         // Генерируем код через this.http.post
37.         const string code = @"var params = {{ {1} }};
38. return this.http.post('{0}', params)
39. .then((response) => {{ return response.data; }});";
40.  
41.         // так же оборачиваем в RtRaw
42.         RtRaw body = new RtRaw(String.Format(code, path, dataParameters));
43.         result.Body = body;
44.         return result;
45.     }
46. }
47.  

Вот и вся магия. Не забудьте задать этот кодогенератор для всех angular-friendly методов контроллеров через атрибут или через Fluent-конфигурацию.

А теперь давайте сделаем кодогенератор для класса, который будет содержать эти методы. Специфика в том, что методы у нас отныне не статические, нам понадобится сделать приватное поле http, которое будет хранить сервис $http, конструктор, который будет инжектить этот сервис, а так же регистрацию нашего контроллер-сервиса в нашем приложении.
Здесь я предполагаю что у вас уже есть где-то создание модуля вашего приложения посредством вызова angular.module и сам модуль лежит в глобальной переменной app.

1.  
2. using System;
3. using Reinforced.Typings.Ast;
4. using Reinforced.Typings.Generators;
5.  
6. /// <summary>
7. /// Генератор, оборачивающий наши методы в angular-сервис.
8. /// наследуем от стандартного генератора классов
9. /// </summary>
10. public class AngularControllerGenerator : ClassCodeGenerator
11. {
12.     public override RtClass GenerateNode(Type element, RtClass result, TypeResolver resolver)
13.     {
14.         // Опять же - начинаем со "стандартного" класса, сгенерированного для контроллера
15.         result = base.GenerateNode(element, result, resolver);
16.         if (result == null) return null;
17.  
18.         // Добавим немножко документации
19.         result.Documentation = new RtJsdocNode(){Description = "Result of AngularControllerGenerator activity"};
20.  
21.         // создаем имя типа angular.IHttpService
22.         var httpServiceType = new RtSimpleTypeName("IHttpService") { Namespace = "angular" };
23.  
24.         // Добавлем конструктор,...        
25.         RtConstructor constructor = new RtConstructor();
26.         // ... принимающий $http: angular.IHttpService
27.         constructor.Arguments.Add(new RtArgument(){Type = httpServiceType,Identifier = new RtIdentifier("$http")});
28.         // его тело будет содержать единственную строчку -
29.         // занесение $http в локальное поле
30.         constructor.Body = new RtRaw("this.http = $http;");
31.  
32.         // Описываем поле, которое будет держать в себе $http
33.         RtField httpServiceField = new RtField()
34.         {
35.             Type = httpServiceType,
36.             Identifier = new RtIdentifier("http"),
37.             AccessModifier = AccessModifier.Private,
38.             Documentation = new RtJsdocNode() { Description = "Хранит экземпляр $http полученный при вызове конструктора"}
39.         };
40.  
41.         // Добавляем констркутор и поле в наш класс
42.         result.Members.Add(httpServiceField);
43.         result.Members.Add(constructor);
44.  
45.         // Код для строчки, которая будет регистрировать наш класс в модуле для последующей инъекции
46.         // регистрация будет идти под именем Api.%Something%Controller
47.         const string initializerFormat =
48.             "if (window['app']) window['app'].factory('Api.{0}', ['$http', ($http: angular.IHttpService) => new {1}($http)]);";
49.  
50.         // подставляем параметры
51.         RtRaw registration = new RtRaw(String.Format(initializerFormat,element.Name,result.Name));
52.        
53.         // Находим текущий модуль в контексте экспорта (свойство генератора Context), берем у него список юнитов компиляции
54.         // Для этого используем Context.Location.CurrentModule.CompilationUnits
55.         // Коллекция CompilationUnits собирает в себе RtNode, так что
56.         // в нее можно запихнуть все, вплоть до RtRaw
57.         // По сему, смело пихаем регистрацию прямо вот туда        
58.         Context.Location.CurrentModule.CompilationUnits.Add(registration);        
59.         return result;
60.     }
61. }
62.  

Присоедините этот кодогенератор к вашим контроллерам любым способом (атрибутом или Fluent-конфигурацией). После чего, пересоберите проект и смело инжектите полученный сервис в свои angular-контроллеры.
Опять же, результат работы этого кодогенератора для нетерпеливых:

1.  
2. module Reinforced.Typings.Samples.Difficult.CodeGenerators.Controllers {
3.         if (window['app']) window['app'].factory('Api.AngularController', ['$http', ($http: ng.IHttpService) => new AngularController($http)]);
4.         /** Result of AngularControllerGenerator activity */
5.         export class AngularController
6.         {
7.                 constructor ($http: ng.IHttpService)
8.                 {
9.                         this.http = $http;
10.                 }
11.                 public SimpleIntMethod() : ng.IPromise<number>
12.                 {
13.                         var params = {  };
14.                         return this.http.post('/Angular/SimpleIntMethod', params)
15.                             .then((response) => { response.data['requestParams'] = params; return response.data; });
16.                 }
17.                 public MethodWithParameters(num: number, s: string, boolValue: boolean) : ng.IPromise<string>
18.                 {
19.                         var params = { 'num': num, 's': s, 'boolValue': boolValue };
20.                         return this.http.post('/Angular/MethodWithParameters', params)
21.                             .then((response) => { response.data['requestParams'] = params; return response.data; });
22.                 }
23.                 public ReturningObject() : ng.IPromise<Reinforced.Typings.Samples.Difficult.CodeGenerators.Models.ISampleResponseModel>
24.                 {
25.                         var params = {  };
26.                         return this.http.post('/Angular/ReturningObject', params)
27.                             .then((response) => { response.data['requestParams'] = params; return response.data; });
28.                 }
29.                 public ReturningObjectWithParameters(echo: string) : ng.IPromise<Reinforced.Typings.Samples.Difficult.CodeGenerators.Models.ISampleResponseModel>
30.                 {
31.                         var params = { 'echo': echo };
32.                         return this.http.post('/Angular/ReturningObjectWithParameters', params)
33.                             .then((response) => { response.data['requestParams'] = params; return response.data; });
34.                 }
35.                 public VoidMethodWithParameters(model: Reinforced.Typings.Samples.Difficult.CodeGenerators.Models.ISampleResponseModel) : ng.IPromise<any>
36.                 {
37.                         var params = { 'model': model };
38.                         return this.http.post('/Angular/VoidMethodWithParameters', params)
39.                             .then((response) => { response.data['requestParams'] = params; return response.data; });
40.                 }
41.                 /** Keeps $http instance received on construction */
42.                 private http: ng.IHttpService;
43.         }
44. }
45.  

Кстати, полная версия файла из примера вживую лежит вот тут.

Добавляем документацию

Так же в RT присутствует возможность автоматически импортировать в полученный TypeScript-код XMLDOC из методов контроллеров. Помимо дописывания RtJsdocNode напрямую руками, возможен следующий подход:
1) Пройдите в Reinforced.Typings.settings.xml и установите там параметр RtGenerateDocumentation в True
2) Включите экспорт XMLDOC-а для вашего проекта. Чтобы сделать это, щелкните правой кнопкой мыши на вашем .csproj-е, выберите Properties, пройдите на вкладку Build и поставьте галочку «XML Documentation File» в секции Output (см. картинку). После чего сохраните проект через Ctrl-S

3) Пересоберите чтобы увидеть изменения Здесь важно заметить две особенности: во-первых по умолчанию, в Release-конфигурации эта галочка уже стоит. Поэтому как вариант вы можете установить параметр RtGenerateDocumentation и переключить конфиг сборки проекта на Release.
Вторая особенность — если волею судеб вы экспортируете типы с fluent-конфигурацией из другой сборки, то RT надо явно указать какой файл с документацией надо подключить (помимо основного). Сделать это можно с помощью Fluent-вызова ConfigurationBuilder.TryLookupDocumentationForAssembly, которому надо передать сборку из которой идет экспорт и полный путь к XML-файлу с документацией.

Раскладываем по разным файлам

Для активации режима раскладки по разным файлам, вам понадобится включить еще одну настройку сборки. Итак 
1) Пройдите в Reinforced.Typings.settings.xml, установите RtDivideTypesAmongFiles в true. Рядом же найдите параметр RtTargetDirectory — он указывает целевую папку, в которую свалятся сгенерированные typescript-файлы. Поправьте и этот параметр при необходимости 
2) Определите какой код в какие файлы ляжет. Это можно сделать используя атрибут [TsFile], или же Fluent-вызов .ExportTo, доступный при использовании .ExportAsClass (es)/.ExportAsInterface (s)/.ExportAsEnum (s). Параметр принимает путь к файлу относительно директории, обозначенной в RtTargetDirectory.
3) Пересоберите, добавьте полученные файлы в проект

Казалось бы, ничего сложного, но тут всплывает сложный момент с директивой ///. Так вот — спешу обрадовать, никаких дополнительных настроек не требуется. RT достаточно умен, чтобы расставить эти директивы корректно без вашего участия. Однако, если вам необходимы референсы на какие-то другие файлы, то это легко решается путем атрибута [TsAddTypeReference] или Fluent-вызова .AddReference, который доступен примерно там же, где и .ExportTo. Эти методы позволяют добавить референс на файл по вашему экспортируемому CLR-типу, или же просто сырой строкой. Кстати, так же есть атрибут [assembly: TsReference], который добавит желаемый референс во все генерируемые файлы. То же самое делает fluent-вызов .AddReference, будучи примененным на ConfigurationBuilder-е.

Заключение

Изложенные примеры доступны в репозитории Reinforced.Typings. Я открыт к предложениям, вопросам и пожеланиям в комментариях к этой статье, а так же в Issues к репозиторию RT. Еще у проекта есть замечательная github-wiki на английском, которую я развиваю по мере наличия свободного времени. Так же был (и есть) проект с русской документацией на RTFD, но он сейчас в суспенде.
Что касается статей и планов на будущее, то я вижу так что это последняя статья про RT, так как сам по себе RT является лишь компонентом моего другого интересного проекта — Reinforced.Lattice, который я выложу несколько позже, ибо как сейчас он проходит стадию обкатки и тестирования на живых людях. Мне почему-то кажется, что он вам понравится. Так что, следующая статья от меня будет уже про Lattice и, вероятнее всего, не скоро.

Спасибо что дочитали до конца. Это помогает мне не забрасывать проект:)

Reinforced.Typings на Github
Reinforced.Typings в NuGet

______________________

Текст подготовлен в Редакторе Блогов от SoftCoder.ru