Walkthrough: Creating an Application Add-In

Article
09/17/2008

This walkthrough demonstrates how to create an add-in that displays a page in the Business Applications tab or System Applications tab of the Windows Essential Business Server Administration Console for monitoring and managing application data.

This walkthrough illustrates the following tasks:

Creating a business object class.
Creating a list provider class that will provide business object data to the add-in.
Creating a page class that will display a list pane, a task pane, and a details pane.
Deploying the application add-in.

You will need the following components to complete this walkthrough:

Visual Studio 2005.
Windows Essential Business Server SDK.

Creating a Business Object Class

For this walkthrough, a business object is implemented as a class that provides access to property values that will be used to populate the page in the Windows Essential Business Server Administration Console.

Note

The class that is used in this walkthrough to provide business object data to the add-in is used only to demonstrate how to access business object data. In most cases, business objects will not need to be created when you create an add-in. Business object data will usually be provided using non-Microsoft SDKs that access business objects from applications that are being integrated into the Windows Essential Business Server Administration Console. Business object data can come from many sources, such as classes, databases, or services.

To create a business object class

Open Visual Studio.
On the File menu, point to New, and then click Project.
In the Project types pane, expand Visual C#, and click Windows.
In the Templates pane, click Class Library.
Name the project DemoBusinessObject.
Click OK.
In Solution Explorer, select the Class1.cs file and rename it to BusinessObject.cs.

Next, add the business object properties to the BusinessObject class. The properties will be used to populate the list in the Windows Essential Business Server Administration Console.

To add the properties to the business object class

In Solution Explorer, right-click the BusinessObject.cs file and then click View Code.
Replace the class declaration with the following code:
```
public class BusinessObject
{
}
```

Add the following code to the BusinessObject class to define properties:

private string _computerName;
public string ComputerName
{
    get { return _computerName; }
    set { _computerName = value; }
}

private string _networkName;
public string NetworkName
{
    get { return _networkName; }
    set { _networkName = value; }
}

private string _systemVersion;
public string SystemVersion
{
    get { return _systemVersion; }
    set { _systemVersion = value; }
}

private string _adminName;
public string AdminName
{
    get { return _adminName; }
    set { _adminName = value; }
}

private string _companyName;
public string CompanyName
{
    get { return _companyName; }
    set { _companyName = value; }
}

Note

The properties that are defined in the code example represent an example of a business object. You can define properties that match your business needs.

On the Build menu, click Build Solution.

The DemoBusinessObject.dll file is created in the \bin\Debug directory of your solution.
Save and close the DemoBusinessObject solution.

Now that you have created the BusinessObject class, you must create a list provider that will populate the list pane of the Windows Essential Business Server Administration Console with business object data.

Creating a List Provider Class

In this section, a user-defined class is created that inherits the ListProvider class. You initialize an instance of the class when you create content for the page that will be displayed in the Windows Essential Business Server Administration Console. A ListProvider object can obtain business object data from various sources and use the data to populate the list that is displayed in the list pane of the page.

To create a list provider class

On the File menu, point to New, and then click Project.
In the Project types pane, expand Visual C#, and click Windows.
In the Templates pane, click Class Library.
Name the project AddinExample.
Click OK.
In Solution Explorer, select the Class1.cs file and rename it to AddinListProvider.cs.

The list of business objects that is used by the Windows Essential Business Server Administration Console is initialized and managed internally, but you must add business objects to the list for the data to be available in the list pane of the page. To populate the list you must override the RefreshAndListenForUpdates method. You will also override the StopListeningForUpdates, GetObjectDisplayName, and GetObjectId methods. The following table provides more information about these methods.

Method	Description
RefreshAndListenForUpdates	Used to ensure that the data sources for business objects are accessible and to populate the provided list with information from those data sources.
StopListeningForUpdates	If your application add-in implements events that listen for updates, use this method to stop listening for updates and relinquish control of the list that is passed to RefreshAndListenForUpdates.
GetObjectDisplayName	Used to define the title of the details pane and the title of the task pane for selected business objects.
GetObjectId	Used by the Windows Essential Business Server Administration Console to uniquely identify each list item that is returned by the ListProvider object.

