c-sharp-scripting

Tabular Editor 向け C# スクリプト

Tabular Editor 2/3 CLI または Tabular Editor IDE を使用して、Power BI セマンティックモデルのメタデータを操作する C# スクリプトの作成と実行に関する専門的なガイダンスです。

このスキルを使用するタイミング

次のタスクに関係する場合、自動的に有効になります。

• 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"
ローカル BIM	path/to/model.bim	"./model.bim"
ローカル TMDL	path/to/definition/	"./MyModel.SemanticModel/definition/"
PBI Desktop	localhost:PORT	"localhost:52123"

コアオブジェクト

Model オブジェクト

読み込まれた Tabular 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 コレクションのフィルター処理と変換に不可欠です。メソッド一覧、ラムダ構文、使用例の全容については、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");

ヘルパーメソッド

Output() の各種バリエーション、ファイル操作、プロパティのエクスポート／インポート、対話型選択ダイアログ、DAX の書式設定／実行、マクロの呼び出しを含む完全なリファレンスについては、references/helper-methods.md を参照してください。

メソッド	用途
Info(message)	情報ポップアップを表示します（CLI：コンソールに出力します）
Warning(message)	警告ポップアップを表示します
Error(message)	エラーポップアップを表示し、スクリプトを停止します
Output(object)	オブジェクトの詳細インスペクター ダイアログを表示します
SaveFile(path, content) / ReadFile(path)	ファイルの入出力
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 Advanced Scripting
• TOM API リファレンス
• C# スクリプトとマクロ
• スクリプトライブラリ