Using the Dundas.BI.PublishExtension NuGet package

Contents[Hide]

1. Overview

This article describes how to use the Dundas.BI.PublishExtension NuGet package. This package allows for simple packaging of Dundas BI extensions into the Dundas BI extension format.

Note
This article assumes that your Visual Studio project uses the 2017 project format or higher.

2. Walkthrough

2.1. Adding the Dundas.BI.PublishExtension NuGet package to your project

To add the any NuGet package to your project follow the instructions here: Quickstart: Install and use a package in Visual Studio (Windows only). The Dundas.BI.PublishExtension NuGet package is called Dundas.BI.PublishExtension and publicly available in the NuGet Gallery.

2.2. PublishExtentionTemplate.props

After the Dundas.BI.PublishExtension NuGet package is added to your Visual Studio project a PublishExtentionTemplate.props file will automatically be added to the root of your project. This file defines a target that allows for defining extension package information through MSBuild properties and items. The following is an example of the default PublishExtentionTemplate.props file:

<Project>
  
  <Target Name="DefineDundasBIExtensionProperties" AfterTargets="CopyFilesToOutputDirectory">
    <!-- Properties used to publish extension -->
    <PropertyGroup>

      <!-- Extension Author -->
      <ExtensionAuthor></ExtensionAuthor>
      <!-- Extension Name -->
      <ExtensionName>$(AssemblyName)</ExtensionName>
      <!-- Extension Display Name -->
      <ExtensionDisplayName>$(AssemblyName)</ExtensionDisplayName>
      <!-- Extension Folder Name -->
      <ExtensionFolderName>$(AssemblyName)</ExtensionFolderName>
      <!-- Extension Main Assembly Name -->
      <ExtensionMainAssemblyName>$(AssemblyName).dll</ExtensionMainAssemblyName>
      <!-- Extension Id -->
      <ExtensionId></ExtensionId>
      <!-- Extension Copyright -->
      <ExtensionCopyright>Copyright (c)</ExtensionCopyright>
      <!-- Extension Version -->
      <ExtensionVersion>1.0.0.0</ExtensionVersion>
      <!-- The outfolder where the extension zip file will be left. -->
      <ExtensionOutputFolder>$(OutputPath)</ExtensionOutputFolder>
      <!-- DT -->
      <!-- If this is specified the extension will be installed using dt.  -->
      <DtFilePath></DtFilePath>

      <!-- Framework Folder -->
      <FrameworkFolderRelative>$(OutputPath)\..</FrameworkFolderRelative>
      <FrameworkFolder>$([System.IO.Path]::GetFullPath($(FrameworkFolderRelative)))</FrameworkFolder>
      
    </PropertyGroup>

    <!-- Define files to include -->
    <ItemGroup>
      <!-- Define the NetFramework assemblies -->
      <NetfwAssemblies Include="$(FrameworkFolder)\net*\$(AssemblyName).*"   />
      <!-- Define the NetCore assemblies -->
      <NetCoreAssemblies Include="$(FrameworkFolder)\netcoreapp*\$(AssemblyName).*"  />
      <!-- Define any app resources for the extension. -->
      <AppResources />
      <!-- Define any file resources for the extension. -->
      <FileResources />
      <!-- Define any localization files for extension. -->
      <Localizations />
      <!-- Define Extension Supported Runtimes -->
      <ExtensionSupportedRuntimes Include="NetFramework" />
      <ExtensionSupportedRuntimes Include="NetCore" />
    </ItemGroup>
  </Target>
</Project>

2.3. Including application resources

An application resource is a file that is included with an extension package that is stored in the application database. The following example would include SomeFile.txt in the root of the MSBuild project as an application resource:

<ItemGroup>
   <FileResources Include="$(MSBuildThisFileDirectory)\SomeFile.txt" />
</ItemGroup>

This type of resource can be later retrieved by calling the API and using the IAppResourceService (.NET), ResourceService (JavaScript), or various Resource requests available in the REST API.

2.4. Including file resources

A file resource is a file that is included with an extension package that is stored in the file system of the Dundas BI web application. The following will add SomeImage.png from the root of the project to the extension as a file resource.

<ItemGroup>
   <FileResources Include="$(MSBuildThisFileDirectory)\SomeImage.png" />
</ItemGroup>

This file will later be available at the following URL on all Dundas BI websites:

public override Uri ToolbarIconUri
{
    get
    {
        return new Uri(
            "ExtensionResources/ExtensionName/SomeImage.png",
            UriKind.Relative
        );
    }
}

For more information, and a working example of this see Create a custom transform.

2.5. Include localization files

The following will add the SomeLocalizationFile.xml localization file on the root of the project to the extension:

<ItemGroup>
   <Localizations Include="$(MSBuildThisFileDirectory)\SomeLocalizationFile.xml" />
</ItemGroup>

This localization file will be loaded, and the localized strings inside will be available to the extension.

2.6. Defining the extension assemblies

2.6.1. Including the files in the bin folder

The following example will pick up both the .NET Framework, and .NET Core assemblies in the bin folder to be included the extension zip fie:

    <!-- Define files to include -->
    <ItemGroup>
      <!-- Define the NetFramework assemblies -->
      <NetfwAssemblies Include="$(FrameworkFolder)\net*\$(AssemblyName).*"   />
      <!-- Define the NetCore assemblies -->
      <NetCoreAssemblies Include="$(FrameworkFolder)\netcoreapp*\$(AssemblyName).*"  />
    </ItemGroup>

If other assemblies are required by the extension they should also be included here.

2.6.2. Targeting extensions

For each run time the extension supports the PublishExtensionTemplate.props file should include them:

      <!-- Define Extension Supported Runtimes -->
      <ExtensionSupportedRuntimes Include="NetFramework" />
      <ExtensionSupportedRuntimes Include="NetCore" />

2.7. After build

After the project is built successfully, the extension zip is available in the bin folder by default. This folder can be changed by modifying the ExtensionOutputFolder in the PublishExtensionTemplate.props file.

If your project defines multiple target frameworks to build, it will only build the extension zip when the last one is being processed. For example, if the target frameworks were defined like the following: <TargetFrameworks>net472;netcoreapp3.1</TargetFrameworks>, you would then expect the extension zip to be run as part of the netcoreapp3.1 build process. This was done to ensure multi-targeted extensions will have all assemblies built.

2.8. See also

Dundas Data Visualization, Inc.
500-250 Ferrand Drive
Toronto, ON, Canada
M3C 3G8

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