c-sharp-scripting

Tabular Editor 的 C# 脚本编写

关于如何使用 Tabular Editor 2/3 CLI 或 Tabular Editor IDE 编写和执行 C# 脚本，以操作 Power BI 语义模型元数据的专家指南。

何时使用此技能

当任务涉及以下内容时，自动启用：

• 为 Tabular Editor 编写 C# 脚本
• 对模型对象（度量值、列、表）执行批量操作
• 创建或修改计算组
• 管理模型安全性（角色、RLS、OLS）
• 格式化 DAX 表达式
• 自动执行重复的模型更改
• 通过 TOM API 查询模型元数据
• 构建带有用户输入对话框的交互式脚本

重要提示

• 每条语句都必须以 ; 结尾（C# 要求使用分号）
• 字符串使用双引号 "，必要时用 \ 转义
• DisplayFolder 路径使用正斜杠 /（会自动转换为 \）
• 始终添加 Info() 语句以进行调试——脚本会在出错处停止
• 先在非生产模型上测试脚本
• 在 Tabular Editor UI 中可使用 Ctrl+Z 撤销更改

C# 版本支持

环境	C# 版本	备注
Tabular Editor 2	默认编译器	较旧的 C# 语法
Tabular Editor 3	Roslyn	使用 VS2022 时最高支持 C# 12
TE2 with Roslyn	可配置	在 File > Preferences > General 中设置

要在 TE2 中使用较新的 C# 功能，请在首选项中配置 Roslyn 编译器路径。

默认导入和程序集

自动导入的命名空间

脚本会自动应用以下 using 语句：

using System;
using System.Linq;
using System.Collections.Generic;
using Newtonsoft.Json;
using TabularEditor.TOMWrapper;
using TabularEditor.TOMWrapper.Utils;
using TabularEditor.UI;

预加载的程序集

以下 .NET 程序集默认已加载：

• System.Dll
• System.Core.Dll
• System.Data.Dll
• System.Windows.Forms.Dll（用于 UI 对话框）
• Microsoft.Csharp.Dll
• Newtonsoft.Json.Dll
• TomWrapper.Dll
• TabularEditor.Exe
• Microsoft.AnalysisServices.Tabular.Dll

添加外部程序集

// Assembly references must be at the very top of the file:
#r "System.IO.Compression"
#r "System.Drawing"

// Using statements come after assembly references:
using System.IO.Compression;
using System.Drawing;

先决条件

使用 Tabular Editor CLI

要求	说明
Tabular Editor 2 CLI	从 GitHub releases 下载
XMLA Read/Write	在 Fabric 容量或 Power BI Premium 上启用
Azure Service Principal	用于 XMLA 连接（参见 authentication.md）

环境变量（用于 XMLA）

AZURE_CLIENT_ID=<app-id>
AZURE_TENANT_ID=<tenant-id>
AZURE_CLIENT_SECRET=<secret>

执行方式

1. Tabular Editor CLI

# Inline script
TabularEditor.exe "WorkspaceName/ModelName" -S "Info(Model.Database.Name);"

# Script file
TabularEditor.exe "WorkspaceName/ModelName" -S "script.csx"

2. 连接类型

类型	格式	示例
XMLA	workspace/model	"Sales WS/Sales Model"
Local BIM	path/to/model.bim	"./model.bim"
Local TMDL	path/to/definition/	"./MyModel.SemanticModel/definition/"
PBI Desktop	localhost:PORT	"localhost:52123"

核心对象

Model 对象

访问已加载的表格模型中的任意对象：

Model                           // Root model object
Model.Tables                    // All tables
Model.Tables["Sales"]           // Specific table
Model.AllMeasures               // All measures across all tables
Model.AllColumns                // All columns across all tables
Model.Relationships             // All relationships
Model.Roles                     // All security roles
Model.CalculationGroups         // All calculation groups
Model.Perspectives              // All perspectives
Model.Cultures                  // All translations/cultures
Model.Expressions               // All M expressions (shared queries)
Model.DataSources               // All data sources

Selected 对象

访问 TOM Explorer 中当前选中的对象（仅限 IDE）：

// Plural form - collections (safe even when empty)
Selected.Tables                 // Selected tables
Selected.Measures               // Selected measures
Selected.Columns                // Selected columns
Selected.Hierarchies            // Selected hierarchies

// Singular form - single object (error if not exactly one selected)
Selected.Table                  // The single selected table
Selected.Measure                // The single selected measure
Selected.Column                 // The single selected column

// Set properties on multiple objects at once
Selected.Measures.DisplayFolder = "Test";
Selected.Columns.IsHidden = true;

