Reinforced.Typings — больше деталей26.10.2015 07:03

И снова здравствуйте.
Кто о чем, а я снова о Reinforced.Typings — своей библиотеке для генерации TypeScript-ового glue-кода из C#-сборок, краткое введение в которую я сделал в предыдщем посте. После чего немедленно получил ряд вопросов и комментариев (не только на Хабрахабре, к слову — многие из заинтересовавшихся просто на нем не зарегистрированы). За это, конечно, всем огромное спасибо, но исходя из проанализированной информации, я понял что одного краткого поста не достаточно, чтобы описать как и что реализуется. Получается что люди задают вопросы «а вот это вот поддерживается?» и каждому приходится объяснять раз за разом, одно и то же. Так что в этой статье я сделаю небольшой cheatsheet по атрибутам, fluent-конфигурации и расскажу про дополнительные возможности. В общем, милости просим. Осторожно, лонгрид и справочная информация!

В предыдщей серии

Когда я впервые рассказывал про Reinforced.Typings, я вскользь упомянул, что есть разные атрибуты и у них много всяких-разных кастомных свойств, есть какие-то кодогенераторы и что-то про процесс сборки TypeScript. Все как-то сумбурно, поверхностно, без подробностей. Давайте разложим по полочкам. Я максимально сжато, но детально расскажу про различные варианты конфигурации, а под конец вас ждет обещаный пример с генерацией оберток методов контроллеров.
В общем и целом эта статья — своеобразный manual/методичка/cheatsheet по Reinforced.Typings, потому как у меня все еще нет времени и ресурса написать полноценную документацию на английском. Конечно, не все так печально — я уже собрался с духом и написал ажно целый план документации. Однако на большее (+ статью на Хабрахабре) «отца русской демократии» не хватило. Итак, поехали.
P.S.: Стоит отметить, что я немного все-таки считерил и за время, которое прошло с момента написания последней статьи, допилил некоторые возможности в библиотечке, починил баги (куда уж без них). По сему, излагаемый материал актуален с версии 1.0.7.

Как оно в целом работает

Вы расслаблены, довольны, у вас теплые ноги и вы пишете на C# и ASP.NET MVC с использованием TypeScript. Вы устанавливаете Reinforced.Typings из NuGet командой

PM > Install-Package Reinforced.Typings

Reinforced.Typings сразу же встраивается в процесс сборки вашего приложения, запускаясь при каждом билде проекта. Этот момент контролируется из файла Reinforced.Typings.settings.xml, который добавляется в корень вашего проекта — я называю это «сборочная конфигурация». Запустившись, Reinforced.Typings делает свое темное дело, подгружая сборку вашего проекта и залезая в нее через Reflection. Желанный TypeScript glue-код генерируется основываясь на двух возможных факторах:

• Атрибутной конфигурации — то есть экспортируются типы и их члены, помеченные специальными атрибутами (их список и свойства будут даны ниже)
• Fluent-конфигурации — когда для выяснения как и что вы хотите сгенерировать вызывается метод, указанный в сборочном конфиге. Этот вариант конфигурации так же будет освещен далее

Атрибутную и fluent-конфигурацию можно комбинировать — это не возбраняется. Они в основном дают равные возможности, но различаются по гибкости.
В общем-то, все тайные знания, необходимые для использования Reinforced.Typings, заключаются в том, чтобы ориентироваться в параметрах его конфигурации. И тут всего 3 точки настройки, упомянутые выше — сборочная конфигурация (Reinforced.Typings.settings.xml), атрибутная и fluent-конфигурация. Сборочная конфигурация определяет глобальные параметры всего процесса вроде того, в какие файлы будет записан сгенерированный код, экспортировать ли документацию, какие сборки подключать и т.п. Атрибутная и fluent-конфигурации определяют какой именно код генерировать и для каких типов.

Сборочная конфигурация

Reinforced.Typings генерирует ваши тайпинги при каждой пересборке проекта. Как было оговорено выше, он встраивается в процесс сборки проекта. Делается это посредством посредством мехнизма встраивания .targets и .props-файлов из пакета, который появился в версии NuGet 2.5.

Некоторые параметры запуска генератора вынесены в файл Reinforced.Typings.settings.xml, кой являет собой кусок MSBuild-скрипта, подключающийся в .targets-файле самого пакета. Reinforced.Typings.settings.xml добавляется в корень вашего проекта при установке пакета. По умолчанию он выглядит вот так вот. Я бы не стал утверждать, что он хорошо документирован (в основном по причине ломанности своего английского), поэтому привожу табличку-cheatsheet с описанием параметров конфигурации:

Атрибуты

