/c-sharp-scripting

name: c-sharp-scripting
description: Writing and executing C# scripts and macros against Power BI semantic models using Tabular Editor 2/3. Automatically invoke when the user mentions "C# script", "Tabular Editor script", "TOM scripting", "MacroActions.json", "XMLA", or asks to "automate model changes", "bulk update measures", "create calculation groups", "write a macro", "format DAX expressions", "manage model metadata".

C# Scripting for Tabular Editor

Expert guidance for writing and executing C# scripts to manipulate Power BI semantic model metadata using Tabular Editor 2/3 CLI or the Tabular Editor IDE.

When to Use This Skill

Activate automatically when tasks involve:

• Writing C# scripts for Tabular Editor
• Bulk operations on model objects (measures, columns, tables)
• Creating or modifying calculation groups
• Managing model security (roles, RLS, OLS)
• Formatting DAX expressions
• Automating repetitive model changes
• Querying model metadata via TOM API
• Building interactive scripts with user input dialogs

Critical

• Every statement must end with `;` (semicolon required by C#)
• Use double quotes `"` for strings and escape with `\` when needed
• Use forward slashes `/` in DisplayFolder paths (auto-converted to `\`)
• Always add `Info()` statements for debugging - script stops at error point
• Test scripts on non-production models first
• Changes are undoable with Ctrl+Z in the Tabular Editor UI

C# Version Support

| Environment | C# Version | Notes | |-------------|------------|-------| | **Tabular Editor 2** | Default compiler | Older C# syntax | | **Tabular Editor 3** | Roslyn | Supports up to C# 12 with VS2022 | | **TE2 with Roslyn** | Configurable | Set in File > Preferences > General |

To use newer C# features in TE2, configure Roslyn compiler path in preferences.

Default Imports and Assemblies

Auto-Imported Namespaces

Scripts automatically have these `using` statements applied:

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

Pre-Loaded Assemblies

These .NET assemblies are loaded by default:

• `System.Dll`
• `System.Core.Dll`
• `System.Data.Dll`
• `System.Windows.Forms.Dll` (for UI dialogs)
• `Microsoft.Csharp.Dll`
• `Newtonsoft.Json.Dll`
• `TomWrapper.Dll`
• `TabularEditor.Exe`
• `Microsoft.AnalysisServices.Tabular.Dll`

Adding External Assemblies

// 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;

Prerequisites

For Tabular Editor CLI

| Requirement | Description | |-------------|-------------| | **Tabular Editor 2 CLI** | Download from [GitHub releases](https://github.com/TabularEditor/TabularEditor/releases) | | **XMLA Read/Write** | Enabled on Fabric capacity or Power BI Premium | | **Azure Service Principal** | For XMLA connections (see authentication.md) |

Environment Variables (for XMLA)

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

Execution Methods

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. Connection Types

| Type | Format | Example | |------|--------|---------| | **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"` |

Core Objects

The `Model` Object

Access any object in the loaded 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

The `Selected` Object

Access objects currently selected in the TOM Explorer (IDE only):

// 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");

When a Display Folder is selected, all child items are included in the selection.

LINQ Fundamentals

LINQ is essential for filtering and transforming TOM collections. See **`references/linq-reference.md`** for the full method table, lambda syntax, and examples.

Key methods: `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))