Reinforced.Typings - more details

Hello again.
What about what, and I'm again about Reinforced.Typings - my library for generating TypeScript glue-code from C # -series, a brief introduction to which I did in a previous post . After that, he immediately received a number of questions and comments (not only on Habrahabr, by the way - many of those interested simply were not registered on it). For this, of course, many thanks to all, but based on the analyzed information, I realized that one brief post is not enough to describe how and what is realized. It turns out that people ask questions, “but is this supported?” And everyone has to explain the same thing time after time. So in this article I will make a small cheatsheet for attributes, fluent-configuration and tell you about additional features. In general, you are welcome. Beware, longrid and background information!

In the previous series

When I first talked about Reinforced.Typings, I casually mentioned that there are different attributes and they have a lot of all sorts of different custom properties, there are some code generators and something about the TypeScript assembly process. Everything is somehow messy, superficially, without details. Let's break it down. I am as concise as possible, but I’ll tell you in detail about the various configuration options, the build script, how it all works together, and what can be fashioned from all this.
In general, this article is a kind of manual / tutorial / cheatsheet for Reinforced.Typings, because I still do not have the time and resource to write full documentation in English. Of course, not everything is so sad - I already gathered my courage and wrote a whole plan of documentation. However, the “father of Russian democracy” was not enough for a larger (+ article on Habrahabr). So let's go.
PS: It is worth noting that I still counted a little and in the time that has passed since the last article was written, I finished some of the features in the library, fixed the bugs (so far without them). Therefore, the presented material is relevant from version 1.0.7.

How does it generally work?

You are relaxed, satisfied, you have warm feet and you write in C # and ASP.NET MVC using TypeScript. You install Reinforced.Typings from NuGet with the command
')

PM > Install-Package Reinforced.Typings 

Reinforced.Typings is immediately integrated into the build process of your application, starting at every build of the project. This moment is controlled from the Reinforced.Typings.settings.xml file, which is added to the root of your project — I call this the “build configuration”. Having started, Reinforced.Typings does its dark work by loading the build of your project and climbing into it through Reflection. The desired TypeScript glue-code (for example, TypeScript-interfaces corresponding to your server TransferObjects / View-models, transmitted to the client) is generated based on two possible factors:

• Attribute configuration - that is, types are exported and their members are marked with special attributes (their list and properties will be given below)
• Fluent configurations - when the method specified in the build config is called to find out how and what you want to generate. This configuration option will also be covered further.

Attribute and fluent configuration can be combined - this is not forbidden. They basically provide equal opportunities, but differ in flexibility.
In general, all the secret knowledge necessary to use Reinforced.Typings, is to navigate the parameters of its configuration. And there are only 3 setting points mentioned above - the assembly configuration (Reinforced.Typings.settings.xml), the attribute and fluent configuration. The build configuration determines the global parameters of the whole process, such as the files to which the generated code will be written, whether to export documentation, which assemblies to plug in, etc. Attribute and fluent configurations determine which code to generate and for which types.

Assembly configuration

Reinforced.Typings generates your taipings each time you rebuild a project. As stated above, it is embedded in the project building process. This is done through the mechanism of embedding .targets and .props files from the package that appeared in version NuGet 2.5.

Some parameters for starting the generator are in the Reinforced.Typings.settings.xml file, which is a piece of MSBuild script that connects to the .targets file of the package itself. Reinforced.Typings.settings.xml is added to the root of your project when the package is installed. By default it looks like this . I would not argue that it is well documented (mainly because of the brokenness of my English), so I’m including a cheatsheet describing configuration parameters:

Attributes

One assembly configuration for successful export is not enough. You also have to specify RT what exactly you want to see in the generated TypeScript files. This can be done, for example, by hanging the corresponding attributes over the exported types (classes, interfaces, enums) and their members. This is what I call the attribute configuration. There is also a fluent configuration, but I will talk about it a little later, because it is completely based on the attribute and largely repeats it, and according to this, it will be more pedagogical to tell first about the attribute configuration.
All attributes of Reinforced.Typings are, oddly enough, in the Reinforced.Typings.Attributes namespace, which can confuse a newbie (sarcasm). All attributes can be inherited. All properties are overloaded. As one of the available techniques of work - you can inherit from any of them and make your attribute so as not to drag a pack of parameters with you each time.
Below I give a cheatsheet for all available attributes. The expression “required attribute” in it means that if you do not put this attribute, then the corresponding entity will not be exported to TypeScript.

Attribute Name	Required?	Result in taiping	Exported (patient)
TsInterface	Yes	TypeScript interface	Class, interface, structure
TsClass	Yes	TypeScript class	Class structure
TsProperty	Not	Interface / class field	Property, field (class / structure)
TsFunction	Not	Interface / class method (in the case of a class, the body is exported as return null; if the method is non-void and as empty in the case of void)	Property, field (class / structure)
TsEnum	Yes	TypeScript enumeration	enum obviously
TsValue	Not	One of the TypeScript enumeration values	Enum value, not obvious
TsParameter	Not	Parameter (formal argument) of the TypeScript method	The parameter of the method, oddly enough
TsGeneric	Not	Type parameter of the TypeScript method / class / whatever	Type parameter
TsIgnore	Not	Patient will not be exported to TypeScript	Property, constructor (!), Field, method, parameter

Attribute properties

There are a lot of properties, so I turned their list into a spoiler so as not to litter the article. There, in the list of properties, I specify the name of the property, in parentheses the value of the default property and describe what it controls. This is mostly background information that is duplicated in XMLDOC, in English only. By this - open carefully.


It is worth noting that attributes have a small inheritance hierarchy, so some properties are in several attributes and do about the same thing (say, Name, overrides the name of the exported class / interface, but also works for method or property parameters).

Export TypeScript code to multiple files

This feature is enabled when RtDivideTypesAmongFiles is set to true in the build config. By default, with no additional configuration, RT scatters all your classes according to the good old tradition of OO languages ​​- the class is in a separate file, and even put in a subdirectory according to Namespaces (in order not to generate extra directories in this connection, it is recommended to use build configuration parameter RtRootNamespace). There is also one nuance - the studio does not always see that any of the types used in the .ts file lies in the adjacent file and underlines with red how much in vain. To avoid such a situation, add the directive /// <reference path = "..."> to all .ts files. — RT , /, , . . . MasterCard TsAddTypeReference. , , TypeScript- .

CodeGenerator

TsAttributeBase, — CodeGeneratorType Type. What it is? . — , 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-. For example:
   

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

   
   

Everything. (: ) . fluent- ( - Tremor , ), . , , , .

, ConfigurationBuilder- ( ), , XMLDOC. fluent-, :

, . , .
: TsBaseParam TsGeneric . fluent- . fluent- . — .
: 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- . , ( , ). , .
. .

Conclusion

, , , - . , github. — .
, - feedback-. — issues github . pull- — , fulltime- .
NuGet- , .