Mulai menggunakan TMDL

Berlaku untuk: SQL Server 2016 dan yang lebih baru Analysis Services Azure Analysis Services Fabric/Power BI Premium

Penting

Bahasa Definisi Model Tabular (TMDL) saat ini dalam pratinjau. Saat dalam pratinjau, fungsionalitas dan dokumentasi cenderung berubah.

Sebelum memulai artikel ini, pastikan untuk memahami konsep yang dijelaskan dalam gambaran umum Tabular Model Definition Language (TMDL) secara menyeluruh.

Cara termampu untuk menjelajahi TMDL adalah dengan mereferensikan paket Nuget Analysis Services Management Objects (AMO) dan menggunakan metode TMDL API untuk membuat serialisasi dan deserialisasi ke dan dari TMDL.

Mendapatkan paket Nuget

Mendapatkan representasi model TMDL

Contoh kode berikut menunjukkan cara mendapatkan representasi model TMDL dari model semantik di ruang kerja Power BI Premium:

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

}

Output adalah folder dengan representasi TMDL dari model, seperti ini:

Setelah serialisasi ke dalam folder, gunakan editor teks untuk mengedit file TMDL. Misalnya, dengan menggunakan Visual Studio Code kita dapat menambahkan ukuran baru, [Jumlah Penjualan (Komputer)]:

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

Untuk pengalaman yang lebih baik, Anda dapat menginstal ekstensi bahasa Visual Studio Code TMDL.

Menyebarkan representasi model TMDL

Contoh kode berikut menunjukkan cara menyebarkan representasi model TMDL dari model ke ruang kerja 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();
    }               
}

Saat dijalankan, ukuran baru disebarkan ke model.

Menangani kesalahan serialisasi TMDL

Ketika kesalahan terdeteksi dalam metode serialisasi TMDL, selain melemparkan beberapa pengecualian .NET umum seperti ArgumentException dan InvalidOperationException, pengecualian khusus TMDL juga dikembalikan.

• TmdlFormatException dilemparkan jika teks TMDL bukan sintaks yang valid. Misalnya, kata kunci atau indentasi yang tidak valid.

• TmdlSerializationException dilemparkan jika teks TMDL valid, tetapi melanggar logika metadata TOM. Misalnya, jenis nilai tidak cocok dengan jenis yang diharapkan.

Selain detail pengecualian, berikut ini disertakan:

• document path: Jalur ke file TMDL dengan kesalahan.
• line number: nomor baris dengan kesalahan.
• line text: teks baris dengan kesalahan.

Contoh kode penanganan 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;
}    

Serialisasi teks objek

Contoh kode berikut menunjukkan cara membuat serialisasi kolom ke dalam TMDL:

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

Console.WriteLine(output);

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

Serialisasi aliran

Contoh kode berikut menunjukkan cara membuat serial model semantik ke variabel teks tunggal:

var output = new StringBuilder();

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

Console.WriteLine(output.ToString());

Contoh kode berikut menunjukkan cara mendeserialisasi dari TMDL, tidak termasuk peran:

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();