示例工程数据库教程后端【免费下载链接】sql-server-samplesAzure Data SQL Samples - Official Microsoft GitHub Repository containing code samples for SQL Server, Azure SQL, Azure Synapse, and Azure SQL Edge项目地址https://gitcode.com/gh_mirrors/sq/sql-server-samples点击查看免费下载规则集Ruleset是 SQL Assessment API 评估 SQL Server 配置的核心载体它以单个 JSON 文本文件的形式承载全部最佳实践检查项Rules与数据采集探针Probes的定义。本文以 RulesetFileStructure.md 为主体结合本仓库中 SQL Assessment API 的完整文档体系与示例 JSON 文件系统讲解规则集文件的顶层结构、规则与探针的组织方式、目标匹配与版本区间语法并给出可直接复制改造的自定义规则集实战样例帮助读者从零构建属于自己的 SQL Server 最佳实践检查清单。规则集文件一个 JSON 对象承载一份评估策略在 SQL Assessment API 中规则集存储在一个文本文件里文件内容是一个 JSON 对象。该 JSON 对象定义了针对哪些 SQL Server 目标、按哪些最佳实践规则、通过哪些探针采集数据的完整评估策略。引擎可以同时加载多个规则集并按照添加顺序依次应用其中的规则。三个必填顶层属性规则集对象包含三个简单且必须存在的顶层属性| 属性 | 类型 | 说明 | | - | - | - | |name| string | 规则集名称用于标识该规则集 | |version| string | 规则集版本号 | |schemaVersion| string | 文件格式版本号用于声明 JSON 结构所遵循的格式版本 |其中schemaVersion决定了文件格式的解析方式。截至本文编写时文件格式版本为1.0。而name与version共同构成规则集的身份标识identity——引擎据此区分不同规则集及其迭代版本。两个可选顶层属性rules 与 probes除了必填属性之外规则集还有两个可选的核心属性rules一个由 SQL Assessment API 规则组成的数组。规则用于构建检查清单checklist每条规则要么定义一个新的检查项要么修改一个或多个已有的检查项。probes探针定义集合。探针用于从目标 SQL Server 实例、宿主机及其他数据源获取真实数据如动态管理视图、注册表、WMI、Azure 元数据等。每个探针定义是一个 JSON 数组数组中包含一个或多个实现implementation以便针对不同版本的 SQL Server 选用最合适的实现。rules与probes之所以都是可选的是因为一个规则集里的规则可以引用另一个规则集中的探针——这为规则的复用与分层管理提供了极大的灵活性。例如你可以维护一份公共探针规则集再在多个业务规则集中共享其中的探针。官方文档 RulesetFileStructure.md 给出了规则集文件的整体结构示意图规则集文件的完整骨架示例{ name: Ruleset name, version: Ruleset version, schemaVersion: Schema version, rules:[ { … rule A … }, { … rule B … }, … ], probes:{ probe1: [ { … implementation 1 … }, { … implementation 2 … }, … ], probe2: [ … ], … } }规则Rules如何构建评估检查清单规则是 SQL Assessment API 评估流程的核心。理解规则首先要理解评估引擎的两步工作流程详见 RulesandProbes.md为给定目标构建检查清单清单中包含针对该目标服务器或数据库的完整检查项集合逐项验证并报告违规引擎遍历清单检查目标是否满足每一条最佳实践对不满足的项生成消息报告。之所以需要规则这种抽象是因为最佳实践并非放之四海而皆准准则取决于 SQL Server 版本、版本类型Edition、宿主平台、甚至使用模式。例如某些最佳实践只适用于云环境另一些则针对物理机上的实例msdb数据库的最佳实践集合也与用户数据库不同。规则通过target模式精准界定适用范围从而让同一套评估机制适配千差万别的环境。规则的 itemTypedefinition 与 override每条规则都是一个 JSON 对象其itemType属性决定规则的行为详见 Rule.mddefinition定义一条新的检查项override修改一个或多个已有的检查项。一个检查项可以被多条规则影响。第一条规则definition必须定义检查项并赋予其唯一的字符串 ID。检查项可以带有tags标签从而支持按组管理。此后的 override 规则可以通过 ID 或标签引用检查项一次修改多个检查项。例如下面的 definition 规则使 ID 为MaxMemory的检查项出现在所有 SQL Server 2012 及以上实例的清单中并将其limit参数设置为 2147483647{ id: MaxMemory, itemType: definition, target: { type: Server, version: [11.0,) }, limit: 2147483647 }下面的 override 规则修改上述检查项的limit参数{ id: MaxMemory, itemType: override, limit: 2000000000 }override 规则还可以借助targetFilter只修改特定目标上的检查项。例如针对不同版本类型engineEdition为MaxMemory设置不同的内存上限{ id: MaxMemory, itemType: override, targetFilter: { engineEdition: Standard }, limit: 131072 }, { id: MaxMemory, itemType: override, targetFilter: { engineEdition: Express }, limit: 1410 }enabled 属性清单中的检查项不一定都会执行检查项出现在清单中并不代表它一定会被评估引擎执行。每个检查项都有enabled属性默认值为true如果所有规则应用完毕后该属性变为false引擎将跳过该检查项。例如下面的 override 规则通过targetFilter针对所有运行在 Linux 上的实例一次性禁用MaxMemory检查项以及所有带Performance标签的性能相关检查项{ id: [ MaxMemory, Performance ], itemType: override, targetFilter: { platform: Linux }, enabled: false }规则的完整属性清单依据 Rule.md 与 RulesandProbes.md一条规则支持以下属性| 属性 | 取值/类型 | 说明 | | - | - | - | |itemType|definition/override| 定义新检查项或修改已有检查项 | |tags| string 数组 | 用于分类检查项的短标签如Memory表示内存相关最佳实践单词标签效果最佳 | |id| string 或 string 数组 | 被定义/修改的检查项 ID数组形式可同时按多个 ID 或标签选择检查项命中任一标签即生效 | |target| Target pattern | 目标模式规则仅应用于匹配该模式的对象 | |targetFilter| Target pattern | 与target语法相同但专用于 override 规则| |displayName| string | 显示在清单中的短名称说明该检查项在查什么 | |message| string | 消息模板当检查项发现不符合最佳实践时展示给用户支持变量插值 | |description| string | 长描述解释为何检查该问题及其影响 | |helpLink| string | 指向最佳实践说明与修复建议的超链接 | |level|Information/Low/Medium/High| 问题严重级别 | |probes| array | 本检查项所需探针的引用列表 | |condition| 表达式对象 | 条件表达式返回true表示最佳实践已落实返回false则向用户展示message| |parameters| 任意属性 | 随探针数据一起传给条件、消息模板、探针参数及 transform 的任意参数 |条件表达式的求值语义每个检查项都需要数据来支撑分析。检查项本身不从目标服务器或数据库检索任何数据而是引用探针probes来获取数据。每个探针返回零行或多行包含命名项named items的数据如果检查项从多个探针取数结果数据集按所有行的组合类似 T-SQL 的CROSS JOIN构建。条件的求值是逐行进行的例如某数据库用 3 块磁盘存放文件那么磁盘剩余空间类最佳实践会分别作用于每块磁盘若一个检查项使用两个探针一个产生 2 行数据、另一个产生 3 行则条件将被求值 2×36 次若其中 2 次结果为false该检查项将产生 2 条消息。探针Probes检查项的数据来源探针解决了数据从哪来的问题。SQL Assessment API 的探针类型十分丰富不仅限于 T-SQL 查询还支持从操作系统与云平台取数。完整类型列表见 Probes 参考文档| 类型 | 说明 | | - | - | | AzGraph | 针对 Azure Resource Graph 的 Kusto 查询 | | AzMetadata | 针对 Azure Instance Metadata Service 返回对象的 JSONPath | | CMD | 在目标机器上运行的命令外壳脚本 | | External | 任意 .NET 代码实现IProbeImplementation接口的类 | | PowerShell | PowerShell 脚本 | | Registry | 从注册表读取数据 | | SQL | T-SQL 查询 | | WMI | WMI 查询 |探针定义结构在规则集 JSON 中探针以属性形式存在属性名即探针 ID供规则引用属性值是一个探针实现数组详见 Probe.mdprobes:{ Custom_DatabaseConfiguration: [ { … implementation 1 … }, { … implementation 2 … } ] }评估引擎会按数组顺序选择第一个 target 模式匹配的实现因此实现顺序很重要。一个探针可以由 CLR 与 SQL 实现混合组成其他规则集也可以在此列表之上追加实现。探针实现的属性包括| 属性 | 说明 | | - | - | |type| 探针类型上表所列之一 | |target| 目标模式与规则的 target 语法一致用于按版本/平台/版本类型等选择实现 | |implementation| 探针参数与数据变换transform对 T-SQL 探针核心参数是query| |requires| 显式功能需求若需求不满足探针不执行、依赖它的检查项全部跳过并返回警告 | |runFor| 显式逻辑需求若需求不满足探针实现不执行且立即返回空结果集 |以 T-SQL 探针为例其implementation支持以下参数见 TSQLProbes.md| 参数 | 必填 | 类型 | 默认值 | 说明 | | - | :-: | :-: | :-: | - | |query| 是 | String | - | T-SQL 查询 | |useDatabase| 否 | Bool |false| 是否在运行查询前发出USE DATABASE语句适用于以数据库为目标的探针 | |timeout| 否 | Number | 30 | 命令执行超时时间秒 |探针的设计约定从源码结构与官方文档可以总结出探针的几条关键设计约定探针应设计为无副作用side-effect free的函数引擎对探针的调用顺序不做保证可能为了优化目标 SQL Server 负载而重排探针调用当没有任何检查项需要某探针的数据时该探针不会被调用默认规则集ruleset.json中的探针只读取元数据如更新日志、服务器属性不读取表用户数据、不向数据库或实例写入任何内容也不设置任何标志或属性。探针实现的分版本示例由于动态管理视图在不同 SQL Server 版本间存在差异探针常按版本拆分多个实现。下面这个例子展示了针对 SQL Server 2016 及以上version为[13.0,)的探针实现——注意它通过useDatabase: true在目标数据库上下文中执行并从sys.database_query_store_options读取 Query Store 状态{ type: SQL, target: { type: Database, version: [13.0,), platform: Windows, Linux, engineEdition: OnPremises, ManagedInstance }, implementation: { useDatabase: true, query: SELECT db.is_auto_create_stats_on, db.is_auto_update_stats_on, (SELECT CAST(actual_state AS DECIMAL) FROM [sys].[database_query_store_options]) AS query_store_state, db.collation_name, (SELECT collation_name FROM master.sys.databases (NOLOCK) WHERE database_id 1) AS master_collation, db.is_auto_close_on, db.is_auto_shrink_on, db.page_verify_option, db.is_db_chaining_on, db.is_auto_create_stats_incremental_on, db.is_trustworthy_on, db.is_parameterization_forced FROM [sys].[databases] (NOLOCK) AS db WHERE db.[name]TargetName } }目标模式Target Pattern与版本区间语法无论是规则还是探针实现都依赖目标模式来界定适用范围。目标模式是一个 JSON 对象所有属性都是可选的省略任何属性即表示匹配一切值完整说明见 TargetPattern.md。目标模式的主要属性| 属性 | 取值/语法 | 说明 | | - | - | - | |type|Server/Database| 匹配的 SQL Server 对象类型支持逗号分隔列表 | |version| 版本区间列表 | 匹配的 SQL Server 版本范围 | |engineEdition|PersonalOrDesktopEngine/Standard/Enterprise/Express/AzureDatabase/DataWarehouse/StretchDatabase/ManagedInstance| 版本类型Azure是AzureDatabase, DataWarehouse, StretchDatabase, ManagedInstance的简写SqlServer是PersonalOrDesktopEngine, Standard, Enterprise, Express的简写 | |platform|Windows/Linux| 宿主机平台 | |machineType|Physical/AzureVm/Hypervisor/Other| 宿主机类型 | |name| 字符串模式 | 目标对象的名称数据库名或实例名支持正则与not否定 | |serverName| 字符串模式 | SQL Server 实例名目标为实例时等于name否则为目标对象所在实例名 |字符串模式与正则字符串模式可以是一个普通字符串精确匹配、以/开头和结尾的正则表达式支持 .NET 正则及选项如/win.*/c表示区分大小写、JSON 数组任一元素匹配即匹配或仅含not属性的 JSON 对象匹配不是该值的一切。示例匹配除master、tempdb、model之外的任何数据库name: { not: /^(master|tempdb|model)$/ }注意正则默认不区分大小写如需区分大小写请使用c选项。版本区间Version Range语法版本区间字符串遵循 NuGet 版本区间格式一个或两个由逗号分隔的版本外层可选用括号()开区间或方括号[]闭区间版本至少需包含用句点分隔的主版本号和次版本号。常用写法| 版本区间 | 匹配内容 | | - | - | |10.0| 精确匹配版本 10.0 | |[10.0, 13.0]| 10.0 到 13.0含两端 | |(10.0, 13.0)| 10.0 到 13.0不含两端如 10.50、11.0.345 | |[10.0, 13.1)| 10.0 到 13.1不含右边界 | |[10.0,)| 10.0 及以上 | |(,10.0]| 10.0 及以下 | |(,10.0)| 低于 10.0 |version属性还可以是版本区间列表数组匹配任一区间即通过。例如同时匹配 SQL Server 2016 SP2、2014 SP3 与 2019version: [[13.0.5026.0, 14.0), [12.0.6024.0, 13.0), [15.0)]仓库自带规则集样例拆解仓库在 sql-assessment-api 目录下提供了两个可直接参考的规则集样例文件它们正是 RulesetFileStructure.md 末尾列出的两个示例。样例一DisablingBuiltInChecks_sample.json —— 用 override 禁用内置检查DisablingBuiltInChecks_sample.json 演示了如何通过 override 规则禁用内置检查包含三种典型场景{ schemaVersion: 1.0, version: 0.2, name: Custom Overrides, rules:[ { id: LatestCU, itemType: override, enabled: false }, { id: [TraceFlag], itemType: override, enabled: false }, { id: [DefaultRuleset], itemType: override, targetFilter: { type: Database, name: /^(DBName1|DBName2)$/ }, enabled: false } ] }逐条解读按 ID 禁用id: LatestCU通过 ID 精确禁用最新累积更新检查项按标签禁用id: [TraceFlag]通过标签一次性禁用所有与 TraceFlag 相关的检查项按目标过滤禁用id: [DefaultRuleset]配合targetFilter数据库类型且名称为DBName1或DBName2仅对这两个数据库禁用整个默认规则集所有带DefaultRuleset标签的检查项。样例二MakingCustomChecks_sample.json —— 从零定义自定义检查MakingCustomChecks_sample.json 是更完整的示例同时包含rules与probes两部分演示如何从零定义两个自定义检查项。自定义规则一Query Store 应处于活动状态该规则针对 SQL Server 2016 及以上version: [13.0,)、Windows/Linux 平台、本地部署或托管实例engineEdition: OnPremises, ManagedInstance上的所有非系统数据库检查 Query Store 的实际操作模式是否为读写query_store_state等于 2{ 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 ] } }这里condition表达式equal: [ query_store_state, 2 ]中的query_store_state是探针返回数据中的命名项——探针与条件表达式通过变量名完成数据对接。自定义规则二TF 834 大页内存分配含 override 定制先定义一条针对本地部署服务器engineEdition: OnPremises的检查项条件为全局 TraceFlag 列表TraceFlag中应包含 834{ target: { type: Server, platform: Windows, Linux, engineEdition: OnPremises }, id: Custom_TF834, itemType: definition, tags: [ CustomRuleset, TraceFlag, Performance, Memory, ColumnStore ], displayName: TF 834 enables large-page allocations, description: Trace Flag 834 causes the server to use large-page memory (LPM) model for the buffer pool allocations. …, message: Enable trace flag 834 to use large-page allocations to improve analytical and data warehousing workloads., level: Information, probes: [ Custom_EnabledGlobalTraceFlags ], condition: { in: [ 834, TraceFlag ] } }随后用一条 override 规则针对更早的 SQL Server 版本targetFilter.version: (,11.0)覆盖描述、消息与帮助链接——这展示了同一规则 ID 的 definition 与 override 协同工作的模式。配套探针多实现 数据变换该规则集的probes部分定义了Custom_DatabaseConfiguration按 SQL Server 版本拆分为三个 T-SQL 实现2016 版本使用useDatabase并在sys.database_query_store_options中取 Query Store 状态以及Custom_EnabledGlobalTraceFlags。后者通过DBCC TRACESTATUS获取全局启用的 TraceFlag并借助transform中的aggregate变换将TraceFlag列聚合为数组供规则条件中的in操作符使用Custom_EnabledGlobalTraceFlags: [ { type: SQL, target: { type: Server, engineEdition: OnPremises, ManagedInstance }, implementation: { query: DECLARE tracestatus TABLE (TraceFlag NVARCHAR(40), [Status] tinyint, [Global] tinyint, [Session] tinyint); INSERT INTO tracestatus EXEC (DBCC TRACESTATUS WITH NO_INFOMSGS); IF NOT EXISTS(SELECT * FROM tracestatus WHERE Global1) SELECT 0 AS [TraceFlag], 0 AS [Status] ELSE SELECT [TraceFlag], [Status] FROM tracestatus WHERE Global1, transform: { type: aggregate, map: { TraceFlag: array } } } } ]组合多个规则集引擎的应用顺序与覆盖机制SQL Assessment API 允许用户逐个添加多个规则集到评估引擎。构建检查清单时引擎按规则集添加的顺序依次应用其中的规则。这意味着后添加规则集中的 override 规则可以覆盖先前规则集含默认规则集中定义的检查项一条检查项可以被多条规则反复修改最终状态由定义 依序覆盖共同决定一个规则集的规则可以使用另一个规则集定义的探针规则与探针的归属关系被解耦。默认规则集 ruleset.json 由 SQL Server 团队随 API 发布并随版本不断扩充仓库还提供了可读版本 DefaultRuleset.csv方便浏览既有检查项及其全部字段。在动手编写自定义规则集之前建议先通读默认规则集了解内置规则 ID、标签与探针命名规律——因为自定义 override 的第一步就是精确引用内置检查项。实践建议与后续学习路径编写自定义规则集时可以遵循以下流程明确目标用target/targetFilter精确界定要评估的服务器版本、版本类型、平台与数据库名称范围复用探针优先复用默认规则集中的探针探针可从其他规则集借用仅在数据不足时按 Probe.md 定义新探针定义规则用itemType: definition声明新检查项通过condition表达式描述合规状态并用level标明严重级别精细覆盖用itemType: override结合targetFilter针对特定环境微调默认规则例如在 Linux 上禁用不适用检查、为不同版本类型设置不同阈值验证结构确保name、version、schemaVersion当前为 1.0三个必填属性齐全JSON 语法合法。如需深入了解规则与探针的细节可继续阅读本仓库中的相关文档规则详解Rule.md探针详解Probe.md 与 ProbeReference.md目标模式与版本区间TargetPattern.md探针类型参考Probes数据变换DataTransformation.md分步教程CreatingCustomRules.md、DisablingBuiltInRules.md、OverridingDefaultThresholds.md掌握规则集文件结构就等于掌握了 SQL Assessment API 的配置语言——无论是微调内置最佳实践还是落地企业内部的配置基线都可以通过一份 JSON 文件优雅地完成。赞分享示例工程数据库教程后端【免费下载链接】sql-server-samplesAzure Data SQL Samples - Official Microsoft GitHub Repository containing code samples for SQL Server, Azure SQL, Azure Synapse, and Azure SQL Edge项目地址https://gitcode.com/gh_mirrors/sq/sql-server-samples点击查看免费下载相关推荐使用 ASP.NET Core 与 SQL Server FOR JSON 构建 ReactJS 评论应用sql-server-samples 中的 JSON 前后端集成实战使用 ASP.NET Core 与 SQL Server FOR JSON 构建 ReactJS 评论应用sql server samples 中的 JSON示例工程数据库教程后端Hap QuickTime视频编码器实现10倍性能提升的硬件加速视频编解码架构设计指南Hap QuickTime视频编码器实现10倍性能提升的硬件加速视频编解码架构设计指南 Hap QuickTime视频编码器是一款专为现代图形硬件优化的开源视示例工程数据库教程后端SQL Assessment API 版本演进全解从 GA 到 1.1.17 的 Performance 探针体系与内置规则集SQL Assessment API 版本演进全解从 GA 到 1.1.17 的 Performance 探针体系与内置规则集 本文以 sql server示例工程数据库教程后端上一篇Transformers 自定义 Kernel 编写指南基于扩展 KernelConfig API 的参数转换与模块融合下一篇Snoop实战10个真实案例教你高效进行网络调查创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考