// Bulk rename with pattern
Selected.Measures.Rename("Amount", "Value");

选中 Display Folder 时，所有子项都会包含在所选内容中。

LINQ 基础

LINQ 对筛选和转换 TOM 集合至关重要。完整的方法表、Lambda 语法和示例，请参阅 references/linq-reference.md。

常用方法：Where()、First()、FirstOrDefault()、Any()、All()、Count()、Select()、OrderBy()、ForEach()、ToList()。

// Common pattern: filter, chain, act
Model.AllMeasures
    .Where(m => m.Name.Contains("Revenue"))
    .Where(m => string.IsNullOrEmpty(m.FormatString))
    .ForEach(m => m.FormatString = "$#,0");

辅助方法

完整参考文档请参阅 references/helper-methods.md，其中包括 Output() 的各种用法、文件操作、属性导出/导入、交互式选择对话框、DAX 格式化/执行以及宏调用。

方法	用途
Info(message)	显示信息弹窗（CLI：写入控制台）
Warning(message)	显示警告弹窗
Error(message)	显示错误弹窗并停止脚本
Output(object)	显示详细的对象检查器对话框
SaveFile(path, content) / ReadFile(path)	文件 I/O
ExportProperties() / ImportProperties()	TSV 导出/导入
SelectMeasure() / SelectTable()	交互式选择（仅 IDE）
FormatDax() / CallDaxFormatter()	DAX 格式化
EvaluateDax() / ExecuteDax()	DAX 执行（已连接）

WinForms UI 模式

如需了解交互式对话框（输入表单、下拉列表、多选），请参阅 references/winforms-dialogs.md。关键设置：#r "System.Drawing"、ScriptHelper.WaitFormVisible = false;

快速参考

核心模式

添加度量值：

var m = Model.Tables["Sales"].AddMeasure("Total Revenue", "SUM(Sales[Amount])");
m.FormatString = "$#,0";
m.DisplayFolder = "Key Metrics";
m.Description = "Total sales revenue";
Info("Added: " + m.Name);

遍历表/列：

foreach(var t in Model.Tables) {
    foreach(var c in t.Columns.Where(c => c.Name.EndsWith("Key"))) {
        c.IsHidden = true;
    }
}
Info("Hidden key columns");

条件操作：

foreach(var m in Model.AllMeasures) {
    if(m.Name.Contains("Revenue")) m.FormatString = "$#,0";
    if(m.Name.Contains("Rate")) m.FormatString = "0.00%";
}

创建计算组：

var cg = Model.AddCalculationGroup("Time Intelligence");
cg.Precedence = 10;

var ytd = cg.AddCalculationItem("YTD", "CALCULATE(SELECTEDMEASURE(), DATESYTD('Date'[Date]))");
var prior = cg.AddCalculationItem("Prior Year");
prior.Expression = @"
CALCULATE(
    SELECTEDMEASURE(),
    DATEADD('Date'[Date], -1, YEAR)
)
";
Info("Created calculation group");

TOM API 快速参考

对象	访问方式	常用属性
模型	Model	.Tables、.AllMeasures、.Relationships
表	Model.Tables["Name"]	.Measures、.Columns、.Partitions、.IsHidden
度量值	Table.Measures["Name"]	.Expression、.FormatString、.DisplayFolder、.Description
列	Table.Columns["Name"]	.DataType、.FormatString、.IsHidden、.SummarizeBy
关系	Model.Relationships	.FromTable、.ToTable、.IsActive、.CrossFilteringBehavior
角色	Model.Roles["Name"]	.Members、.TablePermissions
层次结构	Table.Hierarchies	.Levels、.DisplayFolder、.IsHidden
分区	Table.Partitions	.Expression、.SourceType、.DataSource
透视	Model.Perspectives	对象具有 .InPerspective["Name"]
区域设置	Model.Cultures	对象具有 .TranslatedNames["culture"]

对象类型参考

object-types/ 中提供了各对象类型的详细文档：

• tables.md - 表的 CRUD、属性、分区
• columns.md - 列类型、属性、排序
• measures.md - 度量值创建、格式化、组织
• relationships.md - 关系管理
• calculation-groups.md - 计算组和项
• roles.md - 角色、RLS、OLS 配置
• hierarchies.md - 层次结构和级别管理
• partitions.md - 分区类型和配置
• perspectives.md - 透视成员关系
• translations.md - 区域设置和翻译管理
• annotations.md - 自定义元数据注释

示例脚本

examples/ 中按类别整理了 180 个可运行的 .csx 脚本。动手从头编写脚本前，先检查是否已有相关示例——阅读示例，根据任务进行调整，并按需修改。

