Extending the
Jump to navigation
Jump to search
In Progress. In Progress. In Progress.
Back
Back
Table of Contents
Overview
The .NET Reference Implementation ships with a wide array of knobs and configuration settings that let you tweak the out-of-the box code. You can also customize most key components with custom code - Plugin Assemblies.
Before you set out to write custom code, do review what the system already provides for free.
To write custom code you can:
- Run the RI as is, and have it pull in custom plugin Assemblies for features you wish to customize/optimize. You specify the plugin assemblies entirely through the standard Xml configuration files used by the RI.
- OR Sync to the open source code and build your own components that reference the .NET projects - then implement interfaces such as ICertificateResolver.
Configuring Out of the Box Options
All the knobs and options the RI ships with:
- Gateway Configuration Settings
- Dns Server Settings
- Config Service (Middle Tier) settings
- Dns Record Responder Service (Middle Tier) settings
- Log File Settings
- Config Sections
Message Routing
After validating and accepting an incoming message (sent by an external entity), the SMTP Gateway can run custom message handler code, known as routes.
The Gateway ships with built in route types. You can also write your own plugin message handler in any .NET language, and point the Gateway at it by making a simple addition to the Gateway's Xml config file.
Routes and handlers are associated with address types, which is a string you associate with an email address. You can assign the same address type to multiple email addresses. You manage email addresses and their associated address types by using the WCF Address Manager service in the Config Middle Tier Service. ConfigConsole is the default tool for address management, although you can also build your own tools or integrate the Address Manager into your own code by using the predefined WCF proxies that come with Health.Direct.Config.Client.
The Gateway selects Routes by inspecting the "To" for the message. It finds the address type for each email address, then selects routes. It then runs each discovered route sequentially.
Load Balancing
A route is a collection of message receivers.
The Gateway will automatically:
- Round-robin load balance over the set of receivers in a route.
- If a selected receiver is non-responsive, or throws exceptions, randomly selects an alternative receiver for the message.
You can configure the gateway to place incoming messages in folders or file shares.
Each Route can contain multiple folder/fileshare receivers for both loadbalancing and redundancy.
Plugin Routes
Plugin Routes are .NET objects that implement two interfaces:
- IPlugin [Health.Direct.Common.Routing]: The Gateway invokes IPlugin methods to initialize your plugin and pass in configuration settings.
- IReceiver<ISmtpMessage>[Health.Direct.Common.Routing, Health.Direct.SmtpAgent]:
A Plugin Route is a receiver of ISmtpMessage
A Plugin Route hands ISmtpMessage to an Assembly/Type that is loaded dynamically.
Using the Plugin with the Gateway
Once your custom route is ready (and debugged), you can point the Gateway at it by altering the configuration file. See documentation for the Gateway Configuration File for details.
Plugin Routes
Sample Code
To learn how to write plugin routes, peruse the code for SmtpMessageForwarder, a trivial plugin that forwards a given message to another SMTP server:
<SmtpAgentConfig>
.....
<IncomingRoutes>
....
<PluginRoute>
<AddressType>SMTP</AddressType>
<Receiver>
<TypeName>Health.Direct.SmtpAgent.SmtpMessageForwarder, Health.Direct.SmtpAgent</TypeName>
<Settings>
<AddressType>SMTP</AddressType>
<Server>foo.xyz</Server>
<Port>33</Port>
</Settings>
</Receiver>
<Receiver>
<TypeName>Health.Direct.SmtpAgent.SmtpMessageForwarder, Health.Direct.SmtpAgent</TypeName>
<Settings>
<AddressType>SMTP</AddressType>
<Server>bar.xyz</Server>
<Port>39</Port>
</Settings>
</Receiver>
</PluginRoute>
...
Certificate and Anchor Resolution
Plugin Certificate Resolvers
Not supported in current installer yet (coming in next release).
For now, to use this feature, you must build the RI yourself.
Sample Source Code
Plugin Settings Source Code
A plugin certificate resolver is a CUSTOM certificate resolver. It is arbitrary Type (Assembly + Type) that implements ICertificateResolver interface.
You use this object to define the plugin which will be loaded and plugged into the Direct Agent's Certificate resolution pipeline.
If your resolver also implements IPlugin, then you will be called to initialize yourself with settings (see below). Also see Health.Direct.Agent.Tests.MachineResolverProxy for sample code
<SmtpAgentConfig> .... <PublicCerts> .. (other optional resolvers) <PluginResolver> <Definition> <TypeName>Health.Direct.Agent.Tests.MachineResolverProxy, Health.Direct.Agent.Tests</TypeName> <Settings> <Name>NHINDPrivate</Name> </Settings> </Definition> </PluginResolver> ....
Plugin Anchor Resolvers
Not supported in current installer yet (coming in next release).
For now, to use this feature, you must build the RI yourself.
Custom Loggers
Custom messsaging Auditing
IAuditor interface. [Health.Direct.SmtpAgent]
Web Service Middle Tier
[TODO]