Rather than setting all build options and flow elements explicitly in code form, it is often preferable to make the Pipeline configurable without recompiling. A pipeline builder allows this via its 'BuildFromConfiguration' method.
Usage
A configuration can be parsed manually from XML, JSON or any other source and given to a pipeline builder. Alternatively, in web integrations, a configuration file is loaded automatically.
Note, the possible format of the configuration file varies greatly between languages, with some languages having many options and others only having one. Where possible, we recommend using JSON as the simplest and most transferable configuration format.
Parsing XML
Select a language for an example of parsing XML.
var config = new ConfigurationBuilder()
.AddXmlFile("configuration.xml")
.Build();
PipelineOptions options = new PipelineOptions();
config.Bind("PipelineOptions", options);
IPipeline pipeline = new PipelineBuilder(loggerFactory)
The core build from configuration logic ultimately calls the same configuration methods, on the same builders as the developer does if they configure the Pipeline in code.
There are several rules that govern how a value in a configuration file is mapped to a builder or configuration method:
Element Builder Names
The element builder name is used to determine the element builder that we want to use. Each of the following is tried in turn to find a builder that matches the supplied name:
Case insensitive match on type name. (e.g. 'MyElementBuilder' matches a type with that name.)
Case insensitive match on type name suffixed with 'builder'. (e.g. 'MyElement' matches a type called 'MyElementBuilder'.)
Where the language allows it, match on some alternative name for the builder.
Element Build Parameters
The key value of each entry in the 'build parameters' list associated with each element is used to determine the method to call on the element builder. Each of the following is tried in turn to find a method that matches the supplied name:
Case insensitive match on method name. (e.g. 'SetCacheSize' matches a method with that name.)
Case insensitive match on method name prefixed with 'set'. (e.g. 'CacheSize' matches a method called 'SetCacheSize'.)
Where the language allows it, match on some alternative name for the method.
The value part of each entry in the 'build parameters' list is then passed to the matching method as a parameter. For strongly-types languages, this may also involve parsing a string value from the configuration into the required type.
If there are any build parameters for which a method cannot be found, they will be used to set parameters on the 'Build' method once configuration is complete. In this case, a simple case-insensitive match is performed to determine the parameter value to set.
Pipeline Build Parameters
Pipeline build parameters work in the same way as element build parameters but they are used to call configuration methods on the pipeline builder instead of the element builder.
See above for all the rules governing this.
Alternative Naming Details
Some languages have a mechanism for specifying alternative names for builders and methods. These can be used to match against supplied configuration options.
Select a language for information of specifying an alternative name for element builders and configuration methods.
The AlternateNameAttribute can be used to decorate element builder classes as well as configuration methods on an element builder. This can be used to specify one or more other names to match on when building from configuration.
The ElementBuilder(alternateName) attribute can be used to decorate element builder classes. This can be used to specify one or more other names to match when buiding from configuration.
todo
todo
Internals
The exact internal mechanics of the builder will depend on the language being used. Wherever possible, the rules for mapping are consistent between languages but this cannot always be achieved.
Select a language for more details of the internals of build from configuration.
In .NET, pipeline builder relies on reflection to find the correct builder to build the flow elements required by the configuration. For this reason, it is necessary for the libraries that contain the element builders for those flow element to be loaded. This can be done in a number of ways:
Additionally, the pipeline builder will need to know how to supply any dependencies required by the element builders it creates.
By default, the pipeline builder will call a constructor on element builder that takes an ILoggerFactory if one is available. If not, it will call the default constructor - if one is available.
This can be resolved by passing an IServiceProvider to the pipeline builder on construction that is populated with instances of the services that element builders will require.
