企业官网建设流程全解析

• 示例工程
• 数据库
• 教程
• 后端

SQL Assessment API（SQL Server 评估 API）提供了一种机制，用于依据最佳实践评估 SQL Server 的配置，并随产品附带了由 SQL Server 团队维护的默认规则集（ruleset.json）。本指南围绕仓库中samples/manage/sql-assessment-api/docs/Reference/的参考文档展开，系统讲解 JSON 规则集的完整配置格式、Check 检查项、Probe 探针体系、SQL 对象匹配模式、表达式与运算符、数据变换（Data Transformation）等核心概念。读完本文，你将能够读懂并编写自定义的规则集 JSON，掌握各类探针的实现参数与适用场景，并能基于表达式、运算符与变换构建精确的评估规则。

参考文档导航：Reference 目录在讲什么

docs/Reference/是 SQL Assessment API 的"常用场景参考"，其 入口文档 将内容组织为四个部分：

• JSON 配置文件格式：规则与探针所在的 JSON 文件结构；
• 探针 Probes：获取评估数据的各种探针类型；
• 数据变换 Data Transformation：对探针返回数据进行的后处理变换；
• 运算符 Operators：用于构建评估条件的逻辑、字符串、数学、集合与比较运算。

这四个部分共同构成了"编写与定制规则集"的完整知识链：探针负责取数 → 变换负责清洗与聚合 → 运算符与表达式负责判定合规性 → Check 输出建议。

JSON 配置文件格式：引擎配置三要素

JSON 配置文件是整个评估引擎的"编程接口"。其顶层结构由 JSONConfiguration.md 定义，共三个属性：

| Property | 类型 | 说明 | |-|-|-| | version | string | 配置文件版本，当前版本为"0.3"。 | | checks | array | 每一项是一个 Check 对象。 | | probes | object | 每个属性代表一个 Probe Family。 |

注意：仓库中的实际示例文件（如 MakingCustomChecks_sample.json）使用schemaVersion、name、rules等字段组织文件，与参考文档中的checks命名对应——rules（规则）即文档中所说的checks（检查项），两者是同一概念的不同叫法。

Check 检查项

Check 是规则集的"最小评估单元"：它描述一个最佳实践或内部策略，针对满足特定条件的目标对象运行，并在条件不满足时输出建议。Check 对象支持以下属性：

| Property | 类型 | 说明 | |-|-|-| | name | string | 简短名称，必须唯一。 | | tags | array of strings | 检查的标签集合，代表检查分组与类别；在 API 调用中可用标签替代检查名称。 | | displayName | string | 展示给用户的长名称。 | | description | string | 解释检查目的的长描述。 | | enabled? | bool | 是否启用检查。被禁用的检查不会对任何对象运行，默认true。 | | messge | string | 检查失败时展示给用户的建议文本。建议文本可包含@{variableName}形式的变量引用，引用会被替换为变量值的字符串表示；还可使用@{variableName:formatString}指定格式化字符串。 | | target? | SQL Object Pattern | 检查只应用于满足该模式的对象，默认匹配任意对象。 | | probes | array of strings | 检查所需的 Probe Family 的 ID 列表。 | | condition? | Condition Expression | 目标对象必须满足的条件表达式。若表达式返回false，则生成建议，默认true。 | | level | string | 严重级别：Information、Warning或Critical。 | | any | Expression | 其他属性被视作检查参数，可在检查表达式中以@前缀的变量名引用；参数可以引用变量或其他参数。 |

以仓库 MakingCustomChecks_sample.json 中的QueryStoreOn检查为例，完整展示了上述属性的用法：

