Bien démarrer avec TMDL

S’applique à : SQL Server 2016 et versions ultérieures Analysis Services Azure Analysis Services Fabric/Power BI Premium

Important

Le langage TMDL (Tabular Model Definition Language) est actuellement en préversion. Pendant la période de préversion, les fonctionnalités et la documentation sont susceptibles de changer.

Avant de commencer à utiliser cet article, veillez à bien comprendre les concepts décrits dans Vue d’ensemble du langage TMDL (Tabular Model Definition Language).

Le moyen le plus simple d’explorer TMDL consiste à référencer le package Nuget Analysis Services Management Objects (AMO) et à utiliser les méthodes d’API TMDL pour sérialiser et désérialiser vers et depuis TMDL.

Obtenir les packages Nuget

Obtenir une représentation de modèle TMDL

L’exemple de code suivant montre comment obtenir une représentation de modèle TMDL d’un modèle sémantique dans un espace de travail 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);

}

La sortie est un dossier avec une représentation TMDL du modèle, comme suit :

Après la sérialisation dans un dossier, utilisez un éditeur de texte pour modifier les fichiers TMDL. Par exemple, à l’aide de Visual Studio Code, nous pouvons ajouter une nouvelle mesure, [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

Pour une meilleure expérience, vous pouvez installer l’extension de langage TMDL Visual Studio Code.

Déployer une représentation de modèle TMDL

L’exemple de code suivant montre comment déployer une représentation de modèle TMDL du modèle dans un espace de travail 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();
    }               
}

Une fois exécutée, la nouvelle mesure est déployée sur le modèle.

Gestion des erreurs de sérialisation TMDL

Lorsqu’une erreur est détectée dans les méthodes de sérialisation TMDL, en plus de lever quelques exceptions .NET courantes telles que ArgumentException et InvalidOperationException, des exceptions spécifiques à TMDL sont également retournées.

• TmdlFormatException est levée si le texte TMDL n’est pas une syntaxe valide. Par exemple, mot clé ou mise en retrait non valides.

• TmdlSerializationException est levée si le texte TMDL est valide, mais viole la logique des métadonnées TOM. Par exemple, le type de valeur ne correspond pas au type attendu.

Outre les détails de l’exception, les éléments suivants sont inclus :

• document path: chemin d’accès au fichier TMDL avec des erreurs.
• line number: numéro de ligne avec des erreurs.
• line text: texte de ligne contenant des erreurs.

Exemple de code de gestion 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;
}    

Sérialisation du texte d’objet

L’exemple de code suivant montre comment sérialiser une colonne dans TMDL :

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

Console.WriteLine(output);

Sortie :

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

Sérialisation de flux

L’exemple de code suivant montre comment sérialiser un modèle sémantique sur une variable de texte unique :

var output = new StringBuilder();

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

Console.WriteLine(output.ToString());

L’exemple de code suivant montre comment désérialiser à partir de TMDL, à l’exclusion des rôles :

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