Bien démarrer avec TMDL

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

Avant de commencer avec cet article, veillez à bien comprendre les concepts décrits dans vue d’ensemble de TMDL (Tabulaire Model Definition Language).

Le moyen le plus simple d’explorer TMDL consiste à référencer les objets AMO (Analysis Services Management Objects) package Nuget 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 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);

}

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 '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 sur un espace de travail Power BI Premium :

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

Lorsqu’elle est 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, les 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 retrait non valide.

• TmdlSerializationException est levée si le texte TMDL est valide, mais enfreint la logique de 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 avec des erreurs.

Exemple de code gérant 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;
}    

Sérialisation du texte de l’objet

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

var output = Microsoft.AnalysisServices.Tabular.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 vers une variable de texte unique :

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

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

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