Windows plugins are written in C# .NET. An example plugin can be found with the Windows agent source code.
Step 1: Agent setup
Plugin support in the agent is disabled by default. To enable it, you need to do the following:
Create a plugin directory
This is a single directory anywhere on your server which will contain your plugin scripts. Make sure it has the correct permissions so it is accessible by the agent. For example, you can create the directory in C:\Users\Ryan\Documents\Plugins through Windows Explorer.
Tell the agent where the directory is
Open Server Density by locating it in your start menu. Click the Enable plugins check box and then click the Browse... button. Choose the folder that you created that contains your plugin DLLs. The agent will parse this directory for any new monitoring plugin DLLs each time the agent is started.
Step 2: Writing a plugin
Requirements
- Plugins must be written in C# (.NET Framework 3.5 and above).
- Plugins must be within their own self contained class file.
- Plugins must return a key value which is what will be displayed in the web UI
- Plugins must reference the
BoxedIce.ServerDensity.Agent.PluginSupport.dlllibrary, which can be found in the directory where Server Density was installed. - Plugins must implement the
ICheckinterface.
Class file
Your plugin class's Key property is what will show up in the web UI. For example, if you created a plugin called New Users your plugin class would have a Key whose return value must be NewUsers.
Structure
The class must have a DoCheck() method which returns a Dictionary<string, object> and a Key property that returns a string. The Key property, as mentioned above, needs to return a string. The agent will import the library and then immediately call the DoCheck() method, using the return value as part of the postback payload. You can, of course, create other classes and methods to do anything you like.
Configuration
You can access the configuration values from the agent's config file using ConfigurationManager.AppSettings if your values are within the AppSettings section in the config file. If you set up your own section then you can use ConfigurationManager.GetSection.
Return value
Each plugin will be displayed in the interface on a single graph. However, the return dictionary may contain any number of key/value pairs and these will appear as separate series on the graphs.
The name of the key will be what is displayed on the chart and can contain any character except a dot. The value is expected to be an integer or float, although it will be stored as a string and displayed to 4DP on the graphs.
For example, the following function for the plugin with the internal name Plugin1 returns two fixed value key/pairs:
using System;
using System.Collections.Generic;
using BoxedIce.ServerDensity.Agent.PluginSupport;
namespace PluginExample
{
public class Hats : ICheck
{
public string Key
{
get { return "Plugin1"; }
}
public object DoCheck()
{
IDictionary<string, object> values = new Dictionary<string, object>();
values.Add("hats", 5);
values.Add("Dinosaur Rex", 25.4);
return values;
}
}
}
.net version
You will need to build your project for .net 3.5/4.0. If you get this error:
System.BadImageFormatException: This assembly is built by a runtime newer than the currently loaded runtime and cannot be loaded.
You can add the following to your BoxedIce.ServerDensity.Agent.WindowsService.exe.config:
<supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.5" /> <supportedRuntime version="v4.0" />
Finally
Once you have written and compiled your plugin and it exists in the plugin directory, just restart the agent and it will immediately be picked up and executed.
Comments