開始使用 TMDL

發行項
01/04/2024

適用于：SQL Server 2016 和更新版本的 Analysis Services Azure Analysis Services Fabric/Power BI Premium

重要

表格式模型定義語言 (TMDL) 目前為預覽狀態。預覽版時，功能和檔可能會變更。

開始使用本文之前，請務必徹底瞭解表格式模型定義語言 (TMDL) 概觀中所述的概念。

探索 TMDL 的最簡單方式是參考 AMO) Nuget 套件 (Analysis Services 管理物件，並使用 TMDL API 方法來序列化和還原序列化到 TMDL。

取得 Nuget 套件

取得 TMDL 模型標記法

下列程式碼範例示範如何在 Power BI Premium 工作區中取得語意模型的 TMDL 模型標記法：

var workspaceXmla = " <Workspace XMLA address>";
var datasetName = "<dataset name>";
var outputPath = System.Environment.CurrentDirectory;

using (var server = new Server())
{
    server.Connect(workspaceXmla);

    var database = server.Databases.GetByName(datasetName);

    var destinationFolder = $"{outputPath}\\{database.Name}-tmdl";

    TmdlSerializer.SerializeDatabaseToFolder(database.Model, destinationFolder);

}

輸出是具有模型 TMDL 標記法的資料夾，如下所示：

具有模型 TMDL 標記法的資料夾

序列化至資料夾之後，請使用文字編輯器來編輯 TMDL 檔案。例如，使用 Visual Studio Code我們可以新增量值[Sales Amount (Computers) ]：

/// Sales data for year over year analysis
table Sales        

    partition 'Sales-Part1' = m
        mode: Import        
        source =
            let
                …
            in
                #"Filtered Rows1"

    measure 'Sales Amount' = SUMX('Sales', [Quantity] * [Net Price])
        formatString: $ #,##0

    measure 'Sales Amount (Computers)' = CALCULATE([Sales Amount], 'Product'[Category] = "Computers")
        formatString: $ #,##0

為了獲得更好的體驗，您可以安裝Visual Studio Code TMDL 語言延伸模組。

部署 TMDL 模型標記法

下列程式碼範例示範如何將模型的 TMDL 模型標記法部署到Power BI Premium工作區：

var xmlaServer = "<Workspace XMLA address>";

var tmdlFolderPath = $"{System.Environment.CurrentDirectory}\\Contoso-tmdl";

var model = TmdlSerializer.DeserializeDatabaseFromFolder(tmdlFolderPath);            

using (var server = new Server())
{
    server.Connect(xmlaServer);

    using (var remoteDatabase = server.Databases[model.Database.ID])
    {
        model.CopyTo(remoteDatabase.Model);

        remoteDatabase.Model.SaveChanges();
    }               
}

執行時，新的量值會部署到模型。

Sales Amount (Computers) measure in dataset

處理 TMDL 序列化錯誤

在 TMDL 序列化方法中偵測到錯誤時，除了擲回一些常見的 .NET 例外狀況，例如 ArgumentException 和 InvalidOperationException 之外，也會傳回 TMDL 特定的例外狀況。

TmdlFormatException 如果 TMDL 文字不是有效的語法，則會擲回。例如，不正確關鍵字或縮排。
TmdlSerializationException 如果 TMDL 文字有效，但違反 TOM 中繼資料邏輯，則會擲回。例如，值的類型不符合預期的類型。

除了例外狀況詳細資料之外，還包含下列專案：

document path：TMDL 檔案的路徑，發生錯誤。
line number：有錯誤的行號。
line text：含有錯誤的行文字。

程式碼範例處理 TmdlFormatException ：

try
{
    var tmdlPath = "<TMDL Folder Path>";

    var model = TmdlSerializer.DeserializeDatabaseFromFolder(tmdlPath);
}
catch (TmdlFormatException ex)
{
    Console.WriteLine($"Error on Deserializing TMDL '{ex.Message}', document path: '{ex.Document}'  line number: '{ex.Line}', line text: '{ex.LineText}'");

    throw;
}

物件文字序列化

下列程式碼範例示範如何將資料行序列化為 TMDL：


var output = TmdlSerializer.SerializeObject(model.Tables["Product"].Columns["ProductKey"], qualifyObject: true);

Console.WriteLine(output);

輸出：

ref table Product

 column ProductKey
  dataType: int64
  isKey
  formatString: 0
  isAvailableInMdx: false
  lineageTag: 4184d53e-cd2d-4cbe-b8cb-04c72a750bc4
  summarizeBy: none
  sourceColumn: ProductKey

  annotation SummarizationSetBy = Automatic

串流序列化

下列程式碼範例示範如何將語意模型序列化為單一文字變數：

var output = new StringBuilder();

foreach (MetadataDocument document in model.ToTmdl())
{
    using (TextWriter writer = new StringWriter(output))
    {
        document.WriteTo(writer);
    }
}

Console.WriteLine(output.ToString());

下列程式碼範例示範如何從 TMDL 還原序列化，但不包括角色：

var context = MetadataSerializationContext.Create(MetadataSerializationStyle.Tmdl);

var files = Directory.GetFiles("[TMDL Directory Path]", "*.tmdl", SearchOption.AllDirectories);

foreach (var file in files)
{
    if (file.Contains("/roles/"))
        continue;

    using (TextReader reader = File.OpenText(file))
    {                    
        context.ReadFromDocument(file, reader);
    }
}

var model = context.ToModel();

共用方式為