{ "target": { "type": "Database", "version": "[13.0,)", "platform": "Windows, Linux", "engineEdition": "OnPremises, ManagedInstance", "name": { "not": "/^(master|tempdb|model)$/" } }, "id": "QueryStoreOn", "itemType": "definition", "tags": [ "CustomRuleset", "Performance", "QueryStore", "Statistics" ], "displayName": "Query Store should be active", "description": "The Query Store feature provides you with insight on query plan choice and performance. ...", "message": "Make sure Query Store actual operation mode is 'Read Write' to keep your performance analysis accurate", "helpLink": "https://docs.microsoft.com/sql/relational-databases/performance/monitoring-performance-by-using-the-query-store", "probes": [ "Custom_DatabaseConfiguration" ], "condition": { "equal": [ "@query_store_state", 2 ] } }

其中itemType为"definition"（声明新规则）或"override"（覆盖/定制已有规则）——后者的典型用法见 DisablingBuiltInChecks_sample.json，其通过三个 override 分别实现了：按规则 ID 禁用指定规则（LatestCU）、禁用带有TraceFlag标签的全部规则、以及仅针对名为DBName1/DBName2的数据库禁用默认规则集的全部规则：

{ "id": "LatestCU", "itemType": "override", "enabled": false }

Probe 探针

Probe是 JSON 的一个属性：属性名即 Check 中引用的探针族 ID，属性值是一个探针实现（probe implementation）的数组。多个实现按顺序检查其目标模式是否匹配目标对象，第一个匹配的探针将被用于取数，因此探针的顺序很重要。一个探针族可以由 CLR 与 SQL 实现混合构成。

安全边界：安全是用户的责任。探针只读取元数据（如更新日志、服务器属性），不读取表中的用户数据，也不向数据库或实例写入任何内容，不会设置任何标志位或属性。

探针实现是一个 JSON 对象，通用属性如下：

| Property | 类型 | 说明 | |-|-|-| | type | string | 探针类型。支持值：SQL、WMI、External、PowerShell、CmdShell、AzGraph、AzMetadata、Registry。 | | target? | SQL Object Pattern | 探针可应用于满足该模式的对象。 | | implementation | object | 探针所需的任意参数。type="SQL"的探针需要包含query属性（执行取数的 SQL 命令）；CLR 类探针需要class（类名）与assembly（程序集）属性；其余属性用于填充新的类实例。 |

SQL 探针实现

SQL 探针的 implementation 只有一个核心属性：query（T-SQL 查询），查询可以按名称引用参数。

External 探针实现

External 探针指向给定程序集中的任意 .NET 类，该类必须实现IProbeImplementation接口：

| Property | 类型 | 说明 | |-|-|-| | assembly | string | 指定要加载的程序集。 | | class | string | 完整的类名。 |

SQL 对象模式（SQL Object Pattern）：正则与版本范围

Check 与 Probe 的target都使用 SQL 对象模式来限定适用对象。模式包含两类语法。

正则表达式

正则表达式用斜杠包裹："/Win*./"。可在闭合斜杠后指定正则选项，例如不区分大小写的搜索"/win.*/i"。若字符串不以斜杠开头，则视为精确字符串匹配——字符串"Linux"等价于"/^Linux$/"。

版本范围列表

版本范围列表是单个 版本范围 或版本范围数组；单范围等价于只包含该元素的数组。版本范围列表匹配任何命中其中任一范围的版本：

"version": [ "[10.0.4326,10.0.4371]", "[10.0.5794,10.50)", "[10.50.2806,11.0)", "[11.0.2316,)" ]

版本范围

版本范围由字符串编码：包含一个或两个以逗号分隔的版本，外围用可选的圆括号或方括号。若有两个版本，前者必须小于等于后者，它们代表范围的边界。版本至少需要由句点分隔的两个数字指定：主版本号与次版本号。