To initialize business object and override the ListProvider methods

In Solution Explorer, right-click the AddinListProvider.cs file and then click View Code.

Add the following using statements to the top of the code file:

using Microsoft.EssentialBusinessServer.Console.ObjectModel;
using DemoBusinessObject;

In Solution Explorer, right-click References under the AddinExample project and click Add Reference.
On the .NET page, select Microsoft.EssentialBusinessServer.Console.ObjectModel.
On the Browse page, locate the DemoBusinessObject.dll file that you created earlier in this walkthrough, and then select it.
Click OK.

Replace the class declaration with the following code:

public class AddinListProvider : ListProvider<BusinessObject>
{
}

Add the following code to the AddinListProvider class to define business objects and override the RefreshAndListenForUpdates method:

protected override void RefreshAndListenForUpdates(
    IList<BusinessObject> list)
{
    BusinessObject businessObject = new BusinessObject();

    businessObject.AdminName = "Administrator1";
    businessObject.CompanyName = "Adventure Works";
    businessObject.ComputerName = "Client1";
    businessObject.NetworkName = "Network.Local";
    businessObject.SystemVersion = "Windows Vista";

    list.Add(businessObject);

    businessObject = new BusinessObject();
    businessObject.AdminName = "Administrator2";
    businessObject.CompanyName = "Adventure Works";
    businessObject.ComputerName = "Client2";
    businessObject.NetworkName = "Network.Local";
    businessObject.SystemVersion = "Windows Vista";

    list.Add(businessObject);
}

Note

RefreshAndListenForUpdates is used to initialize the list of business objects and to refresh the list when requested by the user in the Administration Console. If your application add-in implements events that listen for updates, you would use the list that is passed to the RefreshAndListenForUpdates method to refresh the list.

Add the following code to AddinListProvider to override the StopListeningForUpdates, GetObjectDisplayName, and GetObjectId methods:

protected override void StopListeningForUpdates()
{
    // not listening for updates; nothing to do
}

protected override string GetObjectDisplayName(BusinessObject businessObject)
{
    // return a string that contains the name that will be displayed for the object
    return businessObject.ComputerName;
}

protected override string GetObjectId(BusinessObject businessObject)
{
    // return a string that uniquely identifies the business object
    return businessObject.ComputerName + "." + businessObject.NetworkName;
}

On the Build menu, click Build Solution.
Save and close the AddinListProvider class. Do not close the solution.

Now that you have created the list provider, it is time to create the page that will display your business objects in the Windows Essential Business Server Administration Console.

Creating a Page Class

In this section, a user-defined class is created that inherits the Page class. The Page class is used to create a sub-tab under the System Applications tab or the Business Applications tab in the Windows Essential Business Server Administration Console. The page object defines the panes that are visible to the administrator when using the sub-tab. The panes that are created by the page object include the list pane that lists business object data that is obtained by the ListProvider object, a details pane that displays additional information about a specific business object, and a task pane that provides actions that can be performed for all business objects or a specific business object.

To create a page class

In Solution Explorer, right-click the AddinExample project, point to Add and then click New Item.
In the Templates pane, click Class.
Name the project AddinPage.cs.
Click Add.

Next, create the constructor for the page and override the CreateContent method. The CreateContent method initializes a PageContent object that is used by the Windows Essential Business Server Administration Console to create the list pane, task pane, and details pane of the page.

To add the constructor and override the method

In Solution Explorer, right-click the AddinPage.cs file and then click View Code.

Add the following using statements to the top of the code file:

using Microsoft.EssentialBusinessServer.Console.ObjectModel;
using DemoBusinessObject;

Replace the class declaration with the following code:
```
public class AddinPage : Page
{
}
```

Add the following code to the AddinPage class to define the constructor for the page:

public AddinPage()
    : base(
        new Guid("6bee53dd-4eb8-4aeb-98a1-7af77a8bb449"),  // initialize a new instance of Guid
        "AddinExample",                                    // name that is displayed on the page tab 
        "AddinExample Description")                        // description for the add-in
{
}

Note

