validation-testing

Power BI 验证与自测试

概述

适用于开发者（或 Claude）生成的任何 TMDL、PBIR、DAX 或 M 工件的验证技能。目标是在 Fabric REST 部署失败之前，在本地捕获语法、架构和最佳实践错误。这项技能对于 powerbi-expert Agent 的自验证协议至关重要——每当 Agent 编写 TMDL 或 PBIR 时，都应说明（或运行）本技能中对应的验证步骤。

截至 2026 年，Power BI 验证分为四个不同层次，每层用于捕获不同类别的错误：

层次	TMDL 工具	PBIR 工具	捕获的问题
1. 语法 / 解析器	TmdlSerializer.DeserializeDatabaseFromFolder（.NET）	JSON 架构验证（$schema URL）	缩进错误、无效关键字、格式错误的 JSON
2. 对象 / 架构	TmdlSerializer -> TmdlSerializationException（语法有效，但 TOM 元数据无效）	microsoft/json-schemas 仓库中的 PBIR JSON 架构	无效的属性组合、类型不匹配、缺少必需属性
3. 最佳实践（BPA）	Tabular Editor BPA 规则（BPARules.json）或 semantic-link-labs.run_model_bpa	PBI-InspectorV2 规则（Base-rules.json）	反模式、缺少显示文件夹、关系不明确、命名约定
4. 血缘 / 交叉引用	DAX 度量值引用可解析，sortByColumn 存在，计算组优先级	书签引用真实页面，钻取目标存在，主题文件存在	悬空引用、失效书签、缺失视觉对象

基本原则： 未通过第 1 和第 2 层验证，绝不部署；未通过第 3 层验证，绝不合并到 main。

2026 年验证工具概览

工具	验证内容	运行时	状态
TmdlSerializer（Microsoft.AnalysisServices.Tabular）	TMDL 语法 + TOM 架构	.NET / pythonnet	GA
Tabular Editor 2 CLI（免费）	TMDL 加载 + BPA + 自定义 C# 脚本	.NET CLI	GA，免费
Tabular Editor 3 CLI（付费）	同上 + 高级规则 + DAX 调试器	.NET CLI	GA，商业版
semantic-link-labs.run_model_bpa	使用 Python 对 TMDL/TOM 模型执行 BPA	Fabric 笔记本（Python）	GA，内置约 60 条规则
semantic-link-labs.run_model_bpa_bulk	对工作区中的所有模型执行 BPA	Fabric 笔记本	GA
PBI-InspectorV2（“Fab Inspector”）	PBIR / PBIP / Fabric 项目规则	.NET CLI / Docker	v2.3+，GA
pbi-tools	PBIX 提取/编译 + 基础 TMDL	.NET CLI	TMDL 功能稳定，PBIR 功能持续演进
fabric-cicd（内置）	部署前检查 parameter.yml + 仓库结构	Python	GA
DaxFormatter API	DAX 语法	HTTP	GA
Microsoft TMDL VS Code 扩展	编辑器中的 TMDL 语法	VS Code	GA
社区版 CPIM.TMDL-language-support	TMDL + DAX + M 语义高亮	VS Code	GA
INFO DAX 函数	实时模型内省（取代 DMVs）	XMLA / Desktop	GA

自验证协议（适用于生成的工件）

在 Agent 循环中生成 TMDL 或 PBIR 工件时，请遵循以下最低协议：

1. 写入文件之前——在思路中验证结构：每个对象引用都必须能够解析，每个必需属性都必须设置。
2. 写入文件之后——运行语法级解析（TMDL 使用 TmdlSerializer；PBIR 使用 JSON 架构验证）。
3. 建议部署之前——运行 BPA 检查（Tabular Editor CLI 或 semantic-link-labs）。
4. 直接报告结果——绝不悄悄忽略验证错误。提供行号、文件路径以及未通过的具体规则。

生成 50 行 TMDL 度量值代码块的有效 Agent 响应，之后应始终附上以下其中一项：

• (a) 用户可以直接粘贴的验证脚本，或
• (b) 如果环境支持，则提供内联 Bash/PowerShell/Python 验证调用。

TMDL 验证——第 1 层（语法解析器）

最快且依赖最少的 TMDL 语法检查方式是 TmdlSerializer.DeserializeDatabaseFromFolder。它会抛出以下异常：

• TmdlFormatException——TMDL 文本存在无效语法（错误的关键字、缩进不正确、表达式格式错误）。其中的 Document、Line 和 LineText 属性指向确切位置。
• TmdlSerializationException——TMDL 文本解析成功，但会生成无效的 TOM 元数据（例如，column 引用了不存在的 dataType，或 partition 引用了未知数据源）。

最简 C# 验证器（.NET 8）：

using Microsoft.AnalysisServices.Tabular;
using Microsoft.AnalysisServices.Tabular.Tmdl;