| 版本范围 | 匹配内容 | |-|-| |"10.0"| 精确匹配版本 10.0。 | |"[10.0, 13.0]"| 10.0 与 13.0 之间的任意版本（含边界）：10.0、10.50、11.0.345、13.0。 | |"(10.0, 13.0)"| 10.0 与 13.0 之间，不含边界：10.50、11.0.345，不匹配 10.0 或 13.0。 | |"[10.0, 13.1)"| 10.0 与 13.1 之间，排除右边界：10.0、10.50、11.0.345、13.0、13.0.234，不匹配 13.1。 | |"(10.0, 13.1]"| 10.0 与 13.1 之间，排除 10.0。 | |"[10.0,)"| 10.0 及以上。 | |"(10.0,)"| 高于 10.0，但不包括 10.0 本身。 | |"(,10.0]"| 10.0 或以下。 | |"(,10.0)"| 低于 10.0，但不包括 10.0。 |

表达式系统：如何表达"合规"与"不合规"

表达式用于计算是否应向用户给出建议，由 JSONConfiguration.md 的 Expression 部分定义。

字面量

• 布尔字面量：JSON 值true和false被当作布尔常量；
• 数字字面量：JSON 数字被当作十进制常量；
• 字符串字面量：表示字符串，但以@开头的字符串除外——它们表示对变量的引用。

变量

变量由包含变量名前缀@的字符串表示。变量值由探针设置，被表达式或建议文本消费。

表达式 JSON 对象

• 具有单个属性的 JSON 对象是由该属性表示的表达式（见下文属性表达式）；
• 具有多个属性的 JSON 对象是 AND 运算的简写形式，其参数即对象的属性，结果在可能的情况下转换为布尔类型。以下两个表达式等价：

expression1: { "@version": "10.50.0", "@memroySize": 4096 } expression2: { "and": [ {"@version": "10.50.0"}, {"@memroySize": 4096} ] }

属性表达式

任何表达式都可以用 JSON 属性的形式表示：属性名是操作名，属性值是操作参数的数组，参数可以是除条件表达式外的任意表达式。

当属性名以@开头时，它不是操作名，而是等值运算（equal）的简写——变量作为第一个参数，唯一的属性值作为第二个参数：

expression1: {"@memorySize": 4096} expression2: { "equal": [ "@memorySize", 4096 ] }

条件表达式

条件表达式可以是任意表达式，或表达式数组。数组是 OR 运算的简写，数组项即操作参数。以下两个表达式等价：

"condition": [ {"@version": "10.50.0"}, {"@memroySize": 4096} ] "condition": { "or": [ {"@version": "10.50.0"}, {"@memroySize": 4096} ] }

注意：OR 的简写仅适用于条件表达式，而 AND 的简写适用于任何位置。以下表达式等价：

"condition": { "@version": "10.50.0", "@memroySize": 4096 } "condition": { "and": [ {"@version": "10.50.0"}, {"@memroySize": 4096} ] }

运算符全集：让评估更精确

Operators.md 提供了五类运算符，可在表达式中组合使用。

逻辑运算

| 运算符 | 参数 | 说明 | |-|:-:|-| | not | (x) | 逻辑非。 | | and | (a..) | 逻辑与，无参数时返回false。 | | or | (a..) | 逻辑或，无参数时返回true。 |

字符串运算

| 运算符 | 参数 | 说明 | |-|:-:|-| | indexof | (str_a, str_b) | 返回 str_b 在 str_a 中首次出现的从零开始的索引。区分大小写。 | | iindexof | (str_a, str_b) | 同上，不区分大小写。 | | startswith | (str_a, str_b) | str_a 以 str_b 开头时返回true。区分大小写。 | | istartswith | (str_a, str_b) | 同上，不区分大小写。 | | endswith | (str_a, str_b) | str_a 以 str_b 结尾时返回true。区分大小写。 | | iendswith | (str_a, str_b) | 同上，不区分大小写。 |

数学运算

| 运算符 | 参数 | 说明 | |-|:-:|-| | ceiling | x | 向上取整到最近的更大或相等值。 | | floor | x | 向下取整到最近的更小或相等值。 | | max | (a, b) | 返回 a、b 的最大值。 | | min | (a, b) | 返回 a、b 的最小值。 | | mul | (a..) | 算术乘法。 | | div | (a, b) | a 除以 b 的算术除法。 | | mod | (a, b) | a 除以 b 的算术余数。 | | add | (a..) | 算术求和。 | | sub | (a, b) | a 与 b 的算术差。 | | bitand | (a..) | 按位与。 | | bitor | (a..) | 按位或。 | | bitxor | (a..*) | 按位异或。 |

