编写自定义原生查询数据源提供程序

1. 概述

1.1 功能概述

Wyn支持编写自定义原生查询数据源提供程序，然后对接入的数据进行加工和处理，并最终通过仪表板或报表实现数据的可视化展示。

1.2 应用场景

当您需要使用自己的数据库，并期望将其数据接入 Wyn，借助 Wyn丰富的可视化图表及报表功能进行数据展示时，本文将为您详细指引编写自定义原生查询数据源提供程序的具体操作流程，提供全面且实用的参考。

2. 操作步骤

2.1 前提条件

安装Microsoft Visual Studio 2022（以下简称VS2022）。

2.2 操作步骤

步骤一：创建项目

1）使用 VS2022，创建一个新的项目，选择C# - 库 - 类库，点击下一步：

QQ_1722391827380

2）输入项目名称，如JavascriptProvider，点击下一步：

QQ_1722392549257

3）选择框架为 .NET 8.0 (长期支持)，点击创建：

步骤二：添加依赖

自定义数据源需要实现定义在Wyn.Data.Provider.Custom.dll程序集中的接口，添加依赖的方法如下：

1）下载下面的程序集到本地。

Wyn.Data.Provider.Custom.dll

2）右键点击依赖项，选择添加项目引用，打开引用管理器：

QQ_1722406210971

3）点击浏览，打开资源管理器：

QQ_1722406261508

4）在资源管理器中找到下载好的程序集Wyn.Data.Provdier.Custom.dll并选择，点击确定：

5）在引用管理器中点击确定，把当前程序集添加到项目依赖中：

type=info
当您在编写自定义数据源时，应该根据实际情况考虑是否还需要添加额外的依赖。
当前示例中演示的是Javascript数据源的编写，需要在 .NET 应用程序中嵌入和执行 JavaScript 代码，因此还需要添加对Jint的依赖，添加方式为：
1. 右键点击依赖项，选择管理NuGet程序包，打开NuGet包管理器。
2. 在NuGet包管理器中搜索Jint并安装。
您可以参考这个流程安装您所需的其他依赖。

可以展开依赖项查看依赖是否添加完成：

步骤三：实现接口

修改默认生成的Class1.cs文件名称为NativeJavascriptProvider.cs，让其实现接口INativeQueryDataProvider。

示例：

public class NativeJavascriptProvider : INativeQueryDataProvider

该接口规定了一个属性和四个方法。

public interface INativeQueryDataProvider
{
	static abstract string ProviderName { get; }

	static abstract INativeQueryDataProvider CreateInstance();

	static abstract void Configure(IFeatureCollection features);

	Task ExecuteAsync(INativeQuery nativeQuery, Action<IDataReader> readerConsumer, params NativeParameter[] parameters);

	Task TestConnectionAsync(string connectionString);
}

接下来，会详细介绍每个成员的作用以及使用方式。

ProviderName

属性。数据源提供程序的名称，应该在全局范围内唯一。

示例：

public static string ProviderName => "Javascript";

Configure

方法。配置数据源提供程序的功能。

方法入参为IFeatureCollection features。

基本配置方式：

名称	描述	示例
Get	获取功能。	features.Get<IParameterParseFeature>()
Set	设置功能。	features.Set<IParameterParseFeature>(MyParameterParseFeature feature)

可配置的功能如下：

1）参数解析

在默认实现中，可以匹配{{pName}}和@pName两种形式的参数。

成员类型	名称	描述
属性	NeedFillParameters	用于指示在调用 `ExecuteAsync` 方法之前是否需要将参数填入查询文本。
方法	FillParameters	将参数替换回查询文本。
方法	Parse	解析查询文本并返回参数。

2）元数据

方法入参为IFeatureCollection features。可以使用features.Metadata()快速获取当前功能的实例。

成员类型	名称	描述
属性	DisplayName	自定义数据源的显示名称。
属性	Description	自定义数据源的描述。
属性	LargeIcon	自定义数据源的大图标。
属性	SmallIcon	自定义数据源的小图标。

3）用户指导

方法入参为IFeatureCollection features。可以使用features.UserGuide()快速获取当前功能的实例。

成员类型	名称	描述
属性	UserGuideMarkdown	设置标记符格式的用户指南内容。它将显示在数据源设计器中。

