Walkthrough: Creating a Security Adapter Add-In

This walkthrough demonstrates how to create an add-in that is accessed from the Security tab of the Windows Essential Business Server Administration Console that enables a system administrator to monitor and manage security issues.

This walkthrough illustrates the following tasks:

  • Creating a security adapter class that will provide an entry in the list pane, tasks for the entry in the task pane, and security details in the details pane.
  • Deploying the security adapter add-in.

You will need the following components to complete this walkthrough:

  • Visual Studio 2005.
  • Windows Essential Business Server SDK.

Creating a Security Adapter Class

A security adapter add-in adds an entry to the list of security components on the Security tab of the Windows Essential Business Server Administration Console. The security adapter add-in also provides tasks that can be performed on the security component and provides detailed information about security issues.

Note

Unlike tasks that are listed in the task pane of a page for an application add-in, tasks listed in the task pane of the Security page must be associated to a selected security component.

To create a security adapter class

  1. Open Visual Studio.

  2. On the File menu, point to New, and then click Project.

  3. In the Project types pane, expand Visual C#, and click Windows.

  4. In the Templates pane, click Class Library.

  5. Name the project SecurityAddinExample.

  6. Click OK.

  7. In Solution Explorer, select the Class1.cs file and rename it to SecurityAdapterAddin.cs.

This walkthrough includes using an icon to represent the security component in the Windows Essential Business Server Administration Console. To include the icon in the project, you must add it as a resource.

To add resources to the project

  1. In Solution Explorer, right-click the SecurityAddinExample project and then click Add New Item.

  2. In the Templates pane, click Resources File.

  3. Name the resource file Resource.resx.

  4. Click Add.

  5. On the Resource.resx page, select Icons in the Resources list.

  6. Select Add Existing File in the Add Resource list.

  7. Locate and select the icon file that you want to use, and then click Open.

  8. Save and close the Resource.resx file.

    Note

    For more information about managing resources, see the Microsoft Web site (https://go.microsoft.com/fwlink/?LinkId=116103).

Next, create the constructor for the SecurityAdapterAddin class and override the GetStatus, CreateTasks, and GetDetails methods.

To add the constructor and override the methods

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

  2. Add the following using statement to the top of the code file:

    using Microsoft.EssentialBusinessServer.Console.ObjectModel;
    
  3. In Solution Explorer, right-click References under the SecurityAddinExample project and click Add Reference.

  4. On the .NET page, select Microsoft.EssentialBusinessServer.Console.ObjectModel, Microsoft.EssentialBusinessServer.Console.ObjectModel.Security, and System.Drawing.

  5. Click OK.

  6. Add the following code to the SecurityAdapterAddin class to define the constructor:

    public SecurityAdapterAddin()
        : base(
            "Security Adapter Add-in",                   // name displayed for the component
            "Security Adapter for the security tab",     // description of the component
            WellknownSecurityCategory.NetworkProtection, // Thread Protection Group of the component
            Resource.Network)                            // Icon that represents the component
    {
    }
    
  7. Add code to the SecurityAdapterAddin class to override the GetStatus method. The GetStatus method returns the status that is displayed for the security component in the Windows Essential Business Server Administration Console. Each security component can use this method to indicate compliance or aggregate status of all of its managed resources.

    Note

    This method can be implemented to obtain status information from another application and return a value of the SecurityStatus enumeration based on the information that was obtained.

    Add the following code to the SecurityAdapterAddin class to override the GetStatus method:

    protected override SecurityStatus GetStatus()
    {
        return SecurityStatus.Normal;
    }
    
  8. Add code to the SecurityAdapterAddin class to override the CreateTasks method. The CreateTasks method will create tasks in the task pane of the Windows Essential Business Server Administration Console that are associated to selected security components. The selection-based tasks that can be defined for a security adapter add-in are the same selection-based tasks that can be defined for an application add-in.

    Note

    All security tasks must be associated with a selected security component in the Windows Essential Business Server Administration Console. This example shows how to define a ProcessTask. You can also use a UrlTask, a SyncUiTask, and an AsyncUiTask. For more information about adding security related tasks, see SecurityTaskCollection.

    Add the following code to the SecurityAdapterAddin class to override the CreateTasks method:

    protected override SecurityTaskCollection CreateTasks()
    {
        SecurityTaskCollection taskCollection = null;
        taskCollection = new SecurityTaskCollection();
    
        SelectionTask<SecurityAdapter> task = null;
        task = new ProcessTask<SecurityAdapter>(
            "Editor", 
            @"c:\windows\notepad.exe");
        task.Description = "Edit";
    
        taskCollection.Add(task);
    
        task = new ProcessTask<SecurityAdapter>(
            "Calculations", 
            @"c:\windows\system32\calc.exe");
        task.Description = "Calculate";
    
        taskCollection.Add(task);
    
        return taskCollection;
    }
    
  9. Add code to the SecurityAdapterAddin class to override the GetDetails method. The GetDetails method is used to ensure that data sources are accessible and to obtain additional detail information about security issues from the data sources. The additional detail information is displayed in the details pane of the Security page. In this example, a Security History group is created that lists the number of Threats Detected, and a Security Configuration group is created that lists the Scan Rate.

    Add the following code to the SecurityAdapterAddin class to override the GetDetails method:

    protected override DetailColumnCollection GetDetails()
    {
        DetailColumnCollection detailCollection = null;
        detailCollection = new DetailColumnCollection();
    
        string threatCount = "3";
        DateTime timeInformation = DateTime.Now;
    
        DetailColumn column;
        DetailGroup category;
    
        column = detailCollection.Add();
        category = column.Add("Security History");
        category.Add("Threats Detected", threatCount);
        category = column.Add("Security Configuration");
        category.Add("Scan Rate", timeInformation.DayOfWeek.ToString());
    
        return detailCollection;
    }
    

    Note

    For more information about adding details, see DetailColumnCollection.

  10. On the Build menu, click Build Solution.

After you have successfully built the SecurityAdapterExample project, you can test and deploy the security adapter add-in that you created.

Deploying Your New Security Adapter Add-in

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

To create an .addin file

  1. Open Notepad.exe.

  2. Add the following text to the new file:

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

    Note

    If you accepted the default location when you created the project, the driveletter must be changed to the drive letter where your Users folder is located and username must 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 security adapter 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.

  3. (Optional) In the .addin file, you can provide the path to a file that can be used to initialize an add-in. You can use the cookie element to define an external file that contains information to initialize an instance of an 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 SecurityAdapter.

  4. Save the file as SecurityAddinExample.addin in the %systemdrive%\Windows Essential Business Server SDK\Console\Registration\Tabs\Security\Adapters directory.

    Note

    The file can be given any name, but it must have an .addin extension. 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 security adapter add-in with the SDK Add-in Development Console.

To test your new security adapter add-in

  1. Start AdminConsole.exe from the %systemdrive%\Windows Essential Business Server SDK\Console directory.

  2. Click the Security tab.

  3. Verify that the security adapter add-in is functioning correctly.

To deploy the new security adapter add-in to a server

  1. Copy the .addin file that you created in the previous procedure to the %programfiles%\Windows Essential Business Server\Bin\Registration\Tabs\Security\Adapters directory on the server. Ensure that the .addin file contains the correct location for the .dll file of the security adapter 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.

  2. (Optional) If you need to move the .dll file that contains the security adapter add-in to another location for use with your server, you must edit the .addin file and change the basedir path.

  3. (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