集合运算

| 运算符 | 参数 | 说明 | |-|:-:|-| | intersect | (a, b) | a、b 参数的集合交集。区分大小写。 | | in | (a, b) | 检查 a 是否在 b（集合）中被找到。区分大小写。 | | iin | (a, b) | 同上，不区分大小写。 |

in在实战中常用于标签或追踪标记的判断，例如MakingCustomChecks_sample.json中 TF834 检查的条件{ "in": [ 834, "@TraceFlag" ] }即判断探针返回的启用标志列表@TraceFlag中是否包含 834。

比较运算

| 运算符 | 同义词 | 参数 | 说明 | |-|-|:-:|-| | lt | less | (a, b) | a 小于 b。 | | gt | greater | (a, b) | a 大于 b。 | | eq | equal | (a, b) | 两者相等。区分大小写。 | | ieq | | (a, b) | 两者相等。不区分大小写。 | | ge | greaterequal | (a, b) | a 大于等于 b。 | | le | lessequal | (a, b) | a 小于等于 b。 | | ne | notequal | (a, b) | a 不等于 b。区分大小写。 | | ine | | (a, b) | a 不等于 b。不区分大小写。 | | match | | (a, b) | 正则匹配，第二参数视为正则表达式。区分大小写。 | | imatch | | (a, b) | 正则匹配，第二参数视为正则表达式。不区分大小写。 | | interval | | (a, v₁, t₁, ..., vₙ, tₙ, d) | 找到第一个大于等于 a 的 tᵢ，返回对应的 vᵢ；若所有 t 都小于 a，则返回 d。 |

探针家族详解

Probes 参考目录 指出：SQL Assessment API 提供不同类型的探针来获取评估数据，数据既可来自 SQL Server 动态管理视图，也可来自操作系统（例如 Windows 注册表）。各探针类型完整说明如下。

T-SQL 探针（SQL）

T-SQL 探针基于 T-SQL 查询，从指定数据库检索数据供评估使用。其 implementation 参数：

| 参数 | 必填 | 类型 | 默认值 | 说明 | |-|:-:|:-:|:-:|-| | query | 是 | String | | T-SQL 查询 | | UseDatabase | 否 | Bool |false| 是否应在运行查询前发出USE DATABASE语句，用于针对数据库的探针。 | | timeout | 否 | Number | 30 | 设置命令执行超时（秒）。 |

一个从 Linux 主机获取主机信息并配合parse变换解析版本的完整 SQL 探针示例：

{ "type": "SQL", "target": { "type": "Server", "engineEdition": "OnPremises", "platform": "Linux", "version": "[11.0,)" }, "implementation": { "query": "SELECT [host_platform] AS [host_platform] ,[host_release] AS [host_release] ,64 AS [host_architecture] FROM sys.dm_os_host_info(NOLOCK)", "transform": { "type": "parse", "map": { "host_release": "/^(?<major>\\d+)\\.(?<minor>\\d+)(?:\\.(?<build>\\d+))?(?:\\.(?<revision>\\d+))?$/x" } } } }

仓库 MakingCustomChecks_sample.json 中的Custom_DatabaseConfiguration探针族展示了 SQL 探针最典型的用法：同一个探针族针对不同 SQL Server 版本提供多个实现，引擎按target.version自动挑选——(,12.0)（2014 之前）、[12.0, 13.0)（2014）、[13.0,)（2016 及以上）各有一个实现，其中 2016+ 的实现还使用了useDatabase: true让查询在被评估的数据库上下文中执行（等效于USE <DATABASENAME>;），以读取sys.database_query_store_options中的 Query Store 状态。