Одной сборочной конфигурации для успешного экспорта недостаточно. Вам так же придется указать RT что конкретно вы хотите видеть в сгенерированных TypeScript-файлах. Сделать это можно, например, повесив соответствующие атрибуты над экспортируемыми типами (классами, интерфейсами, перечислениями) и их членами. Это я называю «атрибутная конфигурация». Есть еще fluent-конфигурация, но о ней я расскажу чуть позже, потому как она полностью базируется на атрибутной и во многом её повторяет, а по сему — будет педагогичнее рассказать сначала про атрибутную конфигурацию.
Все атрибуты Reinforced.Typings лежат, как ни странно, в пространстве имен Reinforced.Typings.Attributes, что может сбить новичка с толку (sarcasm). От всех атрибутов можно унаследоваться. Все свойства перегружаются. Как одна из доступных техник работы — вы можете унаследоваться от любого из них и сделать свой атрибут, чтобы не таскать за собой пачку параметров каждый раз.
Ниже я привожу cheatsheet по всем доступным атрибутам. Выражение «обязательный атрибут» в нем означает, что если вы этот атрибут не поставите, то экспортироватся в TypeScript соответствующая сущность не будет.

Свойства атрибутов

Свойств достаточно много, поэтому я свернул их список в спойлер, дабы не засоряли статью. Там, в списке свойств я указываю имя свойства, в скобочках значение свойства по умолчанию и описываю что оно контролирует. Это по большей части справочная информация, которая продублирована в XMLDOC-ах, только на английском. По сему — открывать осторожно.

Стоит отметить, что у атрибутов наличествует небольшая иерархия наследования, поэтому некоторые свойства есть в нескольких атрибутах и делают примерно одно и то же (скажем, Name, переопределяет имя экспортируемого класса/интерфейса, но так же работает и для параметров метода или свойства).

Экспорт TypeScript-кода в несколько файлов

Эта возможность включается при установке RtDivideTypesAmongFiles в true в сборочном конфиге. По умолчанию, без дополнительной конфигурации, RT раскидает все ваши классы согласно старой-доброй традиции ОО-языков — по классу в отдельный файл, да еще и положит в поддиректории согласно Namespace-ам (чтобы не наплодить в связи с этим лишних директорий, рекомендуется использовать параметр сборочного конфига RtRootNamespace). Так же есть один нюанс — студия не всегда видит, что какой-либо из используемых в .ts-файле типов лежит в соседнем файле и подчеркивает красным почем зря. Чтобы такой ситуации не возникало — во все .ts-файлы нужно добавить директиву ///. Так вот — в большинстве случаев с корректным размещением этой директивы RT справляется сам, инспектируя зависимости типов путем просматривания типов свойств/полей, возвращаемых значений методов, типов параметров и т. п. И это бесценно. Для остального есть MasterCard атрибут TsAddTypeReference. В спойлере ниже речь пойдет о нем, а так же о некоторых других атрибутах, которые влиялют на раскидывание TypeScript-кода по разным файлам.

CodeGenerator

Почти все атрибуты унаследованы от TsAttributeBase, который определяет всего одно свойство — CodeGeneratorType типа Type. Что это такое? А это возможность указать тип кодогенератора для любого члена класса или типа. Кодогенератор — это специальный класс, который должен реализовывать интерфейс Reinforced.Typings.Generators.ITsCodeGenerator, параметризованный:

• System.Type в случае кодогенератора для типа (используется с TsEnum, TsClass, TsInterface)
• System.Reflection.PropertyInfo в случае кодогенератора для property (используется с TsProperty)
• System.Reflection.FieldInfo в случае кодогенератора для поля (используется с TsField)
• System.Reflection.MethodInfo в случае кодогенератора для метода (используется с TsFunction)
• System.Reflection.ParameterInfo в случае кодогенератора для параметра метода (используется с TsParameter)

ITsCodeGenerator определяет всего одно свойство (Settings), которое достаточно реализовать как auto-property и всего один метод — Generate, который принимает на вход:

• TElement, которым и параметризован генератор — сущность, для которой надо сгенерировать TypeScript — код
• TypeResolver — класс, самым ценным методом которого является метод ResolveTypeName, принимающий на вход тип. Он возвращает TypeScript-friendly имя типа, которое можно писать в генерируемый код.
• WriterWrapper — небольшая обертка над TextWrapper-ом, в который нужно записать генерируемый код
• Так же вы можете использовать свойство Settings внутри метода Generate для того, чтобы, например, посмотреть (или записать в выходной поток) документацию для генерируемой сущности

В RT есть несколько готовых генераторов для классов, интерфейсов, enum-ов, параметров полей, методов и property — они все лежат в пространстве имен Reinforced.Typings.Generators и от них можно наследоваться. Конечно же, ничто не мешает сделать свой кодогенератор напрямую реализовав интерфейс ITsCodeGenerator.
Когда вы сделали свой кодогенератор, нужно указать что нужно использовать именно его, установив свойство CodeGeneratorType соответствующего атрибута в typeof от вашего генератора. Никакого контроля типобезопасности тут, к сожалению нет. Ну то есть если вы укажете CodeGeneratorType = typeof(string), то IntelliSense не скажет что что-то не так. Однако, эта же функциональность предоставляется во fluent-конфигурации (метод .WithCodeGenerator), и вот там уже указать неподходящий кодогенератор вам не дадут.

