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

功能概述

自定义数据源提供程序是一个文件集合，包含一个实现了 Wyn 规定接口的 DLL 程序以及其所需的其它资源文件。

其核心是实现一个连接器，用于链接Wyn和用户自己的数据源。

操作介绍

编写一个自定义数据源的步骤如下（以Javascript数据源为例）：

1. 创建项目

使用 Microsoft Visual Studio 2022（以下简称VS2022），创建一个新的项目，选择C# - 库 - 类库，点击下一步：

QQ_1722391827380

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

QQ_1722392549257

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

2. 添加依赖

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

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

Gcef.CustomProvider.Native.dll

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

QQ_1722406210971

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

QQ_1722406261508

在资源管理器中找到下载好的程序集Gcef.CustomProvider.Native.dll并选择，点击确定：

QQ_1722406305937

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

QQ_1722406432481

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

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

QQ_1722407133282

3. 实现接口

修改默认生成的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=warning
以上仅为实现接口的核心代码，您可以下载下面的文件以获取完整的代码示例。
javascript_source.zip