Hook into server events

Contents[Hide]

1. Overview

This sample shows how to hook into the application's server events from your extension. The extension created in the sample subscribes to the CreatedFileSystemEntry event, and then resets the data result cache.

2. Getting started

The current version of the sample solution targets both .NET Framework and .NET Core so that the packaged extension will work for version 7 of the application and higher on all platforms.

The following prerequisites must be installed on your computer to build the provided sample without modifications:

Visual Studio 2017 or higher
Microsoft .NET Framework 4.7.2
Microsoft .NET Core 3.1

You can modify the sample project to target different versions of .NET if preferred depending on the version used by your application instance.

The NuGet packages referenced as dependencies are initially set to version 7. If your version of the software is newer and the APIs you are using may have changed, you can update the version of this package reference.

2.1. Downloading sample solution

To download the server events sample solution, click here.

(A sample solution is also available for version 6.0, versions 5.0 and older.)

2.2. Opening solution

Extract ServerEventsSample.zip to a folder and open the solution in Microsoft Visual Studio to build the extension.

To use the option to publish directly to your application instance, run Visual Studio as an administrator before opening the solution. For example, you can right-click Visual Studio in the start menu and find the Run as administrator option.

The solution file is located at:
[Extracted folder]\ServerEventsSample\ServerEventsSample.sln

3. The project

The project is a class library.

ServerEventsExtensionPackageInfo.cs - This class contains the package information about the extension package. The server events are hooked up by overloading the OnLoaded method.
PublishExtensionTemplate.props - Used for auto publishing the extension after the build succeeds, and defines extension properties, and files.

3.1. ExtensionPackageInfo class

To register as an extension, extend the ExtensionPackageInfo2 class. This class contains the extension package information.

/// <summary>
/// This class represents the extension package info for the Server Events. 
/// </summary>
public class ServerEventsExtensionPackageInfo : ExtensionPackageInfo2
{
    ...
}

To hook into events, override the OnLoaded method. Next, get the IEventHookService and subscribe to one of the events.

In the example below, the event hook service is used to hook up to the CreateFileEntry event. This event is then used to clear the result cache.

/// <summary>
/// Called after the extension package is loaded during engine startup.
/// </summary>
public override void OnLoaded()
{
    IEventHookService eventHookService = Engine.Current.GetService<IEventHookService>();

    // Hooks up event handler when a file system entry is created.
    eventHookService.CreatedFileSystemEntry += eventHookService_CreatedFileSystemEntry;
}

/// <summary>
/// Handles the CreatedFileSystemEntry event of the eventHookService control.
/// </summary>
/// <param name="sender">The source of the event.</param>
/// <param name="e">The <see cref="ItemChangedEventArgs{Dundas.BI.FileSystem.FileSystemEntry}"/> 
/// instance containing the event data.</param>
void eventHookService_CreatedFileSystemEntry(
    object sender, ItemChangedEventArgs<Dundas.BI.FileSystem.FileSystemEntry> e
)
{
    IDataRetrievalService dataRetrievalService = Engine.Current.GetService<IDataRetrievalService>();

    dataRetrievalService.ClearResultCache();
}

3.2. Publish extension template

This sample has a mechanism to automatically publish the extension when building, which is the Dundas.BI.PublishExtension NuGet package. When this package is added to the project, it creates a PublishExtensionTemplate.props file containing MSBuild property and item groups, which define how to create and publish the extension.

When the DtFilePath property is set to the file path of the dt tool of an application instance, it will then publish the extension directly to that instance when you build the solution. It will also touch the web.config file to force the web application to reset.

If the DtFilePath property is not set, it will create a .zip file you can add to your application instance using the Extensions screen in the administration UI. After building the solution with default settings and the solution configuration set to Release, this .zip file can be found in the bin\Release\netcoreapp3.1 subfolder of your solution. It targets both .NET Framework and .NET Core.

For more details on using this package to automate publishing extensions, see Using the Dundas.BI.PublishExtension NuGet package.

Dundas BI, Managed Dashboards & Reports Support