string folder = args[0];
try
{
    var db = TmdlSerializer.DeserializeDatabaseFromFolder(folder);
    Console.WriteLine($"OK: TMDL parsed. CompatLevel={db.CompatibilityLevel}, Tables={db.Model.Tables.Count}");
    return 0;
}
catch (TmdlFormatException fx)
{
    Console.Error.WriteLine($"SYNTAX ERROR  {fx.Document}:{fx.Line}");
    Console.Error.WriteLine($"  {fx.LineText}");
    Console.Error.WriteLine($"  -> {fx.Message}");
    return 1;
}
catch (TmdlSerializationException sx)
{
    Console.Error.WriteLine($"METADATA ERROR  {sx.Document}:{sx.Line}");
    Console.Error.WriteLine($"  {sx.Message}");
    return 2;
}

通过 Tabular Editor 2 CLI 执行的单行命令（无需 C# 项目）：

# Loads TMDL folder; non-zero exit on parse failure
TabularEditor.exe "MyProject.SemanticModel/definition" -B "MyProject.bim"

-B（bim 输出）开关会强制执行反序列化 + 重新序列化的往返过程。任何解析失败都会以非零状态码退出，并将错误写入 stderr。

如需完整的脚本模式和 Python 等效方案，请参阅 references/tmdl-validation-recipes.md。

TMDL 验证——第 3 层（最佳实践分析器）

最佳实践分析器（BPA）是表格模型反模式检查的权威工具。Tabular Editor 2、Tabular Editor 3、semantic-link-labs 以及 Fabric > Workspace settings > Best Practice Analyzer 使用的是同一套引擎。

Tabular Editor 2 CLI（免费，推荐用于 CI）：

# Run BPA against a TMDL folder using the official Microsoft rule set
TabularEditor.exe "MyProject.SemanticModel/definition" \
  -A "https://raw.githubusercontent.com/TabularEditor/BestPracticeRules/master/BPARules.json" \
  -V \
  -G

# Exit codes:
#   0 = no violations
#   1 = warnings only
#   2 = errors found (any rule with Severity >= 3) -- pipeline should FAIL

对 CI/CD 有用的开关：

开关	用途
-A <rules.json>	使用指定的规则文件（URL 或本地路径）运行 BPA
-V	详细输出（列出每项违规）
-G	GitHub Actions / Azure Pipelines 日志格式（分组区段、文件路径）
-D <conn>	BPA 通过后部署
-S <script>	在 BPA 运行前执行 C# 脚本（自定义验证）

按严重级别触发失败：当 BPA 规则设为 Error（级别 3）时，CLI 会立即停止并以非零状态码退出。对于应阻止 PR 的反模式，请将 BPA 规则设为 Error 严重级别；仅供参考的规则则设为 Warning。

Microsoft 标准规则集：TabularEditor/BestPracticeRules——约 60 条规则，涵盖性能、错误预防、DAX、维护和命名。在 CI 中始终固定到特定提交。

如需完整的 BPA 规则参考（逐条说明所有 Microsoft 规则，以及如何编写自定义规则），请参阅 references/bpa-rules-reference.md。

使用 Python 进行 TMDL 验证（semantic-link-labs）

%pip install semantic-link-labs -q
import sempy_labs as labs

# Run the default BPA against a deployed model
results = labs.run_model_bpa(
    dataset="SalesModel",
    workspace="Sales-Dev",
    extended=True,        # adds VertiPaq Analyzer stats for performance rules
)
results.head(20)

# Run BPA against every model in a workspace and store to delta
labs.run_model_bpa_bulk(
    workspace="Sales-Dev",
    extended=True,
)

# Custom rule set from a JSON file in the lakehouse
my_rules = labs.model_bpa_rules()  # built-in rule definitions
my_rules.append({
    "ID": "AVOID_AUTO_DATE",
    "Name": "Disable auto date/time",
    "Category": "Performance",
    "Severity": 3,
    "Scope": "Model",
    "Expression": "DiscourageImplicitMeasures and not AutoDateTime",
})
labs.run_model_bpa(dataset="SalesModel", rules=my_rules)

semantic-link-labs 是第 3 层的 Python 方案。可在 Fabric 笔记本、定时 BPA 运行或 Spark 管道中使用。完整的 Python 验证指南（包括从本地文件夹离线解析 TMDL）请参阅 references/tmdl-validation-recipes.md。

PBIR 验证——第 1 层（JSON Schema）

每个 PBIR 文件都内嵌了一个 $schema URL，指向 microsoft/json-schemas 中的 Microsoft 官方架构。这意味着可以使用任何 JSON Schema 验证器在本地检查 PBIR 文件的语法。

Python jsonschema 验证器：

import json
import urllib.request
from pathlib import Path
from jsonschema import Draft202012Validator, RefResolver

def validate_pbir_file(pbir_file: Path) -> list[str]:
    doc = json.loads(pbir_file.read_text(encoding="utf-8"))
    schema_url = doc.get("$schema")
    if not schema_url:
        return [f"{pbir_file}: no $schema declared"]

    schema = json.loads(urllib.request.urlopen(schema_url).read())
    validator = Draft202012Validator(schema)
    errors = sorted(validator.iter_errors(doc), key=lambda e: e.path)
    return [f"{pbir_file}#{'/'.join(map(str, e.path))}: {e.message}" for e in errors]

