Configuration

The configuration of the Altairis Mail Toolkit is done using standard .NET configuration mechanism. In case of ASP.NET application it means the web.config file.

Registering configuration section

First of all, you must register the altairis.mailToolkit configuration section in the configSections element of your configuration file:

<configuration>
    <configSections>
        <section name="altairis.mailToolkit" type="Altairis.MailToolkit.Configuration.MailToolkitConfigurationSection, Altairis.MailToolkit" />
    </configSections>
    <!-- rest of your configuration goes here -->
</configuration>

Configuring mail distribution methods

Standard .NET configuration

Altairis Mail Toolkit can use standard .NET mailing classes to send its messages, unless Transport Providers are configured. In such case you must use the standard system.net/mailSettings configuration section to configure mail delivery. For example:
<system.net>
    <mailSettings>
        <smtp deliveryMethod="SpecifiedPickupDirectory">
            <specifiedPickupDirectory pickupDirectoryLocation="C:\InetPub\MailRoot\pickup"/>
            <network host="localhost" />
        </smtp>
    </mailSettings>
</system.net>
See MSDN documentation for detailed information.

Transport providers

Altairis Mail Toolkit can use any other means to send messages, such as 3rd part services like SendGrid, Postmark, Amazon SMS or its own SmtpShovel, designed to be used with Azure Web Sites. See Transport Providers for more information.

Minimal required configuration

To use the Altairis Mail Toolkit, you must set two mandatory configuration parameters: the From address and type of resource file used.

The following is example of minimal configuration for ASP.NET Web Site project (see below for explanation of type name):
<altairis.mailToolkit>
    <templateResource type="Resources.MailerTemplates, App_GlobalResources" />
    <from address="from@example.org" />
</altairis.mailToolkit>

Full configuration

Full configuration options are specified in the following XML syntax:
<altairis.mailToolkit>
    <templateResource type="Resources.MailerTemplates, App_GlobalResources" 
        subjectFormatKey="_SubjectFormat" bodyFormatKey="_BodyFormat" 
        subjectFormatSuffix="Subject" bodyFormatSuffix="Body" />
    <from address="from@example.org" displayName="From Name" displayNameEncoding="UTF-8" />
    <sender address="sender@example.org" displayName="Sender Name" displayNameEncoding="UTF-8" />
    <replyTo address="reply-to@example.org" displayName="Reply-To Name" displayNameEncoding="UTF-8" />
    <encoding subject="UTF-8" body="UTF-8" />
</altairis.mailToolkit>

All elements and attributes except templateResource/@type and from/@address are optional.
  • templateResource element: configures the template resource
    • type attribute is name of the type of resource file to be used. See below for explanation.
    • subjectFormatKey and bodyFormatKey are names of resource keys for general e-mail format. See Preparing resource files for details.
    • subjectFormatSuffix and bodyFormatSuffix attributes are names of key suffixes for template mail body and subject. Again, see Preparing resource files for details.
  • from element: configures the address messages are coming from
    • address is e-mail address in common user@host format
    • displayName is display name to be used
    • displayNameEncoding is IANA name for encoding to be used. Defaults to UTF-8. See MSDN documentation for more info.
  • sender element: configures the sender address. See E-mail basics for explanation and from element documentation for attributes.
  • replyTo element: configures default reply address. See E-mail basics for explanation and from element documentation for attributes.
  • encoding specifies encoding (character set) for message body and subject. In both cases defaults to UTF-8. See MSDN documentation for more info.

Resource type names

The toolkit requires the resource type name to be specified. The format of required name string is common in .NET: TypeName, AssebmlyName. The values are different for Web Site projects and Web Application projects.

Web site projects

Web site projects are quite special in way how they are compiled on demand. In their case, resource files must be placed in ~/App_GlobalResources/ folder and are compiled into assembly App_GlobalResources and namespace called Resources. Therefore if you'll create file named ~/App_GlobalResources/MailerTemplates.resx, the type specification required would be
<templateResource type="Resources.MailerTemplates, App_GlobalResources" />

The only part of name which may change is the MailerTemplate - namespace and assembly name are fixed.

Web application projects (and all other project types)

In all other project types, resources are compiled manually and are placed in the output assembly. You may create project compiling to MyAssembly.dll with root namespace MyNamespace. If you'll create resource file in ~/Resources/MailerTemplates.resx, the configuration would have the following syntax:
<templateResource type="MyNamespace.Resources.MailerTemplates, MyAssembly" />

Last edited Jun 3, 2013 at 2:50 PM by altair, version 3

Comments

No comments yet.