WMI 探针

WMI 探针运行 WMI 查询。每个 WMI 查询返回若干 WMI 对象，每个对象被当作一行处理；@Output变量代表该对象，用点号记法访问对象属性：@Output.BlockSize。implementation 参数：

| 参数 | 必填 | 类型 | 默认值 | 说明 | |-|:-:|:-:|:-:|-| | query | 是 | String | | 返回探针数据的 WMI 查询 | | methods | 否 | Map | | 要对选中的 WMI 对象调用的 WMI 方法列表 |

调用 WMI 方法时，在methodsJSON 对象中以属性值写出方法名，属性名则是在其中存储结果的变量名。使用$（美元符号）访问由检查传入的探针参数。三个典型示例：

{ "type": "WMI", "target": { "type": "Server", "platform": "Windows", "engineEdition": "OnPremises", "version": "[11.0,)" }, "implementation": { "query": "SELECT Name, StartingOffset FROM Win32_DiskPartition WHERE StartingOffset < $threshold" } }

{ "type": "WMI", "target": { "type": "Server", "platform": "Windows", "engineEdition": "OnPremises", "version": "[11.0,)" }, "implementation": { "query": "SELECT DeviceID, Name FROM Win32_Volume WHERE DriveType=3 AND Name LIKE '_:\\\\'", "methods": { "da": "DefragAnalysis" } } }

后者在每个返回的 WMI 对象上调用DefragAnalysis方法，结果存入@da变量。

PowerShell 探针

PowerShell 探针在目标机器上执行 PowerShell 命令（fx），并将管道输出放入@Output变量。implementation 参数仅一个：command（要执行的 PowerShell 命令，必填）。

• 在command文本中使用$（美元符号）访问检查传入的探针参数；
• 使用.（点号）访问对象属性，例如返回对象是字符串时，@Output.Length返回其长度；
• 注意：管道输出不会显示在屏幕上，例如Write-Host的输出会被忽略。

{ "type": "PowerShell", "target": ..., "implementation": { "command": "Get-ChildItem" } }

CMD Shell 探针（CmdShell）

CmdShell 探针执行 CMD.EXE 的 shell 命令，并将文本行放入@stdout变量。implementation 参数：command（要执行的 shell 命令，必填）。命令返回的每一行是带单个@stdout列的独立数据行，可用 Regex 解析变换从@stdout中提取数据：

{ "type": "CmdShell", "target": ..., "implementation": { "command": "dir" } }

注册表探针（Registry）

Registry 探针从目标机器的注册表获取数据。implementation 参数：

| 参数 | 必填 | 类型 | 默认值 | 说明 | |-|:-:|:-:|:-:|-| | query | 是 | object | | 指定要收集的注册表键与值的树状结构（见下） | | instance | 否 | bool |false| 是否应返回特定于该 SQL Server 实例的数据 |

注册表查询是一个复杂 JSON 对象：顶层属性代表注册表根键（hive），包括HKEY_LOCAL_MACHINE与HKEY_CURRENT_USER；每个顶层属性的值又是另一个 JSON 对象，其属性代表注册表键，属性名是从根键到键的完整路径；在任意层级使用*（星号）可枚举所有键，替换*的键名会返回在@RegistryKeyName变量中；每个键属性的值是待读取的注册表值名数组，多字符串值会被读取为多个同名字符串值。

实例特定数据：当instance为true时，探针将路径中的MSSQLSERVER替换为该 SQL Server 实例特有的注册表路径。例如：

Software\Microsoft\MSSQLSERVER\SQLServerAgent

会被替换为：

Software\Microsoft\Microsoft SQL Server\MSSQL12.SQL2014\SQLServerAgent

其中MSSQL12.SQL2014是 SQL Server 实例名。

枚举 CPU 子键的示例：