Fluent-конфигурация

Размещать атрибуты над экспортируемыми типами не всегда удобно. Например, в случае, когда вам надо экспортировать сотню типов из определенного namespace-а, при том выдрать из них определенные свойства и прописать для них определенную конфигурацию экспорта, то размещать атрибуты становится делом несколько скучным и монотонным. К тому же, вы не сможете разместить атрибуты экспорта над сущностями, к исходному коду которых у вас нет доступа. Как раз чтобы побороть это обстоятельство, в версии 1.0.5 была добавлена вомзожность fluent-конфигурации. Начать использовать её наряду с атрибутами можно в 2 простых шага:

1. Создайте отдельный класс, объявите в нем публичный статический метод с единственным параметром типа Reinforced.Typings.Fluent.ConfigurationBuilder. Например, вот так:

   using Reinforced.Typings.Fluent;
   namespace TestProject.App_Start
   {
       public class TypingsConfiguration
       {
           public static void ConfigureTypings(ConfigurationBuilder builder)
           {
               // тут будет ваша fluent-конфигурация
           }
       }
   }
   
   

   
   
2. В сборочной конфигурации укажите используемый fluent-метод. Например, так:

   <RtConfigurationMethod>TestProject.App_Start.TypingsConfiguration.ConfigureTypings</RtConfigurationMethod>
   
   

   
   

Всё. Теперь этот метод будет вызываться каждый раз при перегенерации тайпингов (читай: при пересборке проектов) и готовить конфигурацию экспорта. Через fluent-конфигурацию достаточно легко можно экспортировать пачками однотипные интерфейсы и классы с однотипной же конфигурацией (реализован фич-реквест Tremor, пусть и немного в другом виде), что облегчает задачу в случае большого проекта. Так же несомненным плюсом, на мой взгляд, является строго типизированное указание кодогенератора, благодаря которому вы уже никогда по ошибке не примените кодогенератор для метода на свойствах и наоборот.

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

using Reinforced.Typings.Fluent;
namespace TestProject.App_Start
{
    public class TypingsConfiguration
    {
        public static void ConfigureTypings(ConfigurationBuilder builder)
        {
            builder.ExportAsInterface<ILoginInformation>()
                .WithPublicProperties()
                .WithProperty(c => c.Email).Type<int>();

            builder.ExportAsInterface<ILoginPage>()
                .WithPublicProperties()
                .WithPublicMethods()
                .WithMethod(c => c.FillIn(Ts.Parameter<ILoginInformation>(o => o.Type<string>())))
                .Returns<string>();
            builder.ExportAsInterface<ILoginPage>()
                .WithMethod(c => c.AddOrders(Ts.Parameter<OrdersColelction>()));

            builder.ExportAsInterfaces(
                new[] {
                    typeof (ILoginPage), 
                    typeof (ILoginInformation),
                    typeof(IOrder)
                },
                c => c.ExportTo("login.ts").WithAllMethods(m => m.CamelCase()));
        }
    }
}

В отдельном пояснении, пожалуй, здесь нуждается только Ts.Parameter и метод TryLookupDocumentationForAssembly.
Ts.Parameter — это специальный статический метод, который может принимать на вход построитель fluent-конфигурации для параметров метода. То есть когда вы хотите задать конфигурацию для параметра метода, вы просто говорите нечто вроде

builder.ExportAsInterface<MyClass>()
    .WithMethod(m => m.MyMethod(
            Ts.Parameter<int>(p => p.OverrideName("apple").Type<string>())
              ))
    .Returns<object>();

чтобы получить в TypeScript-е

export IMyClass {
        MyMethod(apple:string):any;
}

/*
При исходных данных
class MyClass
{
        public int MyMethod(int a)
        {
                return 0;
        }
}
*/

На мой взгляд, удобный и элегантный способ.
TryLookupDocumentationForAssembly — это метод самого ConfigurationBuilder-а, который говорит RT поискать файл с xml-документацией для указанной сборки рядом с самой сборкой. Имеет одну перегрузку, которая позволяет указать имя файла непосредственно (таким образом сборка будет использована только для определения директории, в которой надо искать). Я пришел к необходимости добавить этот метод, когда встала необходимость экспортировать документацию из другой сборки.
Вот. Теперь точно всё.

Заключение

Статья вышла довольно крупной, что, в принципе, соответствовало моей цели сделать более-менее подробный мануал при полном отсутствии документации по проекту и категорическом недостатке свободного времени для авторства. Еще меня не хватило на примеры использования, но им я посвящу следующую статью и постараюсь дописать и докоммитить примеры на github. Не стреляйте в пианиста — он пишет когда есть время.
Как обычно, я открыт к пожеланиям-предложениям и прочему feedback-у. Если в ходе использования вы найдете баги — не стесняйтесь отправлять issues на github проекта. Неожиданным pull-реквестам я так же очень рад — писать в одного, совмещая с fulltime-работой становится тяжеловато.
NuGet-пакет проекта лежит там же, где и лежал.

© Habrahabr.ru