类别	脚本数	描述
bulk-operations/	8	模型初始化、批量更新、清理名称、同步文件夹、验证
calculation-groups/	2	时间智能、货币转换
columns/	20	数据类型、隐藏、排序、编码提示、基数、属性
cultures/	4	添加/删除区域性设置、列出、修改翻译
display-folders/	8	按类型整理、清空、重命名、添加/移除文件夹
evaluate-dax/	5	执行 DAX、标量查询、表查询、列大小、优化
format-dax/	8	格式化度量值、计算列/表、KPI、详细信息行
format-strings/	6	按名称/模式应用、自定义格式、动态格式字符串
functions/	4	添加/删除/列出/修改共享 M 函数
hierarchies/	4	添加/删除/列出/修改层次结构
kpis/	4	添加/删除/列出/修改 KPI
measures/	18	完整的 CRUD、时间智能、批量创建、移动、隐藏/取消隐藏
model/	10	属性、兼容性级别、依赖项、刷新、导出统计信息
partitions/	6	刷新、M 查找替换、增量刷新、混合表
perspectives/	4	添加/删除/列出/修改透视
relationships/	5	创建、命名约定、RI 违规、完整性、属性
roles/	7	添加/删除角色、成员、RLS、OLS 配置
shared-expressions/	6	命名表达式、范围参数、M 函数
svg-measures/	15	条形图、子弹图、哑铃图、棒棒糖图、瀑布图、抖动图
tables/	36	所有表类型（导入、DirectQuery、Direct Lake、计算、字段参数、日期）、刷新策略、RLS/OLS、属性

常见工作流

请参阅 references/common-workflows.md，获取完整的工作流脚本：批量格式化度量值、创建时间智能度量值、配置 RLS、审计隐藏对象。从头编写前，也请查看 examples/ 中的 180 个可运行 .csx 脚本。

调试与故障排除

脚本未完成

添加 Info() 检查点，以找到脚本失败的位置：

Info("Step 1: Starting");
var table = Model.Tables["Sales"];
Info("Step 2: Got table");
var measure = table.AddMeasure("Test", "1");
Info("Step 3: Added measure");  // If this doesn't appear, AddMeasure failed

找不到对象

访问前检查对象是否存在：

if(Model.Tables.Contains("Sales")) {
    var table = Model.Tables["Sales"];
    // ...
} else {
    Error("Table 'Sales' not found");
}

// Or use FirstOrDefault
var table = Model.Tables.FirstOrDefault(t => t.Name == "Sales");
if(table == null) {
    Error("Table not found");
}

更改未显示

• XMLA 操作可能需要 2-5 秒才能同步
• 更改后刷新 Power BI Desktop 连接
• 检查是否存在静默错误（在每项操作后添加 Info()）

TE2/TE3 兼容性

对特定版本的代码使用预处理器指令：

#if TE3
    // TE3-specific code (version 3.10.0+)
    Info("Running in Tabular Editor 3");
#else
    // TE2 fallback
    Info("Running in Tabular Editor 2");
#endif

在运行时检查版本：

var majorVersion = Selected.GetType().Assembly.GetName().Version.Major;
if(majorVersion >= 3) {
    // TE3 code
}

最佳实践

1. 添加 Info() 语句 - 跟踪脚本执行情况并尽早发现错误
2. 检查对象是否存在 - 访问前使用 .Contains() 或 .Any()
3. 使用批量操作 - 使用循环的单个脚本比多个脚本更快
4. 在开发模型上测试 - 切勿在生产环境中测试新脚本
5. 对 DAX 使用 @"..." - 使用多行字符串编写 DAX 表达式
6. 使用 FormatDax() 格式化 - 创建度量值/列后进行格式化
7. 使用 / 设置 DisplayFolder - 正斜杠会自动转换为反斜杠
8. 隐藏等待旋转指示器 - 对于 UI 对话框，使用 ScriptHelper.WaitFormVisible = false;

其他资源

参考文件

• object-types/ - 各对象类型的详细 API 文档
• examples/ - 涵盖 20 个类别的 180 个可运行 .csx 脚本；从头编写前务必先查看

获取文档

如需检索最新的 TOM API 参考文档，如果可用，请使用 microsoft_docs_search + microsoft_docs_fetch（MCP）；否则使用 mslearn search + mslearn fetch（CLI）。根据用户的请求进行搜索，并按需执行多次搜索，以确保在继续操作前获得足够的上下文。

外部参考资料

• Tabular Editor 高级脚本
• TOM API 参考
• C# 脚本和宏
• 脚本库