Understanding the extension format

1. Overview

This article describes the extension format used by versions 7 and higher of Dundas BI and Logi Symphony's Managed Dashboards & Reports. 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 the 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:

The following table describes the setting names and descriptions:

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>

    <!-- The names of extension purposes, separated by semicolons.
     Supported values are the ExtensionPurposes enumeration values.
     Optional - if not specified, the default value is General. -->
    <!--General-->

  </settings>
  
</ExtensionManifest>

4. The binaries

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 the software where you are installing it:

• Versions 9 and earlier installed on Windows run on the Windows-only .NET Framework and use the netfw folder.
• All other versions and installations including Docker images, installations on Linux, and later versions of the software 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 the software. For more details about .NET versions used, see the system requirements for the version of the software you're using.

5. Resources

There are two types of resources that can be defined within the extension to be referenced when loaded: 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 operating system running the application. These resources are designed to be set up automatically for all websites when installed into a load balanced application instance.

5.1. AppResources

These files will be stored in the 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 the application 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, 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 application

To install the extension ZIP file, you can use the extensions screen found under Setup in the 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 web application pool or website service, 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 application 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

• Administration overview
• Extensions
• Using the Dundas.BI.PublishExtension NuGet package
• .NET API: IAppResourceService
• .NET API: ExtensionPackageInfo2
• .NET API: Dundas.BI.Core