Skip to content

Fluent configuration

Jump to bottom Edit New page
Pavel Novikov edited this page Jan 13, 2016 · 20 revisions

Fluent configuration is Reinforced.Typings configuration specified as sequence of calls to Reinforced.Typings.Fluent.ConfigurationBuilder class. It is somehow more comfortable than attributes configuration in some cases. Anyway fluent configuration does not restrict attributes configuration somehow. So attributes are safe to be used together with fluent configuration.

Important! If attributes configuration contrary to the fluent configuration then RT will act according to fluent configuration.

Table of contents

Starting with fluent configuration

To enable fluent configuration for Reinforced.Typings follow 3 simple steps:

  1. Create static class containing static method that consumes instance of Reinforced.Typings.Fluent.ConfigurationBuilder as follows:

    using Reinforced.Typings.Fluent;

namespace YourProjectNamespace {
    public static class ReinforcedTypingsConfiguration
    {
        public static void Configure(ConfigurationBuilder builder)
        {
            // fluent configuration goes here
        }
    }    
}

  2. Go to Reinforced.Typings.settings.xml and set there RtConfigurationMethod parameter to full-qualified name of Configure method as follows:

    ...
    <RtConfigurationMethod>YourProjectNamespace.ReinforcedTypingsConfiguration.Configure</RtConfigurationMethod>
...

  3. Rebuild your solution. Now your TypeScript code will be generated according to calls made to ConfigurationBuilder.

Configuration builder methods - single and plural

Configuration builder contains 6 main methods:

  • ExportAsInterface/ExportAsInterfaces
  • ExportAsClass/ExportAsClasses
  • ExportAsEnum/ExportAsEnums

Lets call:

  • ExportAsInterface, ExportAsClass, ExportAsEnum - "Single" configuration builder methods
  • ExportAsInterfaces, ExportAsClasses, ExportAsEnums - "Plural" configuration builder methods

"Single" versions of these methods requires to specify exported type as follows:

public static void Configure(ConfigurationBuilder builder)
{
    builder.ExportAsInterface<IMyInterface>();
}

"Single" versions returns instance of interface/class/enum generic configuration builder. To configure exporting details for specified type you should simply continue call chain like this:

public static void Configure(ConfigurationBuilder builder)
{
    builder.ExportAsInterface<IMyInterface>()
            .WithPublicMethods()        // extension methods calls
            .WithPublicProperties()     // to interface configuration builder`
            .OverrideName("IMyCustomInterface");
}

Also it is safe to perform multiple "single" method calls:

public static void Configure(ConfigurationBuilder builder)
{
    builder.ExportAsInterface<IMyInterface>()
            .WithProperty(c => c.MyProperty, p => p.CamelCase());
            
    builder.ExportAsInterface<IMyInterface>()
            .WithProperty(c => c.AnotherProperty, p => p.Type<Func<int,bool>>()); // no crime!
}

"Plural" versions of these methods consumes 2 parameters:

  • set (IEnumerable) of types to be exported
  • action that should be performed on each type's configuration builder

Fluent configuration for "plural" methods looks like this:

public static void Configure(ConfigurationBuilder builder)
{
    builder.ExportAsInterfaces(
        new Type[] {    typeof(IMyInterface), 
                        typeof(IAnotherInterface), 
                        typeof(MyClass)
                   },
        conf => conf.WithPublicMethods().WithPublicProperties();
    );
    // this will export IMyInterface, IAnotherInterface, MyClass
    // as TS interfaces including all public methods and all public properties            
}

Note that in "single" fluent methods returns generic builders but "plural" dont. So you can use strongly typed calls e.g. to specify configuration for particular properties when you are using "single" method. Due to C# type system this approach is not applicable for "plural" methods:

public static void Configure(ConfigurationBuilder builder)
{
    // look, I can do this for .ExportAsInterface<T>!
    builder.ExportAsInterface<IMyInterface>()
            .WithProperty(c => c.MyProperty, p => p.CamelCase()); 
       
    builder.ExportAsInterfaces(
        new Type[] { typeof(IMyInterface) },
        conf => conf
            .WithPublicMethods()
            .WithPublicProperties()
            // but cannot for .ExportAsInterfaces :(
            // .WithProperty(c => c.MyProperty, p => p.CamelCase()) 
            
            // but still can do like this! :)
            .WithProperties(
                prop => prop.Name == "MyProperty",
                conf => conf.CamelCase())
            ;
    );           
}

Classes, interfaces and enums are exported differently. For further information see which fluent methods present for interfaces, classes and enums.

Additional ConfigurationBuilder methods

Besides methods mentioned above ConfigurationBuilder has 2 more:

AddReference

Arguments: string reference: path for ///<reference ...> directive being added to each exported file

Path to file that will be written in ///<reference path="..."> directive that will be placed on top of every generated file (analogue for [TsReference] attribute)

TryLookupDocumentationForAssembly

Arguments:

  • Assembly assmbly: Assembly which documentation should be included
  • string documentationFileName = null: Override XMLDOC file name if differs (please include .xml extension)

Tries to find documentation .xml file for specified assembly and take it in account when generating documentaion. See details on JSDOC support page

Fluent methods for types

Interface

