Understanding the Dundas BI extension format

Contents[Hide]

1. Overview

This article describes the Dundas BI extension format used by versions 7 and higher. Extensions are made up of the file and folder structure described below contained within a ZIP file.

This extension ZIP file can be automatically prepared for you by Visual Studio when you build your project using the Dundas.BI.PublishExtension NuGet package as demonstrated by our provided extension samples. Once you have your extension ZIP file, it can be installed using Dundas BI's administration interface or using other methods if preferred.

2. The extension root folder

The extension root folder is the first folder inside your extension. All other parts of the extension go inside this folder:

\YourExtensionRootFolder

3. The extension manifest file

Each extension contains a manifest file at the root of the extension folder, which is an XML file. The extension manifest describes different extension properties and settings.

With our example root folder above, the extension manifest would be located at:

\YourExtensionRootFolder\ExtensionManifest.xml

The following table describes the property names and descriptions:

Property nameDescription
id An arbitrary GUID which uniquely identifies the extension.
name The name of the extension.
displayName The display name of the extension.
author The author of the extension.
copyright The copyright text for the extension.
version The version of the extension.

The following table describes the setting names and descriptions:

Setting nameDescription
MainAssemblyName The name of the main assembly containing the ExtensionPackageInfo implementation.
ExtensionFolderName The name of the root extension folder.
SupportedRuntimes The names of supported runtimes separated by semicolons. Supported values are NetFramework, NetCore, NetCoreWindows and NetCoreLinux. These should correspond to the binaries as described in the following section.
EnumeratingTypesErrorExemptAssemblies The names of referenced assemblies separated by semicolons that should be exempt from logging Error enumerating types from assembly... in the application if they are unable to be loaded.

3.1. Manifest example

The following is an example of an extension manifest:

<?xml version="1.0" encoding="utf-8" ?>
<ExtensionManifest 
  xmlns="http://dundas.com/schemas/BI/ExtensionManifest.xsd"
  id="c1fdbe6b-bc39-4e95-eee4-2ee77eeeeeee" 
  name="Sample"
  displayName="Sample"
  author="Author"
  copyright="Copyright (c)"
  version="1.0.0.0">

  <settings>
    <!-- The name of the main assembly. -->
    <setting name="MainAssemblyName">Sample.dll</setting> 

    <!-- The name of the root extension folder. -->
    <setting name="ExtensionFolderName">Sample</setting>

    <!-- The names of supported runtimes, separated by semicolons. 
     Supported values are NetFramework, NetCore, NetCoreWindows and 
     NetCoreLinux. -->
    <setting name="SupportedRuntimes">NetFramework;NetCore</setting>

  </settings>
  
</ExtensionManifest>

4. The binaries

Dundas BI extension assembly files are .NET Framework or .NET Core assemblies. Each assembly has a class that inherits from ExtensionPackageInfo2 in the Dundas.BI.Core assembly.

All compiled extensions and their referenced assemblies are placed within the bin folder in the root of the extension folder. The assemblies then go in netfw and/or netcore subfolders. If you are multi-targeting your extension for both .NET Framework and .NET Core, you can put your assemblies in both the netfw and netcore subfolders:

\YourExtensionRootFolder\bin\netfw\MyExtension.dll
\YourExtensionRootFolder\bin\netcore\MyExtension.dll

Your extension needs to include an assembly compatible with the version of Dundas BI where you are installing it. Dundas BI versions 9 and earlier installed on Windows run on the Windows-only .NET Framework and use the netfw folder, while all other versions and installations including Docker images, installations on Linux, and later versions of Dundas BI run on .NET Core, now also known as simply .NET, and use the netcore folder. You can target an earlier version of .NET Framework or .NET Core than the version used by Dundas BI. For more details about .NET versions used, see Dundas BI - System Requirements for your version of Dundas BI.

5. Resources

There are two types of resources that can be defined within the extension to be referenced when loaded in Dundas BI: application resources, and file resources.

Application resources are stored in the application database, and file resources are stored on the file system of the server running Dundas BI. These resources are designed to be set up automatically for all websites when installed into a load balanced Dundas BI instance.

Tip
Besides these two types of resources stored within the extension ZIP file, you can set the Build Action to Embedded Resource on a file in your extension's project to embed it within the .NET assembly. The custom control extension sample returns embedded JavaScript and CSS files in its AdapterInfo implementation.

5.1. AppResources

These files will be stored in the Dundas BI application database and maintained (added, updated, removed) when your extension is added, updated or deleted. From within the extension these resources can reached by using the IAppResourceService.

\YourExtensionRootFolder\AppResources\SomeFile1.txt

This type of resource can also be retrieved using ResourceService (JavaScript), or various Resource requests available in the REST API.

5.2. FileResources

These files will be stored in the file system of your app and maintained (added, updated, removed) by the app, when your extension is added, updated or deleted.

\YourExtensionRootFolder\FileResources\SomeFile2.txt

After installation this will be available at:

[InstallDir]\www\BIWebsite\wwwroot\ExtensionResources\[YourExtensionRootFolder]\SomeFile2.txt

File resources can also be accessed by URL as in the following C# example referring to an image file:

return new Uri("ExtensionResources/ExtensionName/SomeImage.png", UriKind.Relative);

6. Localizations

If you have localization files to include with your extension, they should be placed in the Localizations subfolder.

\YourExtensionRootFolder\Localizations\SomeLocalizationFile.xml

This localization file will be loaded into Dundas BI and its strings will be available to you, for example by using Engine.Current.Localize or by calling localize on a localization key string in JavaScript: "GS_StringKey".localize().

7. Zipping and installing the extension

To install the extension in Dundas BI, its files and folders need to be contained within a ZIP file. This can be packaged for you automatically when your project is built when using the PublishExtension NuGet package.

The root folder referred to above should be the first folder inside the zip file:

YourExtension.zip\YourExtensionRootFolder

7.1. Installing through the Dundas BI application

To install the extension ZIP file, you can use the extensions screen found under Setup in the Dundas BI administration interface.

7.2. Installing using the dt command-line tool

To install using the dt tool, pass the following arguments:

dt manageExtensions Store /id:"{ExtensionId}" /filePath:"C:\temp\YourExtension.zip"

After restarting your Dundas BI web application pool, the extension gets loaded and any file resources get copied to:

[InstallDir]\www\BIWebsite\wwwroot\Extensions\[YourExtensionRootFolder]

7.3. Installing from Visual Studio

You can optionally publish the extension directly to your Dundas BI instance automatically when the project builds. When using the Dundas.BI.PublishExtension NuGet package and providing a path to the dt command line tool, it installs the extension using the same process shown above.

The provided sample extension projects include this package, and articles for each type of extension provide information in their publish extension template section. For more details, see Using the Dundas.BI.PublishExtension NuGet package.

8. See also

Dundas Data Visualization, Inc.
400-15 Gervais Drive
Toronto, ON, Canada
M3C 1Y8

North America: 1.800.463.1492
International: 1.416.467.5100

Dundas Support Hours:
Phone: 9am-6pm, ET, Mon-Fri
Email: 7am-6pm, ET, Mon-Fri