Erste Schritte mit TMDL

gilt für: SQL Server 2016 und höher Analysis Services Azure Analysis Services Fabric/Power BI Premium

Bevor Sie mit diesem Artikel beginnen, sollten Sie sich unbedingt mit konzepten vertraut machen, die in Übersicht über tabellarische Modelldefinitionssprache (Tabular Model Definition Language, TMDL) beschrieben.

Die einfachste Möglichkeit zum Erkunden von TMDL besteht darin, auf die Analysis Services Management Objects (AMO) Nuget-Paket zu verweisen und die TMDL-API-Methoden zum Serialisieren und Deserialisieren von und von TMDL zu verwenden.

Abrufen der Nuget-Pakete

Abrufen einer TMDL-Modelldarstellung

Das folgende Codebeispiel zeigt, wie Sie eine TMDL-Modelldarstellung eines semantischen Modells in einem Power BI Premium-Arbeitsbereich abrufen:

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

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

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

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

    Microsoft.AnalysisServices.Tabular.TmdlSerializer.SerializeDatabaseToFolder(database.Model, destinationFolder);

}

Die Ausgabe ist ein Ordner mit einer TMDL-Darstellung des Modells, wie folgt:

Verwenden Sie nach der Serialisierung in einen Ordner einen Text-Editor, um die TMDL-Dateien zu bearbeiten. Beispielsweise können wir mithilfe von Visual Studio Code ein neues Measure hinzufügen, [Verkaufsbetrag (Computer)]:

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

Um eine bessere Benutzererfahrung zu erzielen, können Sie Visual Studio Code TMDL-Spracherweiterunginstallieren.

Bereitstellen einer TMDL-Modelldarstellung

Das folgende Codebeispiel zeigt, wie Sie eine TMDL-Modelldarstellung des Modells in einem Power BI Premium-Arbeitsbereich bereitstellen:

var xmlaServer = "<Workspace XMLA address>";

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

var model = Microsoft.AnalysisServices.Tabular.TmdlSerializer.DeserializeModelFromFolder(tmdlFolderPath);            

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

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

        remoteDatabase.Model.SaveChanges();
    }               
}

Bei Ausführung wird das neue Measure für das Modell bereitgestellt.

Behandeln von TMDL-Serialisierungsfehlern

Wenn in TMDL-Serialisierungsmethoden ein Fehler erkannt wird, werden neben dem Auslösen einiger gängiger .NET-Ausnahmen wie ArgumentException und InvalidOperationExceptionauch TMDL-spezifische Ausnahmen zurückgegeben.

• TmdlFormatException wird ausgelöst, wenn der TMDL-Text keine gültige Syntax ist. Beispiel: Ungültiges Schlüsselwort oder Einzug.

• TmdlSerializationException wird ausgelöst, wenn der TMDL-Text gültig ist, jedoch gegen die TOM-Metadatenlogik verstößt. Der Typ des Werts stimmt z. B. nicht mit dem erwarteten Typ überein.

Zusätzlich zu Ausnahmedetails ist Folgendes enthalten:

• document path: Pfad zur TMDL-Datei mit Fehlern.
• line number: Zeilennummer mit Fehlern.
• line text: Zeilentext mit Fehlern.

Codebeispiel für die Behandlung von TmdlFormatException:

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

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

    throw;
}    

Serialisierung des Objekttexts

Das folgende Codebeispiel zeigt, wie Sie eine Spalte in TMDL serialisieren:

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

Console.WriteLine(output);

Ausgabe:

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

Stream serialisierung

Das folgende Codebeispiel zeigt, wie Sie ein Semantikmodell in eine einzelne Textvariable serialisieren:

var output = new StringBuilder();

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

Console.WriteLine(output.ToString());

Im folgenden Codebeispiel wird gezeigt, wie Sie aus TMDL deserialisieren, mit Ausnahme der Rollen:

var context = Microsoft.AnalysisServices.Tabular.Serialization.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();