SendMail Custom Activity

The SendMail sample demonstrates how to create a custom activity that derives from AsyncCodeActivity to send mail using SMTP for use within a workflow application. The custom activity uses the capabilities of SmtpClient to send email asynchronously and to send mail with authentication. It also provides some end-user features like test mode, token replacement, file templates, and test drop path.

The following table details the arguments for the SendMail activity.

Name	Type	Description
Host	String	Address of the SMTP server host.
Port	String	Port of the SMTP service in the host.
EnableSsl	bool	Specifies whether the SmtpClient uses Secure Sockets Layer (SSL) to encrypt the connection.
UserName	String	Username to set up the credentials to authenticate the sender Credentials property.
Password	String	Password to set up the credentials to authenticate the sender Credentials property.
Subject	InArgument<T><string>	Subject of the message.
Body	InArgument<T><string>	Body of the message.
Attachments	InArgument<T><string>	Attachment collection used to store data attached to this email message.
From	MailAddress	From address for this email message.
To	InArgument<T><MailAddressCollection>	Address collection that contains the recipients of this email message.
CC	InArgument<T><MailAddressCollection>	Address collection that contains the carbon copy (CC) recipients for this email message.
BCC	InArgument<T><MailAddressCollection>	Address collection that contains the blind carbon copy (BCC) recipients for this email message.
Tokens	InArgument<T><IDictionary<string, string>>	Tokens to replace in the body. This feature allows users to specify some values in the body than can be replaced later by the tokens provided using this property.
BodyTemplateFilePath	String	Path of a template for the body. The SendMail activity copies the contents of this file to its body property. The template can contain tokens that are replaced by the contents of the tokens property.
TestMailTo	MailAddress	When this property is set, all emails are sent to the address specified in it. This property is intended to be used when testing workflows. For example, when you want to make sure that all emails are sent without sending them to the actual recipients.
TestDropPath	String	When this property is set, all emails are also saved in the specified file. This property is intended to be used when you are testing or debugging workflows, to make sure that the format and contents of the outgoing emails is appropriate.

Solution Contents

The solution contains two projects.

Project	Description	Important Files
SendMail	The SendMail activity	1. SendMail.cs: implementation for the main activity 2. SendMailDesigner.xaml and SendMailDesigner.xaml.cs: designer for the SendMail activity 3. MailTemplateBody.htm: template for the email to be sent out.
SendMailTestClient	Client to test the SendMail activity. This project demonstrates two ways of invoking the SendMail activity: declaratively, and programmatically.	1. Sequence1.xaml: workflow that invokes the SendMail activity. 2. Program.cs: invokes Sequence1 and also creates a workflow programmatically that uses SendMail.

Further configuration of the SendMail activity

Although not shown in the sample, users can perform addition configuration of the SendMail activity. The next three sections demonstrate how this is done.

Sending an email using tokens specified in the body

This code snippet demonstrates how you can send email with tokens in the body. Notice how the tokens are provided in the body property. Values for those tokens are provided to the tokens property.

IDictionary<string, string> tokens = new Dictionary<string, string>();
tokens.Add("@name", "John Doe");
tokens.Add("@date", DateTime.Now.ToString());
tokens.Add("@server", "localhost");

new SendMail
{
    From = new LambdaValue<MailAddress>(ctx => new MailAddress("john.doe@contoso.com")),
    To = new LambdaValue<MailAddressCollection>(
                    ctx => new MailAddressCollection() { new MailAddress("someone@microsoft.com") }),
    Subject = "Test email",
    Body = "Hello @name. This is a test email sent from @server. Current date is @date",
    Host = "localhost",
    Port = 25,
    Tokens = new LambdaValue<IDictionary<string, string>>(ctx => tokens)
};

Sending an email using a template

This snippet shows how to send an email using a template tokens in the body. Notice that when setting the BodyTemplateFilePath property we don't need to provide the value for Body property (the contents of the template file will be copied to the body).

new SendMail
{
    From = new LambdaValue<MailAddress>(ctx => new MailAddress("john.doe@contoso.com")),
    To = new LambdaValue<MailAddressCollection>(
                    ctx => new MailAddressCollection() { new MailAddress("someone@microsoft.com") }),
    Subject = "Test email",
    Host = "localhost",
    Port = 25,
    Tokens = new LambdaValue<IDictionary<string, string>>(ctx => tokens),
    BodyTemplateFilePath = @"..\..\..\SendMail\Templates\MailTemplateBody.htm",
};

Sending Mails in Testing Mode

This code snippet shows how to set the two testing properties: by setting TestMailTo to all messages will be sent to john.doe@contoso.con (without regard of the values of To, Cc, Bcc). By setting TestDropPath all outgoing emails will be also recorded in the provided path. These properties can be set independently (they are not related).

new SendMail
{
   From = new LambdaValue<MailAddress>(ctx => new MailAddress("john.doe@contoso.com")),
   To = new LambdaValue<MailAddressCollection>(
                    ctx => new MailAddressCollection() { new MailAddress("someone@microsoft.com") }),
   Subject = "Test email",
   Host = "localhost",
   Port = 25,
   Tokens = new LambdaValue<IDictionary<string, string>>(ctx => tokens),
   BodyTemplateFilePath = @"..\..\..\SendMail\Templates\MailTemplateBody.htm",
   TestMailTo= new LambdaValue<MailAddress>(ctx => new MailAddress("john.doe@contoso.com")),
   TestDropPath = @"c:\Samples\SendMail\TestDropPath\",
};

Set-Up Instructions

Access to a SMTP server is required for this sample.

For more information about setting up a SMTP server, see the following links.

• Configuring the SMTP Service (IIS 6.0)

• IIS 7.0: Configure SMTP E-Mail

• How to Install the SMTP Service

SMTP emulators provided by third parties are available for download.

To run this sample

1. Using Visual Studio, open the SendMail.sln solution file.

2. Ensure that you have access to a valid SMTP server. See the set-up instructions.

3. Configure the program with your server address, and From and To email addresses.

   To correctly run this sample, you may need to configure the value of From and To email addresses and the address of the SMTP server in Program.cs and in Sequence.xaml. You will need to change the address in both locations since the program sends mail in two different ways

4. To build the solution, press CTRL+SHIFT+B.

5. To run the solution, press CTRL+F5.