How to: Extend an Existing Dialog or Wizard

Applies To: Windows Server 2012 Essentials

To extend an existing wizard or dialog, you must create an adorner that inherits from FormExtensionAdorner and IHostedEmailExtension. Once you have created the adorner, you can link it to a specific UI element though the .addin file. For more information, see How to: Install the UI Update.

Currently, the only UI element that supports this type of extension is the User Properties dialog. You can add in a new tab to the dialog, or you can extend the Advanced button on the Email tab. For an example of each, see Quickstart: Creating a Hosted Email Adapter. For more information on which built-in UI elements can be extended using the Hosted Email Integration Framework, see Extending and Replacing the Email UI.

To extend an existing dialog or wizard

1. Create a class that inherits from FormExtensionAdorner and IHostedEmailExtension.

   FormExtensionAdorner allows you to hook into an existing UI dialog or wizard, while IHostedEmailExtension allows you to associate your UI extension with your add-in.

   public class AdvancedPage : FormExtensionAdorner, IHostedEmailExtension  
       {  
       }  
   

2. Implement the constructor, using the GUID, display name, and description of the new UI element.

   public AdvancedPage
   ()  
               : base(UIConstants.ContosoServicesSubTab,  
                      Resources.ContosoServicesSubTab_DisplayName,  
                      Resources.ContosoServicesSubTab_Description)  
   

3. Override the CreateForm method, using your new page or dialog object.

   In this example, UserPropertyAdvancedForm is a Windows Form control. Note the use of the form property bag to pass in data from the original built-in email control.

   public override Form CreateForm(FormPropertyBag bag)  
   {  
       UserPropertyAdvancedForm ret = new UserPropertyAdvancedForm(null == bag ? string.Empty : bag.UserName);  
       if ((null == bag) || string.IsNullOrEmpty(bag.UserName) || !ret.loadUserData())  
       {  
           MessageBox.Show(Resources.ContosoServicesSubTab_ErrorDescription);  
           return null;  
       }  
       else  
       {  
           return ret;  
       }  
   }  
   

4. Implement GetAddinId.

   This method is called by the form to identify which add-in your UI is associated with. The actual add-in ID is the GUID used to uniquely identify the add-in, and is stored in the XML Configuration file. For more information, see the ID attribute of the Addin Element, as well as How to: Create a Configuration XML File. In the sample below, the adapter ID is stored as a constant, as it is used in several locations in the sample.

   public Guid GetAddinId()  
   {  
       return Constants.AdaptorId;  
   }