[.NET] 使用C#开发SQL Function来提供数据 - 天气预报

范例下载

范例程序代码：点此下载

问题情景

开发人员在设计一些数据汇整的系统服务时，可能会选择WCF、WebAPI、SignalR...等等通讯框架，来开放API给客户端开发人员使用。但在一些特殊的开发案例中，客户会很婉转的告知开发人员，上述这些技术太新，客户端开发人员无法理解与使用这样的技术。

为了满足这类客户的需求，开发人员可以选择将系统服务封装成为SQL Function并且布署到SQL数据库；后续客户端开发人员透过SELECT语法来查询SQL数据库，就可以取得系统服务所提供的数据，大幅降低客户端开发人员使用系统服务的技术门坎。

本篇文章介绍如何将系统服务封装成为SQL Function来提供数据，为自己留个纪录也希望能帮助到有需要的开发人员。

数据源

为了降低范例的复杂度，后续范例使用CLK.OpenDataAPIs套件中的WeatherAPI类别做为系统服务，来示范如何将系统服务封装成为SQL Function。

这个CLK.OpenDataAPIs套件可以由NuGet取得，套件中的WeatherAPI类别透过HTTP通讯协议从政府数据开发平台(http://data.gov.tw/)取得县市天气预报，用来提供天气预报的相关数据给开发人员使用。

功能开发

01.建立DataBase

示范如何将系统服务封装成为SQL Function，第一个步骤就是建立一个用来安装SQL Function的范例数据库：ClrSampleDB。

02.设定DataBase - 开启SQLCLR

接着为了在SQL Server中执行C#所开发的SQL Function，必须要先透过下列的SQL指令，在SQL Server中开启CLR的功能。

EXEC sp_configure 'clr enabled', 1

GO

RECONFIGURE

GO

03.建立数据库项目

完成了上列数据库的基本设定，就可以开启Visual Studio来动手建立数据库类型项目：CLK.OpenDataAPIs.SqlExtension。

04.参考CLK.OpenDataAPIs

接着为CLK.OpenDataAPIs.SqlExtension项目，加入CLK.OpenDataAPIs套件来做为系统服务。这个CLK.OpenDataAPIs套件可以由NuGet取得，但是在Visual Studio中数据库类型项目，并不支持使用NuGet来加入套件参考，所以开发人员在这个步骤要手动加入套件参考。

开启NuGet Package Explorer来下载CLK.OpenDataAPIs的DLL：CLK.OpenDataAPIs.dll。
取得CLK.OpenDataAPIs.dll之后，就可以将这个套件DLL加入CLK.OpenDataAPIs.SqlExtension数据库项目的参考。

05.设定CLK.OpenDataAPIs

接着还需要将CLK.OpenDataAPIs.dll的属性变更为下图的内容，其中最重要的就是「权限集合」这个属性必须要设定为「外部」，这样SQL Server在执行的时候，才会允许CLK.OpenDataAPIs.dll开启HTTP通讯协议来取得资料。

06.设定数据库项目 - 可信任 & 权限等级

设定完加入的套件参考之后，还要接着设定数据库项目的属性：可信任、权限等级，这两个属性必须要设定为下图所示的内容，后续SQL Server在执行的时候，才会允许这个数据库项目CLK.OpenDataAPIs.SqlExtension.dll，使用CLK.OpenDataAPIs.dll开启HTTP通讯协议来取得资料。

07.封装SQL Function

完成上述这个琐碎的设定之后，就可以写程序来将CLK.OpenDataAPIs套件中的WeatherAPI类别封装成为SQL Function。

public partial class UserDefinedFunctions

{

    [SqlFunction(TableDefinition = @"LocationName nvarchar(MAX),

                                     IssueTime datetime,

                                     StartTime datetime,

                                     EndTime datetime,

                                     MaxTemperature int,

                                     MaxTemperatureUnits nvarchar(MAX),

                                     MinTemperature int,

                                     MinTemperatureUnits nvarchar(MAX),

                                     ProbabilityOfPrecipitation int,

                                     ProbabilityOfPrecipitationUnits nvarchar(MAX),

                                     Weather int,

                                     WeatherText nvarchar(MAX),

                                     ComfortIndexText nvarchar(MAX)",

                FillRowMethodName = "WeatherAPI_GetAllForecast_FillRowMethod")]

    public static IEnumerable WeatherAPI_GetAllForecast()

    {

        return new WeatherAPI().GetAllForecast();

    }

}

public partial class UserDefinedFunctions

{

    // Methods

    public static void WeatherAPI_GetAllForecast_FillRowMethod(object row,

                                                               ref SqlString LocationName,

                                                               ref SqlDateTime IssueTime,

                                                               ref SqlDateTime StartTime,

                                                               ref SqlDateTime EndTime,

                                                               ref SqlInt32 MaxTemperature,

                                                               ref SqlString MaxTemperatureUnits,

                                                               ref SqlInt32 MinTemperature,

                                                               ref SqlString MinTemperatureUnits,

                                                               ref SqlInt32 ProbabilityOfPrecipitation,

                                                               ref SqlString ProbabilityOfPrecipitationUnits,

                                                               ref SqlInt32 Weather,

                                                               ref SqlString WeatherText,

                                                               ref SqlString ComfortIndexText)

    {

        // Require

        Forecast forecast = row as Forecast;

        if (forecast == null) throw new InvalidOperationException();

        // Fill

        LocationName = forecast.LocationName;

        IssueTime = forecast.IssueTime;

        StartTime = forecast.StartTime;

        EndTime = forecast.EndTime;

        MaxTemperature = forecast.MaxTemperature;

        MaxTemperatureUnits = forecast.MaxTemperatureUnits;

        MinTemperature = forecast.MinTemperature;

        MinTemperatureUnits = forecast.MinTemperatureUnits;

        ProbabilityOfPrecipitation = forecast.ProbabilityOfPrecipitation;

        ProbabilityOfPrecipitationUnits = forecast.ProbabilityOfPrecipitationUnits;

        Weather = forecast.Weather;

        WeatherText = forecast.WeatherText;

        ComfortIndexText = forecast.ComfortIndexText;

    }

}

这段封装的步骤有点复杂，拆成几块会比较好理解。

首先在Function中将回传数据格式定义为IEnumerable，这代表Function会回传一个数据集合。

在SQL Server中是以Table来处理数据，没有办法处理IEnumerable类型回传的数据集合。为了将IEnumerable类型转换为Table让SQL Server能够处理，必须要先在SqlFunction特性的TableDefinition属性中，定义IEnumerable类型的数据集合会被转换为何种格式的Table的Schema。

SQL Server没有提供自动依照Table Schema来转换IEnumerable类型数据集合的功能，必须要开发人员写程序将数据集合中的每个数据对象，转换为Table中的每一行Row。而在SqlFunction特性的FillRowMethodName属性中，可以指定用来将数据对象转换为Table Row的转换函式。

在这个将数据对象转换为Table Row的转换函式中，必须依照先前SqlFunction特性的TableDefinition属性所定义的Table Schema，来定义做为函式输出的ref参数，在这其中每个ref参数对应到一个Table Schema的字段。

最后就是将每个数据对象属性，填入对应的ref参数，用来输出成为每个Table Row的字段内容。至此就完成整个SQL Function的设计，这个SQL Function在执行的时候，就会取得数据集合并且依照程序定义将每个数据对象转为Table Row来组成Table提供给SQL Server使用。

08.发行数据库项目

将CLK.OpenDataAPIs套件中的WeatherAPI类别封装成为SQL Function之后，还需要将包含这个SQL Function的数据库项目，发行到先前建立的范例数据库：ClrSampleDB里面。

09.检视DataBase

完成上列一连串的动作之后，就可以在数据库看到数据库项目中发行的组件以及函数。

功能使用

在SQL Server中，C#开发SQL Function与原生的SQL Function是同等级的存在，可以透过SQL语法来调用。

SELECT * FROM WeatherAPI_GetAllForecast()

当然也可以将SQL Function封装成为View，让使用者更方便的使用。

参考数据

张小呆的碎碎念 - 使用 SQLCLR 来实作 SPLIT