Introduzione a TMDL

Si applica a: SQL Server 2016 e versioni successive analysis Services Azure Analysis Services Fabric/Power BI Premium

Prima di iniziare a usare questo articolo, assicurarsi di comprendere in modo approfondito i concetti descritti in panoramica di TMDL (Tabular Model Definition Language).

Il modo più semplice per esplorare TMDL consiste nel fare riferimento al pacchetto AMO (Analysis Services Management Objects) pacchetto Nuget e usare i metodi dell'API TMDL per serializzare e deserializzare da e verso TMDL.

Ottenere i pacchetti NuGet

Ottenere una rappresentazione del modello TMDL

L'esempio di codice seguente illustra come ottenere una rappresentazione del modello TMDL di un modello semantico in un'area di lavoro di 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);

}

L'output è una cartella con una rappresentazione TMDL del modello, come illustrato di seguito:

Dopo la serializzazione in una cartella, usare un editor di testo per modificare i file TMDL. Ad esempio, usando Visual Studio Code è possibile aggiungere una nuova misura, [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

Per un'esperienza migliore, è possibile installare estensione del linguaggio TMDL di Visual Studio Code.

Distribuire una rappresentazione del modello TMDL

L'esempio di codice seguente illustra come distribuire una rappresentazione del modello TMDL del modello in un'area di lavoro di 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();
    }               
}

Quando viene eseguita, la nuova misura viene distribuita nel modello.

Gestione degli errori di serializzazione TMDL

Quando viene rilevato un errore nei metodi di serializzazione TMDL, oltre a generare alcune eccezioni .NET comuni come ArgumentException e InvalidOperationException, vengono restituite anche eccezioni specifiche di TMDL.

• TmdlFormatException viene generata se il testo TMDL non è una sintassi valida. Ad esempio, parola chiave o rientro non validi.

• TmdlSerializationException viene generata se il testo TMDL è valido, ma viola la logica dei metadati TOM. Ad esempio, il tipo di valore non corrisponde al tipo previsto.

Oltre ai dettagli delle eccezioni, sono inclusi gli elementi seguenti:

• document path: percorso del file TMDL con errori.
• line number: numero di riga con errori.
• line text: testo della riga con errori.

Esempio di codice che gestisce 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;
}    

Serializzazione del testo oggetto

L'esempio di codice seguente illustra come serializzare una colonna in TMDL:

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

Console.WriteLine(output);

Prodotto:

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

Serializzazione dei flussi

Nell'esempio di codice seguente viene illustrato come serializzare un modello semantico in una singola variabile di testo:

var output = new StringBuilder();

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

Console.WriteLine(output.ToString());

L'esempio di codice seguente illustra come deserializzare da TMDL, escludendo i ruoli:

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