{ "type": "Registry", "target": { "type": "Server" }, "implementation": { "query": { "HKEY_LOCAL_MACHINE":{ "HARDWARE\\DESCRIPTION\\System\\CentralProcessor\\*": [ "VendorIdentifier" ] } } } }

注册表探针还支持用@（at-sign）将探针参数插入注册表查询路径，例如"SOFTWARE\\@{hiveParam}"会在运行时被参数值替换（详见 RegistryProbes.md 的 Example 4）。

External 探针

External 探针允许运行外部代码作为探针，可调用任意实现了Microsoft.SqlServer.Management.Assessment.IProbeImplementation接口的 .NET 类。implementation 参数：

| 参数 | 必填 | 类型 | 默认值 | 说明 | |-|:-:|:-:|:-:|-| | class | 是 | string | | 实现IProbeImplementation的类名 | | assembly | 否 | string | SQL Assessment API 引擎程序集 | 包含class的程序集文件路径；未指定时引擎会在内部查找该名称的类。 |

IProbeImplementation接口的属性由引擎赋值，使探针实现可以获得可选参数以及被评估 SQL Server 实例/数据库的信息：

| 属性 | 类型 | 说明 | |-|:-:|-| | ServerName | string | 目标服务器名称 | | TargetName | string | 被评估的实例或数据库名 | | Urn | string | 目标对象的字符串标识符 | | Parameters | dictionary | 检查传入探针的命名参数 |

引擎设置完所有IProbeImplementation属性后，调用GetDataAsync方法检索全部数据。

AzGraph 与 AzMetadata 探针

这两类探针面向 Azure 场景。AzMetadata 探针返回可通过 Azure Instance Metadata Service (IMDS)。

Performance 探针

Performance 探针返回所有请求计数器的多组采样（samples），通常与 performance 变换搭配使用，从采样中计算平均值、最大值等派生值（详见下文数据变换一节）。

数据变换（Data Transformation）：取数之后的关键加工

探针返回的原始数据往往需要二次加工才能用于条件判定。DataTransformation 参考目录 收录了aggregate、defaultValue、nameValuePairs、noData、parse、performance、rename、toString等变换，这里详解其中四个最常用的变换。

aggregate：聚合

aggregate变换接收探针或前一变换返回的所有数据行，对指定列计算聚合值。若指定了分组，则为每个分组返回一个聚合行，否则返回一行。

| 参数 | 必填 | 类型 | 说明 | |-|-|-|-| | map | 是 | Map | 将列名映射到聚合函数 | | group | 否 | String 或字符串数组 | 用于分组的列名，工作方式类似 T-SQL 的GROUP BY|

聚合函数包括：

• and/or：对布尔值计算逻辑与/或聚合。Null、DBNull、空字符串、空数组及字符串'false'转为false；非空字符串、非空数组及字符串'true'转为true。
• array：将所有值收集进一个数组。
• count：统计所有值。参数distinct（可选，默认true，仅统计去重值）、notNull（可选，默认true，仅统计非空值）。
• join：将值转为字符串并按默认逗号连接。参数trim（可选，默认true，去除值首尾空白）、separator（可选，默认', '）、limit（可选，默认 0，大于 0 时最多返回前limit项并以省略号代替其余，如limit=3时[1,2,3,4,5]得到"1, 2, 3, ..."）、distinct（可选，默认true，跳过重复值）、comparison（可选，默认CurrentCulture，指定选取 distinct 值所用的区域性、大小写与排序规则）。
• max/min：计算数值列的最大/最小值，仅限数值。
• sum：计算所有数值之和，仅限数值。

按publisher_db分组并用join构造以逗号分隔的出版物列表：

"transform": { "type": "aggregate", "group": "publisher_db", "map": { "publication": "join" } }

parse：正则解析

正则解析变换从变量值的子串中提取数据，这些子串对应正则表达式中指定的命名组。

| 参数 | 必填 | 类型 | 说明 | |-|-|-|-| | map | 是 | Map | 为变量设置正则表达式 | | flatten | 否 | bool | 启用跨行字段合并 | | join | 否 | string | 启用所有行字符串连接并设置分隔符 |

