Introdução ao TMDL

aplica-se a: SQL Server 2016 e posteriores do Analysis Services Fabric/Power BI Premium do Azure Analysis Services

Antes de começar a usar este artigo, lembre-se de entender completamente os conceitos descritos em visão geral da TMDL (Tabular Model Definition Language).

A maneira mais fácil de explorar o TMDL é referenciar o AMO (Objetos de Gerenciamento) do Analysis Services pacote Nuget e usar os métodos da API TMDL para serializar e desserializar de e para TMDL.

Obter os pacotes Nuget

Obter uma representação de modelo TMDL

O exemplo de código a seguir mostra como obter uma representação de modelo TMDL de um modelo semântico em um workspace do 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);

}

A saída é uma pasta com uma representação TMDL do modelo, desta forma:

Pasta

Após a serialização em uma pasta, use um editor de texto para editar os arquivos TMDL. Por exemplo, usando o Visual Studio Code, podemos adicionar uma nova medida, [Valor de Vendas (Computadores)]:

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

Para obter uma experiência melhor, você pode instalar de extensão de linguagem TMDL do Visual Studio Code.

Implantar uma representação de modelo TMDL

O exemplo de código a seguir mostra como implantar uma representação de modelo TMDL do modelo em um workspace do 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();
    }               
}

Quando executada, a nova medida é implantada no modelo.

Medida

Manipulando erros de serialização de TMDL

Quando um erro é detectado em métodos de serialização TMDL, além de gerar algumas exceções comuns do .NET, como ArgumentException e InvalidOperationException, exceções específicas de TMDL também são retornadas.

• TmdlFormatException será gerada se o texto TMDL não for uma sintaxe válida. Por exemplo, palavra-chave ou recuo inválido.

• TmdlSerializationException será gerada se o texto TMDL for válido, mas violar a lógica de metadados TOM. Por exemplo, o tipo de valor não corresponde ao tipo esperado.

Além dos detalhes da exceção, o seguinte está incluído:

• document path: caminho para o arquivo TMDL com erros.
• line number: número de linha com erros.
• line text: texto de linha com erros.

Tratamento de exemplo de código 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;
}    

Serialização de texto do objeto

O exemplo de código a seguir mostra como serializar uma coluna em TMDL:

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

Console.WriteLine(output);

Saída:

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

Serialização de fluxo

O exemplo de código a seguir mostra como serializar um modelo semântico em uma única variável de texto:

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

O exemplo de código a seguir mostra como desserializar do TMDL, excluindo as funções:

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