For more information about creating a GUID, see "Create Guid (guidgen.exe)" at the Microsoft Web site (https://go.microsoft.com/fwlink/?LinkId=116098).

Add code to the AddinPage class to override the CreateContent method. The CreateContent method uses the Create method of the PageContent class to initialize a PageContent object. The PageContent object is used by the Windows Essential Business Server Administration Console to define the columns and groups in the list pane, to define the tasks that can be performed on business objects, and to define the additional detail information that will be displayed for business objects. The Create method will be passed the ListProvider object that was created earlier in this document and will be passed objects that are returned from other methods, which will be defined later in this document.

Add the following code to the AddinPage class to override the CreateContent method:
```
protected override PageContent CreateContent()
{
    return PageContent.Create<BusinessObject>(
        new AddinListProvider(),    // initialize the list provider
        CreateColumns(),            // define the columns for the list pane
        CreateGroupings(),          // define how data will be grouped in the columns
        CreateTasks(),              // define the tasks for the task pane
        GetDetails                  // use a delegate method to get data for the details pane
    );
}
```

Now add the methods that will define the list pane, task pane, and details pane.

To add the CreateColumns, CreateGroupings, CreateTasks, and GetDetails methods

Add the CreateColumns method to the AddinPage class. This method will create columns in the list pane that will display the computer name, administrator name, and company name from the business objects. When the Add method of the ListColumnCollection class is called, the first parameter represents the header name that will be displayed for the column, and the second parameter represents the property of the business object that will be used as the display name for the object in the column. For example, a column will be added with a header of “Computer Name” and the value of the “ComputerName” property will be displayed for all business objects in that column.

Add the following code to add the CreateColumns method to the AddinPage class:
```
public static ListColumnCollection<BusinessObject> CreateColumns()
{
    ListColumnCollection<BusinessObject> columns = null;
    columns = new ListColumnCollection<BusinessObject>();

    ListColumn<BusinessObject> column = null;
    column = columns.Add("Computer Name", "ComputerName");
    column.IsRequired = true;

    column = columns.Add("Admin Name", "AdminName");
    column.IsRequired = true;

    column = columns.Add("Company Name", "CompanyName");
    column.IsRequired = true;

    return columns;
}
```
Add the CreateGroupings method to the AddinPage class. This method will group data in the list pane based on the network name of the business objects. When the Add method of the ListGroupingCollection class is called, a delegate method is used to get the business objects that are associated to the group. In this example, a group is created called “Network Name” and the GetObjectListGroup delegate method adds all business objects to the group using the “NetworkName” property. The group that is created can be used to filter the data that is displayed in the page.

Add the following code to add the CreateGroupings method to the AddinPage class:
```
public static ListGroupingCollection<BusinessObject> CreateGroupings()
{
    ListGroupingCollection<BusinessObject> groupings = null;
    groupings = new ListGroupingCollection<BusinessObject>();

    ListGrouping<BusinessObject> grouping = groupings.Add(
        "Network Name",
        GetObjectListGroup    // use a delegate method to initialize the list group
    );

    return groupings;
}

private static ListGroup<BusinessObject> GetObjectListGroup(
    BusinessObject businessObject)
{
    ListGroup<BusinessObject> group = null;
    group = new ListGroup<BusinessObject>(businessObject.NetworkName);

    return group;
}
```
Add the CreateTasks method to the AddinPage class. This method will create two tasks; one task will be associated to the item that is selected in the list pane, and the other task will not be associated to selected items.

Note

This code example only shows how to define a ProcessTask. There are several other types of tasks that can be used. For more information, see TaskCollection.

Add the following code to add the CreateTasks method to the AddinPage class:
```
public static TaskCollection CreateTasks()
{
    TaskCollection tasks = new TaskCollection();

    tasks.Add(new ProcessTask("Page Task", "notepad.exe"));
    tasks.Add(new ProcessTask<BusinessObject>("Selection Task", "notepad.exe"));

    return tasks;
}
```

Add the GetDetails delegate method to the AddinPage class. This method will provide the computer name, network name, and operating system version from the business object to the details pane. This method will also organize the detail information in a group called Computer Information.

Add the following code to add the GetDetails delegate method to the AddinPage class:

public static DetailColumnCollection GetDetails(
    BusinessObject businessObject)
{
    DetailColumnCollection columns = new DetailColumnCollection();

    DetailColumn column = new DetailColumn();
    DetailGroup group = new DetailGroup("Computer Information");
    group.Add("Computer Name", businessObject.ComputerName);
    group.Add("Network Name", businessObject.NetworkName);
    group.Add("Operating System", businessObject.SystemVersion);

    column.Add(group);
    columns.Add(column);

    return columns;
}

On the Build menu, click Build Solution.

After you have successfully built the AddinExample project, you can test and deploy the application add-in that you created.

Deploying Your New Application Add-in

The Windows Essential Business Server SDK Add-in Development Console enables you to test your application add-in before deploying it to a server. To test your application add-in, you must create and install an .addin file, which provides the location and name of your application add-in.

To create an .addin file

Open Notepad.exe.

Add the following text to the new file:

<addin name="AddinExample" type="AddinExample.AddinPage, AddinExample" basedir="driveletter\Users\username\Documents\Visual Studio 2005\Projects\AddinExample\AddinExample\bin\Debug" />

Note

If you accepted the default location when you created the project, the driveletter should be changed to the drive letter where your Users folder is located and username should be changed to the name of your user folder. If you changed the location of your project to a different location, change the basedir path to the new location.

The following table lists the attributes that are used in the .addin file to define the name and location of the application add-in.

Attribute	Description
name	Represents the name of the add-in that will appear in the Manage Add-in dialog box in the Windows Essential Business Server Administration Console.
type	The first part of the type attribute represents the fully-qualified type name of the object that defines the add-in. The second part of the type attribute represents the name of the .dll file (without the .dll extension).
basedir	Represents the path to the .dll file. The basedir attribute also defines the application domain in which the add-in will run. Any add-in that is run from the same basedir will run in the same application domain.

(Optional) In the .addin file, you can provide the path to a file that can be used to initialize an add-in. When a Page object is created, a GUID must be provided that uniquely identifies the object. You can use the cookie element to define an external file that contains a GUID, which can be used to initialize an instance of an add-in. By defining different GUIDs in other .addin files, you can initialize multiple instances of the same type of add-in. To reference a file in the .addin file, add the following element:
```
<cookie>
externalFilePath
</cookie>
```
Replace externalFilePath with the path to the file that you want to reference. For more information about how to use the specified file, see Page.
Save the file as AddinExample.addin in the %systemdrive%\Windows Essential Business Server SDK\Console\Registration\Tabs\BusinessApplications directory.

Note

The file can be given any name, but it must have a .addin extension. You can also locate the .addin file in the SystemApplications directory if you want your application add-in to be available on the System Applications tab. It is recommended when naming an add-in that you use a namespace style, such as CompanyName.ProductName.AddinName, to avoid naming conflicts with other registered add-ins.

Perform the following procedure to test your new application add-in with the SDK Add-in Development Console.

To test your new application add-in

Start AdminConsole.exe from the %systemdrive%\Windows Essential Business Server SDK\Console directory.
Click the Business Applications tab and then click the tab for the new add-in.
Verify that the application add-in is functioning correctly.

To deploy the new application add-in to a server

Copy the .addin file that you created in the previous procedure to the %programfiles%\Windows Essential Business Server\Bin\Registration\Tabs\BusinessApplications directory on the server. Ensure that the .addin file contains the correct location for the .dll file of the application add-in.

Note

If the basedir directive is not defined in the .addin file, the Administration Console will look for the .dll file in the %programfiles%\Windows Essential Business Server\Bin directory.
(Optional) If you need to move the .dll file that contains the application add-in to another location for use with your server, you must edit the .addin file and change the basedir path.
(Optional) If you are creating an Windows Installer package to install your add-in, you can access the following registry entry to locate the Bin directory of the Windows Essential Business Server operating system:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WSSG\ProductBinDir

Walkthrough: Creating an Application Add-In

Creating a Business Object Class

Creating a List Provider Class

Creating a Page Class

Deploying Your New Application Add-in

Additional resources