map 的每个属性为同名变量定义正则表达式，命名组定义的子串被返回为新变量；新变量名由original.group构成（original是被解析的变量名，group是正则组名）。当正则有多处匹配时，每个匹配生成一行；可用 flatten 或 join 将部分匹配打包进单行。

提示：启用 Explicit captures 选项可改善变换的内存占用与性能，在闭合斜杠后使用x开启：/(?<int>\d+)/x。

flattening（合并字段）仅作用于解析过程生成的字段，其他数据会被移除，适用于数据行跨越多行的场景；joining（连接字符串）将所有行合并为一行，仅作用于 map 中提到的变量，其他数据被移除。例如join = ", "时，多行的@a值42、13、0会合并为"42, 13, 0"。

nameValuePairs：行列转置

nameValuePairs变换从探针或前一变换返回的所有数据行中取两列，将这张两列表转置。

| 参数 | 必填 | 类型 | 说明 | |-|-|-|-| | keyColumn | 是 | String | 用于转置的键列名 | | valueColumn | 是 | String | 用于转置的值列名 | | map | 是 | Map | 将 keyColumn 的值映射为列名 |

它从 keyColumn 取一个名称，用其创建新列，填入 valueColumn 中对应的值；若提供了 map，则用 keyColumn 的值作为键在 map 中查找新列名。典型场景是把Metric | MeasuredValue两列转置成多列（如 CPU 利用率、NOPM、磁盘空间、TPM 各成一列）。

performance：性能计数器派生值

Performance 探针返回多个计数器采样的表格，检查往往需要派生值（平均值、最大值等）。Performance 变换用于在探针引用（probe reference）中为检查所使用的每个计数器计算指定的派生值：

可用派生值函数（其中 n 为该计数器的采样数，c₁/c₂ 为采样值，t₁/t₂ 为采样时间戳，b₁/b₂ 为 base_counter 的采样值）：

| 类型 | 参数 | 公式 | |-|:-:|:-:| | average | – | (1/n)Σcᵢ | | delta_ratio |base_counter| (c₂ − c₁) / (b₂ − b₁) | | min/max | – | 所有采样的最小值/最大值 | | rate | – | (c₂ − c₁) / (t₂ − t₁) | | ratio |base_counter| (c₂/b₂ + c₁/b₁) / 2 |

一个完整的性能检查规则集示例（截取自 performance.md）：

{ "schemaVersion": "1.0", "name": "Performance Checks Example", "version": "1.0", "rules":[ { "target": { "type": "Server" }, "id": "CacheHitRatio", "itemType": "definition", "displayName": "Buffer Manager cache hit ratio", "description": "Use \"ratio\" for counter type PERF_LARGE_RAW_FRACTION(537003264) and specify base PERF_LARGE_RAW_BASE(1073939712).", "message": "Cache hit ratio (@{cache_hit_ratio:P0}) is greater than 0", "condition": { "lt": ["@cache_hit_ratio", 0] }, "probes": [ { "id": "PerformanceProbe", "transform": { "type": "performance", "counters": { "cache_hit_ratio": { "type": "ratio", "base": "cache_hit_ratio_base" } } } } ] } ], "probes":{ "PerformanceProbe": [{ "type": "Performance", "implementation": { "Counters": { "Buffer Manager": { "Buffer cache hit ratio": "cache_hit_ratio", "Buffer cache hit ratio base": "cache_hit_ratio_base", "Target pages": "total_pages" }, "Latches": { "Average Latch Wait Time (ms)": "latch_wait_time", "Average Latch Wait Time Base": "latch_wait_time_base" }, "Databases": { "Transactions/sec": "transactions_sec" } } } }] } }

多个性能计数器同用一检查时的坑：当不同计数器需要不同实例（例如batch_request_sec不选实例、lock_requests_sec选_Total）时，条件会按行逐一检查并可能产生意外结果。解决方案是用别名（alias）两次引用同一探针：

