Create custom application configuration settings

Contents[Hide]

1. Overview

This sample shows how to create custom application configuration settings.

2. Getting started

The following prerequisites must be installed on your computer:

  • Visual Studio 2017, or higher
  • Microsoft .NET Framework 4.7.2 or higher, and Microsoft .NET Core 3.1 or higher
  • A deployed instance of Dundas BI version 7 or higher

2.1. Downloading sample solution

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

2.2. Extracting sample to a folder

This sample is designed to automatically publish the extension to the instance. First, you must extract AppConfigSample.zip to a folder.

2.3. Opening solution

Find and open the solution located at:

[extracted folder]\AppConfigSample\AppConfigSample.sln

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.

   
using Dundas.BI;
using Dundas.BI.Configuration;
using Dundas.BI.Extensibility;

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Text.RegularExpressions;
using System.Threading.Tasks;

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 Props

This sample has a mechanism to automatically publish the extension when building. This mechanism is the Dundas.BI.PublishExtension NuGet package. When the Dundas.BI.PublishExtension package is added to the project it creates a PublishExtensionTemplate.props file in the project. This file contains Msbuild property and item groups, these are defined to create the extension.

When the DtFilePath property is set to the file path of the dt utility inside an instance. It will then publish the extension to that instance. It will also then touch the web.config to force the web application to reset.

If the DtFilePath property is not set it will create a zip file in the based on the ExtensionOutputFolder folder. This can then be added through the Dundas BI user interface to add the extension to the instance.

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

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

      <!-- Extension Author -->
      <ExtensionAuthor>Dundas 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>

3.4. Older version of this sample

To download the older version 6 sample, click here.

4. 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