示例：

public static void Configure(IFeatureCollection features)
{
	features.Metadata().DisplayName = ProviderName;
	features.Metadata().Description = "General-purposed native JDBC connector";

	var assemblyDirectory = Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location);
	if (Path.Combine(assemblyDirectory!, "UserGuide.md") is var userGuidePath && File.Exists(userGuidePath))
	{
		features.UserGuide().UserGuideMarkdown = File.ReadAllText(userGuidePath);
	}

	if (Path.Combine(assemblyDirectory!, "javascript_16x16.png") is var smallIconPath && File.Exists(smallIconPath))
	{
		features.Metadata().SmallIcon = GetDataURL(smallIconPath);
	}

	if (Path.Combine(assemblyDirectory!, "javascript_180x130.png") is var largeIconPath && File.Exists(largeIconPath))
	{
		features.Metadata().LargeIcon = GetDataURL(largeIconPath);
	}

	features.Get<IParameterParseFeature>().NeedFillParameters = true;
}

CreateInstance

静态创建本地查询数据提供程序的实例。

示例：

public static INativeQueryDataProvider CreateInstance() => new NativeJavascriptProvider();

ExecuteAsync

执行本地查询，并将结果作为数据读取器返回。

执行此方法时，应确保在读取器完成工作后，所有非托管资源都已正确关闭。

入参INativeQuery nativeQuery：

名称	描述	备注
ConnectionString	用于连接数据源的连接串。
QueryText	字符串形式的查询文本。
CancellationToken	查询进程的取消令牌。
RowLimitOption	查询行数数限制配置项。	`IRowLimitOption`

IRowLimitOption

名称	描述	备注
RowLimitType	行限制类型。默认为 AllRows。	枚举类型 AllRows：返回所有行数据。 SingleRow：仅返回一行数据。 SchemaOnly：仅返回schema，不返回任何数据。 SpecifiedRowLimit：返回指定的行数。
GetSpecifiedRowLimit	用户指定的确切行数限制。只有当 RowLimitType 为 SpecifiedRowLimit 时才有效并具有值。

名称

描述

备注

RowLimitType

行限制类型。默认为 AllRows。

枚举类型

AllRows：返回所有行数据。

SingleRow：仅返回一行数据。

SchemaOnly：仅返回schema，不返回任何数据。

SpecifiedRowLimit：返回指定的行数。

GetSpecifiedRowLimit

用户指定的确切行数限制。只有当 RowLimitType 为 SpecifiedRowLimit 时才有效并具有值。

入参 Action<IDataReader> readerConsumer：

用于从reader中读取数据的方法。

入参params NativeParameter[] parameters：

查询中所需的参数。

名称	描述
Name	参数名称。
ParameterValue	参数值。

示例：

public Task ExecuteAsync(INativeQuery nativeQuery, Action<IDataReader> readerConsumer, params NativeParameter[] parameters)
{
	if (nativeQuery == null)
	{
		throw new DataException("Native query can not be null.");
	}

	var rawCommandText = nativeQuery.QueryText ?? throw new DataException("Command text can not be null or empty.");
	var engineConfig = EngineConfig.Parse(nativeQuery.ConnectionString);

	int? rowLimit = nativeQuery.RowLimitOption?.RowLimitType switch
	{
		RowLimitType.AllRows => null,
		RowLimitType.SchemaOnly => 0,
		RowLimitType.SingleRow => 1,
		RowLimitType.SpecifiedRowLimit => nativeQuery.RowLimitOption.GetSpecifiedRowLimit,
		_ => null
	};

	using var reader = ScriptExecutor.ExecuteReader(engineConfig, rawCommandText, rowLimit);
	readerConsumer(reader);
	return Task.CompletedTask;
}

TestConnectionAsync

测试连接字符串。实现方式可以是检查连接字符串，也可以是实际连接数据库。如果验证失败，应该抛出异常。

示例：

public Task TestConnectionAsync(string connectionString)
{
	EngineConfig.Parse(connectionString);
	return Task.CompletedTask;
}

type=info
以上仅为实现接口的核心代码，您可以下载下面的文件以获取完整的代码示例。
javascript_provider_source.zip

1. 概述
1.1 功能概述
1.2 应用场景
2. 操作步骤
2.1 前提条件
2.2 操作步骤