Create custom application configuration settings

1. Overview

This sample shows how to create custom application configuration settings.

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 Dundas BI version 7 or 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 Dundas BI instance.

The Dundas BI NuGet packages referenced as dependencies are initially set to version 7.0.1. If your version of Dundas BI is newer and the APIs you are using may have changed, you can update the version of these package references.

2.1. Downloading sample project

To download the custom application configuration sample project, click here.

An older version 6 sample is also available.

2.2. Opening project

Extract AppConfigSample.zip to a folder and open the project in Microsoft Visual Studio to build the extension.

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

The project file is located at:
[Extracted folder]\AppConfigSample\AppConfigSample.csproj

3. The project

The project is a class library.

• AppConfigSamplePackageInfo.cs - This class contains the package information about the extension package, and the methods for registering the new application setting.
• PublishExtensionTemplate.props - Used for auto publishing the extension after the build succeeds, and defines extension properties, and files.

3.1. ExtensionPackageInfo class

In order for the extension to be read by Dundas BI, it needs to contain a class that extends the ExtensionPackageInfo2 class. This class contains a call to the base constructor that reads extension package information from the extension manifest file, which is packaged with your extension by the publishing mechanism included with this sample project.

   
namespace MyCompany.Sample.AppConfigSample
{
	/// <summary>
	/// This class contains the package information about the extension package.
	/// </summary>
	public class AppConfigSamplePackageInfo : ExtensionPackageInfo2
	{
		/// <summary>Initializes a new instance of the 
		/// <see cref="AppConfigSamplePackageInfo"/> class.</summary>
		/// <param name="extensionManifest">The extension manifest.</param>
		public AppConfigSamplePackageInfo(ExtensionManifest extensionManifest)
			: base(extensionManifest)
		{
		}

In order to add an application setting to Dundas BI overload the OnLoaded method of the ExtensionPackageInfo2 class. Next, get the application configuration service (IAppConfigService) from the engine. Finally, create an ApplicationSettingProperties object and then use the Application Configuration Service to register the setting.

In the sample below a hello world application setting is added to Dundas BI:

   
private void RegisterSettings()
{
	IAppConfigService appConfigService = Engine.Current.GetService<IAppConfigService>();

	AppSettingProperties appSettingsProperties = new AppSettingProperties(
		AppConfigSamplePackageInfo.HelloWorldPropertyId,
		"HelloWorldProperty",
		this.Id,
		typeof(string)
	);
	appSettingsProperties.CategoryName = "Hello World Category";
	appSettingsProperties.Description = "Hello World Property";

	appSettingsProperties.DefaultValue = string.Empty;
	appConfigService.RegisterSetting(appSettingsProperties);
}

/// <summary>
/// Called after the extension package is loaded during engine startup.
/// </summary>
public override void OnLoaded()
{
	RegisterSettings();
}

3.2. Validating an application setting

Each application setting can be validated by setting the ValidationRule property. This property takes AppSettingValidationRule. In the sample below a StringValidationRule is used to ensure that the property is set with hello followed by a space and then some text.

   
int maxLength = 1000;
bool isEmptyStringValid = true;
Regex regularExpressionToMatch = new Regex("Hello[\\s](.*?)", RegexOptions.IgnoreCase);

AppSettingValidationRule appSettingValidationRule =
    new StringValidationRule(maxLength, regularExpressionToMatch, isEmptyStringValid);

appSettingsProperties.ValidationRule = appSettingValidationRule;

3.3. 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 a Dundas BI 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 Dundas BI 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.

<Project>
  <Target Name="DefineDundasBIExtensionProperties" AfterTargets="CopyFilesToOutputDirectory">

    <!-- Properties used to publish extension -->
    <PropertyGroup>

      <!-- Extension Author -->
      <ExtensionAuthor>MyCompany Sample Author</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>c1fdbe6b-bc39-4e95-bbf4-2fa77edaeabe</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 -->
      <DtFilePath></DtFilePath>
      <!-- Framework Folder -->
      <FrameworkFolderRelative>$(OutputPath)\..</FrameworkFolderRelative>
      <FrameworkFolder>$([System.IO.Path]::GetFullPath($(FrameworkFolderRelative)))</FrameworkFolder>
    </PropertyGroup>

    <!-- Define files to include -->
    <ItemGroup>
      <NetfwAssemblies Include="$(FrameworkFolder)\net472\AppConfigSample.*" />
      <NetCoreAssemblies Include="$(FrameworkFolder)\netcoreapp3.1\AppConfigSample.*" />
      <AppResources />
      <FileResources />
      <Localizations />
      <ExtensionSupportedRuntimes Include="NetFramework" />
      <ExtensionSupportedRuntimes Include="NetCore" />
    </ItemGroup>

  </Target>
</Project>

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

4. See also

• Understanding the Dundas BI extension format
• Configuration settings
• .NET API: ExtensionPackageInfo2
• .NET API: AppSettingValidationRule
• .NET API: StringValidationRule
• .NET API: OnLoaded method