"probes": [ { "id": "PerformanceProbe", "alias": "b", "transform": { "type": "performance", "counters": { "batch_request_sec": "rate" } } }, { "id": "PerformanceProbe", "alias": "l", "transform": { "type": "performance", "counters": { "lock_requests_sec": { "type": "rate", "instance": "_Total" } } } } ]

alias 是探针的任意替代名，任何数据变量都可用别名或探针 ID 作前缀，例如以下三个名称在无歧义时指向同一值：

@PerformanceProbe::batch_request_sec @b::batch_request_sec @batch_request_sec

其余变换

参考目录还收录了defaultValue（为变量提供默认值）、noData（处理无数据场景）、rename（重命名列/变量）、toString（类型转换）等变换，完整定义见 DataTransformation 目录。

仓库实战资源：从参考到落地

参考文档之外，仓库提供了可直接运行的实战素材，建议结合使用：

• 两分钟快速上手：QuickStart.md 提供两步评估法——安装模块并执行评估：

Install-Module -Name SqlServer -AllowClobber Get-SqlInstance -ServerInstance 'localhost' | Invoke-SqlAssessment

若要对实例上所有数据库生成建议：

Get-SqlDatabase -ServerInstance 'localhost' | Invoke-SqlAssessment

评估结果形如（详见 images/SQLAssessmentPSResult.png），每条规则带有严重级别（Info/Low/Medium/High）、建议消息 Message、规则 ID（Check ID）以及 Origin（来源规则集及版本）：

Sev. Message Check ID Origin ---- ------- -------- ------ Info Enable trace flag 834 to use large-page allocations to improve TF834 Microsoft Ruleset 0.1.202 analytical and data warehousing workloads. Medi Amount of single use plans in cache is high (100%). Consider PlansUseRatio Microsoft Ruleset 0.1.202 enabling the Optimize for ad hoc workloads setting on heavy OLTP ad-hoc workloads to conserve resources.

• 默认规则集：ruleset.json 是随 API 发布的默认规则集，DefaultRuleset.csv 是其可读版本，GitHub 会以交互式表格渲染 CSV，支持搜索与行过滤，方便熟悉现有规则。
• 自定义示例：MakingCustomChecks_sample.json 演示了含两个检查的自定义规则集（含rules与probes两节）；DisablingBuiltInChecks_sample.json 演示了禁用内置规则的三种 override 写法。
• 交互式学习：notebooks 目录下有两个面向 Azure Data Studio PowerShell 内核的笔记本（需 ADS 1.13.0 及以上）：SQLAssessmentAPIQuickStartNotebook.ipynb用于快速上手，SQLAssessmentAPITutorialNotebook.ipynb是覆盖全部功能（含自定义规则与自建规则）的完整教程，其中CustomizationSamples/还附带了 CLR、CmdShell、PowerShell、Registry、TSQL、WMI 探针及阈值修改等可直接对照的示例 JSON。
• 更进一步的定制文档：Customization 目录深入讲解规则/探针/目标模式的结构（含 SVG 结构图），Tutorials 目录提供创建自定义规则、禁用内置规则、覆盖默认阈值等分步教程。

小结

SQL Assessment API 的参考文档体系可以概括为一条清晰的生产链路：JSON 配置文件（version/checks/probes）→ 各类探针取数（SQL/WMI/PowerShell/CmdShell/Registry/External/AzGraph/AzMetadata/Performance）→ 数据变换加工（aggregate/parse/nameValuePairs/performance 等）→ 表达式与运算符判定（逻辑/字符串/数学/集合/比较）→ 输出带级别与建议的评估结果。理解本文所述的对象模式、表达式简写规则与探针参数，即可在ruleset.json基础上定制出符合自身环境与内部策略的评估规则集。

• 示例工程
• 数据库
• 教程
• 后端