# Walk the entire PBIR folder
report_root = Path("MyProject.Report/definition")
all_errors = []
for f in report_root.rglob("*.json"):
    all_errors.extend(validate_pbir_file(f))

if all_errors:
    print(f"FAIL: {len(all_errors)} schema violations")
    for e in all_errors[:50]:
        print(f"  {e}")
    raise SystemExit(1)
print(f"OK: validated {sum(1 for _ in report_root.rglob('*.json'))} PBIR files")

将架构缓存在本地以便离线执行 CI：先运行一次 git clone https://github.com/microsoft/json-schemas.git，然后让 RefResolver 指向本地副本。这样可以避免 CI 每次构建都发出 1000 多个 HTTP 请求。

PBIR 验证——第 3 层（PBI-InspectorV2 / Fab Inspector）

NatVanG/PBI-InspectorV2（也称为 Fab Inspector）是 PBIR/PBIP 规则验证器的权威实现。v2.3+ 通过 -fabricitem 开关支持所有 Fabric 项目类型（语义模型、报表、笔记本、湖屋），以及新的 PBIR 增强格式（原始的 PBI-Inspector 存储库仅支持 PBIR-Legacy）。

安装（跨平台 .NET 工具）：

# Download the latest release from https://github.com/NatVanG/PBI-InspectorV2/releases
# Or use the published Docker image
docker pull natvang/pbi-inspector-v2:latest

针对 PBIP 文件夹运行：

PBIInspectorCLI \
  -fabricitem "./MyProject.Report" \
  -rules "./pbi-inspector-rules.json" \
  -formats "JSON,HTML,GitHub" \
  -output "./inspector-results"

# Exit codes:
#   0 = all rules passed
#   1 = warnings only
#   2 = at least one Error-severity rule failed

规则格式——从 Base-rules.json 开始并进行自定义。每条规则包含：

• Name（显示名称）
• Description（描述）
• LogType（Error / Warning / Info）
• Disabled（停用规则但不删除）
• Path（指向 PBIR 文件的 JSONPath）
• Test（取值为 isEqualTo、isGreaterThan、isLessThan、mustExist、mustNotExist、regex 等）

每个 PBIR PR 都应强制执行的常见规则：

[
  {
    "Name": "All visuals have a title",
    "LogType": "Error",
    "Path": "$.visual.objects.title[0].properties.show.expr.Literal.Value",
    "Test": "isEqualTo",
    "Expected": "true"
  },
  {
    "Name": "Page count under limit",
    "LogType": "Error",
    "Path": "$.pages",
    "Test": "arrayLengthLessThan",
    "Expected": 1000
  },
  {
    "Name": "Bookmarks reference real pages",
    "LogType": "Error",
    "Path": "$.children[?(@.targetSection)].targetSection",
    "Test": "mustResolveToPage"
  }
]

完整规则示例和 CI 门禁模式见 references/pbir-validation-recipes.md。

Fabric CI/CD、DAX、血缘、CI 门禁和错误目录

关于 fabric-cicd 部署前验证、无需服务器的 DAX 语法验证，以及血缘／交叉引用验证的专项教程见 references/fabric-dax-lineage-validation.md。GitHub Actions CI 门禁模式、常见错误映射和静态验证限制见 references/ci-gates-and-error-catalog.md。

其他资源

参考文件

• references/tmdl-validation-recipes.md——完整的 TMDL 验证指南：TmdlSerializer C# 模式、Python pythonnet 封装、Tabular Editor C# 脚本、INFO DAX 内省、离线解析
• references/pbir-validation-recipes.md——PBIR JSON 架构验证、PBI-InspectorV2 规则示例、血缘交叉引用检查器、GitHub Actions 集成
• references/bpa-rules-reference.md——Microsoft 标准 BPA 规则集摘要、规则编写指南、严重性策略和固定版本指南
• references/fabric-dax-lineage-validation.md——fabric-cicd、DAX 语法和血缘验证教程
• references/ci-gates-and-error-catalog.md——CI 门禁模式、常见验证错误和静态验证限制

相关技能

• powerbi-master:tmdl-mastery——TMDL 语法参考（生成 TMDL 时使用；之后回到此处验证）
• powerbi-master:programmatic-development——PBIR 生成（生成 PBIR 时使用；之后回到此处验证）
• powerbi-master:performance-optimization——通过 DAX Studio、VertiPaq Analyzer、Performance Analyzer 进行运行时验证

2026 年官方参考资料

• TmdlSerializer 类（Microsoft Learn）
• TmdlFormatException 类（Microsoft Learn）
• Tabular Editor BPA 文档
• TabularEditor/BestPracticeRules（Microsoft 官方规则集）
• NatVanG/PBI-InspectorV2（Fab Inspector）
• semantic-link-labs Best Practice Analyzer
• microsoft/json-schemas（PBIR 官方 JSON 架构）
• fabric-cicd 参数化