[This post comes to us courtesy of Rui Ling and Yang Cao from Sustained Engineering]
The Windows Server Essentials Dashboard nowadays supports many UI extensions. In Update Rollup 1 for Windows Server 2012 Essentials, Essentials provides an important update for the Hosted Email Add-In Framework, which is used not only for email integration, but also for extending the user management UI in the Dashboard. Value-added solution providers or system integrators can leverage the add-in framework to build Dashboard extensions as part of their total solutions.
By following the steps in this post, you can add a new tab on the Windows Server 2012 Essentials Dashboard. On this tab, you can display information about your own value-add services (such as email, backup, or monitoring). You can also add a new page into the Add a User Wizard so that you can integrate your service configuration with the new user creation flow.
This article is inspired by our partner Cbeyond® (http://cbeyond.com/). From Microsoft PinPoint, you can find other add-ins developed by our partner. It is highly recommended that you take some time to go through Dashboard features or install some add-ins before completing the following steps. You can also review the Hosted Email Add-in Framework as a reference for the UI add-in development.
- Set up the environment: Install Visual Studio on your development system.
- Create add-ins: We will create a sample project first and then introduce how to create the following two types of UI add-ins:
- A new tab on the Dashboard
- A page to add to the wizards of the user management UI on the Dashboard
1.1 Open Visual Studio and create a Class Library project targeting at least .NET Framework 4.0
This article will use the Visual Studio Class Library project as an example to show every part of a UI add-in. Another option is to download the Windows Server 2012 Essentials SDK and create the project against the Essentials template.
Add all the references assemblies you need to the project. Normally for a UI add-in, you need to add the following assemblies:
- AdminCommon
- Microsoft.windowsserversolutions.administration.objectmodel
You can find these assemblies in the install path (%ProgramFiles%\Windows Server\Bin) or GAC from your server running Windows Server 2012 Essentials (or Windows Server 2012 R2 Essentials). You can copy all the binaries you need from the server to your DEV box to compile the project. It is also recommended that you compile the project directly on your server.
Note: Visual Studio will automatically create a Class1.cs in the project. Because we won’t use it for this example, you can remove this class.
2.1 Create a new tab on the Dashboard
Please follow these steps to add a top-level tab to the Dashboard.
2.1.1 Create a user control, MyTabUserControl, and add a label with some text “label in MyTab”
2.1.2 Create the Adorner class MyTabAdorner, and make sure that it inherits from Microsoft.WindowsServerSolution.Administration.ObjectModel.Page
a. In the constructor of this class, you must pass a unique GUID, display name, and description to the base class.
b. You must override the function CreateContent and return your own user control MyTabUserControl.
c. When creating the PageContent, you may create a TaskCollection and implement some global tasks if needed. We will create one task named “MyTask” and will pop up a message box.
d. You can also override other functions to show more information on the tab. For more details, see the SDK doc.
using Microsoft.WindowsServerSolutions.Administration.ObjectModel;namespace SampleClassLibrary.Tab{publicclass MyTabAdorner : Page{public MyTabAdorner(): base(new Guid("{B8813153-4DC6-429C-A912-6362E6D9A10F}"),"DisplayName for MyTab","Description for MyTab"){}protectedoverride PageContent CreateContent(){TaskCollection tasks = new TaskCollection();tasks.Add(new SyncUiTask("MyTask",new SyncAction(() =>{System.Windows.Forms.MessageBox.Show("Test Task");returnnull;}), false));return PageContent.Create((obj, component) => new MyTabUserControl(), tasks, null);}}}
2.1.3 Create the provider class MyTabProvider, and make sure that it inherits from Microsoft.WindowsServerSolution.Administration.ObjectModel.PageProvider
a. In the constructor of this class, you must pass a unique GUID, display name, and description to the base class.
b. You also need to override the function CreatePages and return your own adorner page MyTabAdorner.
c. You can also override other functions to show more information on the tab. For more details, see the SDK doc.
using Microsoft.WindowsServerSolutions.Administration.ObjectModel;namespace SampleClassLibrary.Tab{publicclass MyTabProvider : PageProvider{public MyTabProvider(): base(new Guid("{8A0338F4-C88D-4EF3-8A3E-3BBB0922B575}"),"DisplayName for MyTabProvider","Description for MyTabProvider"){}protectedoverrideobject CreatePages(){return (newobject[] { new MyTabAdorner() });}}}
2.1.4 Create an add-in configure file called MyTabConf.addin
a. Set the property “Copy to Output Directory” to “Copy always” because we want to deploy this file to the Windows Server Essentials server.
b. The basedir should be the path where you deploy your add-in assembly to the Essentials server.
c. The type should be the full type string of your provider class and should be case-sensitive.
<addin name="MyTab Addin" basedir="E:\Sample"type="SampleClassLibrary.Tab.MyTabProvider, SampleClassLibrary" />
After completing these steps, your SampleClassLibrary will look like this screenshot.
Now you can build your project and deploy the add-in to the Essentials server (see the deploy section). In this section, we want to add a top-level tab to the Dashboard, so we deploy the add-in file to “%ProgramFiles%\Windows Server\Bin\Addins\Primary\MyTabConf.addin”.
After launching/restarting your Dashboard, you will see this screenshot.
2.2 Insert a new page to the Dashboard User Management wizards and retrieve data from PropertyBag
2.2.1 Create a user control, MyPageUserControl, and add a button with some text “button in MyPage”
a. Double-click the button in the VS designer; VS will automatically generate the button click handler. Add some code to this handler:
if (null == FormPropertyBag)
{ MessageBox.Show("You need to set the FormPropertyBag");}
else {MessageBox.Show(string.Format("Get Data from FormPropertyBag:\r\n UserName : {0},\r\n FirstName : {1},\r\n LastName : {2},\r\n Password : {3}",
FormPropertyBag.UserName,
FormPropertyBag.FirstName,
FormPropertyBag.LastName,
FormPropertyBag.Password));
}
b. Add the namespace
using Microsoft.WindowsServerSolutions.Administration.ObjectModel.Adorners;
and one property to MyPageUserControl.cs:
publicFormPropertyBag FormPropertyBag { get; set; }
2.2.2 Create the provider class MyPageContent, and make sure that it inherits from Microsoft.WindowsServerSolution.Administration.ObjectModel.Adorner.AddinPageContent
a. In the constructor of this class, you need to add Microsoft.WindowsServerSolution.Administration.ObjectModel.Adorner.FormPropertyBag as the parameter and pass it to its base class.
b. You need to override the function CreateControl and return your own control MyPageUserControl.
c. You also need to override the event handler PropertyChanged.
d. You can override other functions or events to customize the behavior of this class. For more details, see the SDK doc.using Microsoft.WindowsServerSolutions.Administration.ObjectModel.Adorners;namespace SampleClassLibrary.Wizard{publicclass MyPageContent : AddinPageContent{public MyPageContent(FormPropertyBag bag): base(bag){}publicoverride Control CreateControl(){returnnew MyPageUserControl() { FormPropertyBag = this.PropertyBag };}publicoverrideevent EventHandler PropertyChanged;}}
2.2.3 Create the Adorner class MyPageAdorner, and make sure that it inherits from Microsoft.WindowsServerSolutions.Administration.ObjectModel.Adorners.FormContentAdorner
a. In the constructor of this class, you need to pass a unique GUID, display name, and description to the base class.
b. You need to override the function CreatePages and return MyPageContent created in the last step.
c. You can also override other functions to show more information on the tab. For more details, see the SDK doc.
using Microsoft.WindowsServerSolutions.Administration.ObjectModel.Adorners;namespace SampleClassLibrary.Wizard{publicclass MyPageAdorner : FormContentAdorner{public MyPageAdorner(): base(new Guid("E2B29E47-CD46-4B11-8AB1-B1384E917A0C"),"DisplayName for MyPage","Description for MyPage"){}publicoverride ICollection<AddinPageContent> CreatePages(FormPropertyBag propertyBag){List<AddinPageContent> list = new List<AddinPageContent>();list.Add(new MyPageContent(propertyBag) {Title = "Test Title for MyPage",HelpLink = new Uri("http://www.contoso.com"),HelpLinkText = "Test Help Link for MyPage",});return list;}publicoverride ICollection<System.Threading.Tasks.Task> CreatePostExecutionTasks(FormPropertyBag propertyBag){List<System.Threading.Tasks.Task> list = new List<System.Threading.Tasks.Task>();list.Add(new System.Threading.Tasks.Task(()=>{// do something in the task}));return list;}publicoverride ICollection<System.Threading.Tasks.Task> CreatePreExecutionTasks(FormPropertyBag propertyBag){List<System.Threading.Tasks.Task> list = new List<System.Threading.Tasks.Task>();list.Add(new System.Threading.Tasks.Task(()=>{// do something in the task}));return list;}}}
2.2.4 Create an add-in configure file MyPageConf.addin
a. Set the property “Copy to Output Directory” to “Copy always” because we want to deploy this file to the Windows Server Essentials server.
b. The basedir should be the path where you deploy your add-in assembly to the Essentials server.
c. The type should be the full type string of your provider class and should be case-sensitive.
<addin name="MyPage Addin" basedir="E:\Sample"type="SampleClassLibrary.Wizard.MyPageAdorner, SampleClassLibrary" />
After these four steps, your SampleClassLibrary will look like this screenshot.
Now you can build your project and deploy your add-in to the Essentials server (see the deploy section). In this section, we want to insert the page to the Add-User Wizard, so we deploy the add-in file to “%ProgramFiles%\Windows Server\Bin\Addins\Users\AddUserWizard\MyPageConf.addin.”
After launching/restarting your Dashboard, you can run the “add a user” task and go through the wizard flow. On the last configure page, you will see the add-in page.
3.1 Deployment
After building your project in Visual Studio, you will get the binaries and several add-in configure files.
a. Confirm that your target installation includes Update Rollup 1 so that the Hosted Email Add-In Framework is present.
b. Deploy your *.dll to the Essentials server (for example, E:\Sample).
c. Make sure that the path you deploy to the add-in binaries is the same as the basedir in the add-in configure files.
d. Deploy your *.addin to the correct add-in folder.
Reference MSDN article: How to: Install a Top-Level Tab
Reference MSDN article: How to: Install the UI Update