How to: Create a Definition XML File

Article
10/19/2016

Applies To: Windows Server 2012 Essentials, Windows Home Server 2011, Windows Storage Server 2008 R2 Essentials, Windows Small Business Server 2011 Essentials

In this section, you create an XML file that contains the elements and attributes that represent a health add-in. For more information about the elements that are used for health add-ins, see Definition XML Schema Reference.

To define the Feature element

Open Visual Studio 2010 as an administrator by right-clicking the program in the Start menu and selecting Run as administrator.
Click File, click New, and then click Project.
In the Project types pane, click Visual C#.
In the Templates pane, click HSBSHealthAddin, type MyHealthAddin in the Name text box, and then click OK.
In Solution Explorer, expand the MyHealthFeature folder, and then open the Definition.xml file.

Every add-in has one Feature element. Such as the following example:

<Feature xmlns="https://schemas.microsoft.com/WindowsServerSolutions/2010/03/Health"  
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
  xsi:schemaLocation=https://schemas.microsoft.com/WindowsServerSolutions/2010/03/Health ..\..\Engine\FeatureSchema.xsd  
  Name="HealthAddIn"   
  Title="Evaluates Health">  
</Feature>

In the Definition.xml file, change the Name attribute and the Title attribute of the Feature element to the name and title that you want to use for your health add-in. The Name attribute must be unique among all of the installed add-ins.

Save the Definition.xml file, but do not close it because you will continue to modify it in the next procedure.

A Filter element is an optional child element of the Feature element. The Filter element can be defined by a PowerShell script or a managed assembly. If you use a managed assembly, it must implement the IBinaryAction interface, which is located in the Microsoft.WindowsServerSolutions.NetworkHealth.Engine namespace. If you use a PowerShell script, the last line of the script must evaluate to a Boolean value. In the Definition.xml file, the following Filter element is defined:

<Filter>  
   <PowerShell>  
      <Script>$(get-wmiobject Win32_OperatingSystem).Version -like "6.1.*"</Script>  
   </PowerShell>  
</Filter>

-Or-

<Filter>  
   <Binary>  
      <Assembly>MyAssembly</Assembly>  
      <Class>MyNameSpace.MyFilter</Class>  
   </Binary>  
</Filter>

The following code example shows possible implementations of the IBinaryAction interface:

public class SucceedCondition : IBinaryAction<bool>  
{  
   public ActionResult<bool> Run(IActionContext context)  
   {  
      return new ActionResult<bool>(true, "This action will always return true");  
   }  
}  

public class ReturnStringAction : IBinaryAction<string>  
{  
   public ActionResult<string> Run(IActionContext context)  
   {  
      return new ActionResult<string>("Hello World", "This action always returns \"Hello World\"");  
   }  
}  

public class FalseCondition : IBinaryAction<bool>  
{  
   public ActionResult<bool> Run(IActionContext context)  
   {  
      return new ActionResult<bool>(false, "This action always returns false");  
   }  
}  

public class ThrowActionException : IBinaryAction<bool>  
{  
   public ActionResult<bool> Run(IActionContext context)  
   {  
      throw new ActionRuntimeException("Evaluation condition action that throws an error");  
   }  
}  

public class TimeoutEvaluationError : IBinaryAction<bool>  
{  
   public ActionResult<bool> Run(IActionContext context)  
   {              
      Thread.Sleep(5000);  
      return new ActionResult<bool>(true, "This action always returns true");  
   }  
}  

public class PowershellMissingError : IBinaryAction<bool>  
{  
   public ActionResult<bool> Run(IActionContext context)  
   {  
      throw new PowershellMissingException("Evaluation condition that throws a Powershell missing error");  
   }  
}

You can also define the Assembly element with the full assembly information, such as the following code example:

<Assembly>MyAssembly, Version=1.0.0.0, Culture=null, PublicKey token=null</Assembly>

Change the Script element or the Assembly and Class elements to specify the filter that you want to use for your health add-in.

Note

If you used the binary option, you must ensure that the assemblies and all dependent files are saved in %ProgramFilesWindows ServerBin, and you must ensure that the assemblies are signed with a strong name so that the add-in can be uniquely identified. Important: If the assembly is not strong named, the health check will not be evaluated. For more information about strong naming, see How to: Sign an Assembly.

Save the Definition.xml file, but do not close it because you will continue to modify it in the next procedure.

To define the HealthDefinitions element

The HealthDefinitions element can contain multiple HealthDefinition elements. In the Definition.xml file, the following HealthDefinitions element that contains a HealthDefinition element is defined.

<HealthDefinitions>  
   <HealthDefinition Name="Alert1" Title="Repairable Critical Alert 1">  
      <Condition>  
         <PowerShell>  
            <Script>$(get-service Spooler).Status –eq "Running"</Script>  
            <Detail>Verify that the Spooler service is running</Detail>  
         </PowerShell>  
      </Condition>  

      <HealthStatusChange>  
         <Status>Critical</Status>  
      </HealthStatusChange>  

      <AlertAction>  
         <PowerShell>  
            <Script>Echo “Alert is raised” > mylog.txt; $true</Script>  
            <Detail>Logs a raised alert</Detail>  
         </PowerShell>  
      </AlertAction>  

      <Troubleshoot>  
         <Steps>  
            1.Ensure that the computer is plugged in.  
            2.Turn on computer.  
            3.Restart service.  
         </Steps>  
         <FWLink>https://www.microsoft.com</FWLink>  
      </Troubleshoot>  

      <RepairAction>  
         <PowerShell>  
            <Script>net start Spooler</Script>  
            <Detail>Restart Spooler service</Detail>  
         </PowerShell>  
      </RepairAction>  
   </HealthDefinition>  
</HealthDefinitions>

In the Definition.xml file, change the Name attribute and the Title attribute of the HealthDefinition element to the name and title that you want to use for the health definition. The Name attribute must be unique among HealthDefinition elements in the Feature element.

You can define an action to be performed to obtain system information. Under the Condition element, change the Script element and the Detail element of the PowerShell element to specify a script that is run to obtain a system condition. You can also use a Binary element to specify that a managed assembly is used to obtain system information. The following example shows how to use the Binary element:
```
<Binary>  
   <Assembly>MyAssembly</Assembly>  
   <Class>MyNameSpace.MyCondition</Class>  
</Binary>  
```
You can define the health state of the system by using the HealthStatusChange element. Change the Status element to the status value that you want for the health add-in. The value can be: OK, Information, Warning, Critical.
You use the AlertAction element to specify the action that is performed when an alert is raised. Change the Script element and the Detail element of the PowerShell element to specify a script that is run when the alert is raised. You can also use a Binary element to define an alert action.
You can use the optional Troubleshoot element to provide instructions for manually repairing a problem. Change the text in the Steps element to define the troubleshooting steps for your health add-in. You can also provide a URL in the FWLink element to specify a Web page for providing help.
You use the RepairAction element to define the script of binary file to be run to repair a problem on the system. Change the Script element and the Detail element of the PowerShell element to specify a script that is run to repair a problem. You can also use a Binary element to define a repair action.
Save the Definition.xml file.

How to: Create a Definition XML File

To define the Feature element

To define the Filter element

To define the HealthDefinitions element

Additional resources