Quickstart: Creating a Hosted Email Adapter

  • Article

 

Applies To: Windows Server 2012 Essentials

The Windows Server Essentials Hosted Email Framework SDK contains an extended sample that describes how to create and build a hosted email add-in provider, a log monitor, additions to the Dashboard UI, as well as a custom Windows Installer package. The sample also includes a simulated email service, which the provider links to in order to demonstrate simple email features.

The sample add-in contains 6 projects in the solution:

Project Description
ContosoHostedEmailAdaptorLogMonitor Creates a real-time log monitor for the ContosoHostedEmailAddin project.
ContosoHostedEmailAddin This project consists of 2 parts:

1. ContosoHostedEmailAdaptor, which contains the implementation of IHostedEmailAdaptor;
2. SampleAddinForm, which creates a tab on the Dashboard.
ContosoHostedEmailHomepageAddin Adds a new Getting Started Task for the sample email add-in under the EMAIL section on the Home tab on Dashboard.

This project contains the ContosoHostedEmail.Home XML configuration file, which is necessary for a Home Tab task. The file is located in the sample project directory.

Note that when you fill in the id attribute of element Task, you must use the same id which you filled in in the configuration file for your hosted email add-in. For example in the sample add-in, the value for the id attribute in ContosoHostedEmail.Home is the same as the id attribute in ContosoHostedEmail.addin.
ContosoMockEmailService Contains the simulated email service running on the local server. This project allows you to simulate a hosted email service, and test the various interfaces of the hosted email framework platform.
MsiPackage Builds the WSSX package.
ContosoCustomAction Contains the custom action for the Windows Installer package. The purpose of this project is to demonstrate:

1. How to prevent uninstalling when the add-in is enabled;
2. How to remove auto generated data and configuration files after installation.

To build the sample add-in

  1. Install Visual Studio 2010 on your development machine.

  2. Download and install the Windows Server Essentials SDK package on your development machine.

  3. Download and install the Wix Toolset from Codeplex on your development machine.

    The Wix Toolset is used by the sample to create the Windows installation package.

  4. Copy the files under %ProgramFiles%\Microsoft SDKs\Windows Server 2012 Essentials\6.2\samples\HostedEmail to a separate development folder, such as (%DEV%).

    Copying the files will allow you to re-use the sample code without having to download the SDK again.

  5. Open ContosoHostedEmail.sln with Microsoft Visual Studio 2010.

  6. In the Solution Explorer, right-click the ContostHostedEmail solution, click Properties, and then click Configuration Properties.

  7. Confirm that the ContosoCustomAction field is set to the x64 platform, and then click OK.

    Although the project is written in C#, the final output which will be referenced by the WIX project is a native dll. Therefore, you should be sure the project is compiled for x64 platform.

  8. Build the solution. A package called ContosoHostedEmail.wssx will be built at %DEV%\Bin\disk1.

To run the sample add-in

  1. Set up a computer running Windows Server Essentials for testing. If you are using Windows Server 2012 Essentials, you must also install Update Rollup 1 of Windows Server 2012 Essentials on the server.

    If necessary, this may be your development machine. However, using the same machine as your development environment will limit your ability to practice deploying the package to a different machine.

  2. Disable the Strong Name on the test machine, using the following command line instructions:

    reg delete HKLM\Software\Microsoft\StrongName\Verification\*,31bf3856ad364e35 /f

    reg add HKLM\Software\Microsoft\StrongName\Verification\*,* /ve /f

    Note that you may need to manually restart the Windows Server Heath Service, if you are using it.

  3. Copy ContosoHostedEmail.wssx to any place on the server box, and double click it to install.

    1. On the User Account Control dialog, click Yes.

    2. On the Install an Add-in dialog, click Install.

  4. Open the Dashboard, expand the EMAIL tab.

    Here you will see the Contoso hosted email entry, where you can configure the hosted email service.

    1. Click Integrate with Contoso Services, and then click Click to integrate with Contoso Services.

    2. On the Integrate with Contoso page, enter a user name and password, and then click Next.

      For this sample, you may use any name and password. You do not need to use the Windows Server Essentials administrator credentials.

    3. On the Password Synchronization page, you can read about password synchronization, and choose whether to enable this feature. After you have finished reading, click Next, and then click Close.

      The hosted email adapter will then be installed on our system. The system will re-boot the Dashboard, and you can then see the new email features available.

    After the configuration you can see the integrated experience under both the Users tab and the Contoso tab.

    1. Click the Users tab. Here, you can see a new Email column, as well as the different email tasks listed in the Admin Tasks pane. These tasks are supported by the simulated Contoso email service, which is part of the sample solution.

    2. Click the Contoso tab. Here, you can see the Contoso Services and the Add-in, as well as the administrative tasks the add-in supports.