Methods family Description
WithProperty/With*Properties Contains 7 different overloads allowing to variously select properties to be included to typing for specified type. Note that all there is not auto-export in fluent configuration. You must specify which properties to export and configuration for exporting them. See property configuration for all avaiable property exporting configuration methods.
WithMethod/With*Methods Contains 11 different overloads to variously select methods to be included to typing for specified type as class/interface functions. Note that all there is not auto-export in fluent configuration. You must specify which methods to export and configuration for exporting them. See method configuration for all avaiable method exporting configuration methods. Also some of overloads allow to specify export configuration for method parameters. Refer to this section to see how to specify configuration for methods parameters.
WithCodeGenerator Allows to specify ITsCodeGenerator that should be used to export this member. For more details please refer to Custom code generators page
AddReference Allows to specify additional paths or types that will be added as ///<reference ... > directive to file containing type being configured. This call only makes sense in case of [[multiple files export
ExportTo Specifies file where current type will be exported to. This call only makes sense in case of [[multiple files export
OverrideName Overrides name
DontIncludeToNamespace Configures exporter dont to export type to corresponding namespace
OverrideNamespace Configures exporter to export type to specified namespace
AutoI Forces exporter to add I letter as interface prefix.

Class

Method family Description
WithProperty/With*Properties Contains 7 different overloads allowing to variously select properties to be included to typing for specified type. Note that all there is not auto-export in fluent configuration. You must specify which properties to export and configuration for exporting them. See property configuration for all avaiable property exporting configuration methods.
WithField/With*Fields Mostly similar to WithProperty/With*Properties but for class fields
WithMethod/With*Methods Contains 11 different overloads to variously select methods to be included to typing for specified type as class/interface functions. Note that all there is not auto-export in fluent configuration. You must specify which methods to export and configuration for exporting them. See method configuration for all avaiable method exporting configuration methods. Also some of overloads allow to specify export configuration for method parameters. Refer to this section to see how to specify configuration for methods parameters.
WithCodeGenerator Allows to specify ITsCodeGenerator that should be used to export this member. For more details please refer to Custom code generators page
AddReference Allows to specify additional paths or types that will be added as ///<reference ... > directive to file containing type being configured. This call only makes sense in case of [[multiple files export
ExportTo Specifies file where current type will be exported to. This call only makes sense in case of [[multiple files export
OverrideName Overrides name
DontIncludeToNamespace Configures exporter dont to export member to corresponding namespace
OverrideNamespace Configures exporter to export type to specified namespace

Enum

Method family Description
WithCodeGenerator Allows to specify ITsCodeGenerator that should be used to export this member. For more details please refer to Custom code generators page
AddReference Allows to specify additional paths or types that will be added as ///<reference ... > directive to file containing type being configured. This call only makes sense in case of [[multiple files export
ExportTo Specifies file where current type will be exported to. This call only makes sense in case of [[multiple files export
DontIncludeToNamespace Configures exporter dont to export member to corresponding namespace
OverrideNamespace Configures exporter to export type to specified namespace
Value Retrieves configuration builder for particular enumeration value. Consumes enum value itself or string enum value name.

Fluent methods for members

Method

Method family Description
Ignore Ignores specified members during exporting. Ignored members won't appear in resulting typing.
WithCodeGenerator Allows to specify ITsCodeGenerator that should be used to export this member. For more details please refer to Custom code generators page
CamelCase Forces member name to be in camelCase notation
Returns Overrides member type name on export with textual string. Beware of using this setting because specified type may not present in your TypeScript code and this may lead to TypeScript compilation errors

Property

Method family Description
CamelCase Forces member name to be in camelCase notation
ForceNullable Forces property to be a nullable. When set to true then property will be generated as [property]? : [type] with forcibly added question mark denoting nullable field
Ignore Ignores specified members during exporting. Ignored members won't appear in resulting typing.
WithCodeGenerator Allows to specify ITsCodeGenerator that should be used to export this member. For more details please refer to Custom code generators page
Type Overrides member type name on export with textual string. Beware of using this setting because specified type may not present in your TypeScript code and this may lead to TypeScript compilation errors

Enum value

Method family Description
OverrideName Overrides enumeration value name
Ignore Ignores specified members during exporting. Ignored members won't appear in resulting typing.

Method parameter

To specify configuration for method parameter you should use .WithMethod fluent configuration method for class/interface and specify exported method using lambda expression replacing all parameters with Ts.Parameter call. Like this:

public interface IMyInterface
{
    void DoSomething(int a, string b);
}

public static void Configure(ConfigurationBuilder builder)
{
    builder.ExportAsInterface<IMyInterface>()
        .WithMethod(c => 
            c.DoSomething(
                Ts.Parameter<int>(conf => conf.OverrideName("blah")), // conf is parameter configuration builder
                Ts.Parameter<string>()));
}

Reinforced.Typings.Fluent.Ts class is special dummy class used only for specifying configuration for parameter export

Method family Description
Type Overrides member type name on export with textual string. Beware of using this setting because specified type may not present in your TypeScript code and this may lead to TypeScript compilation errors
CamelCase Forces member name to be in camelCase notation
DefaultValue Sets parameter default value
Ignore Ignores specified members during exporting. Ignored members won't appear in resulting typing.
WithCodeGenerator Allows to specify ITsCodeGenerator that should be used to export this member. For more details please refer to Custom code generators page
Add a custom footer
Add a custom sidebar
Clone this wiki locally