Introdução ao TMDL
Aplica-se a: SQL Server 2016 e posteriores do Analysis Services
Azure Analysis Services
Fabric/Power BI Premium
Importante
A TMDL (Linguagem de Definição de Modelo tabular) está atualmente em versão prévia. Durante a versão prévia, a funcionalidade e a documentação podem ser alteradas.
Antes de começar a usar este artigo, lembre-se de entender completamente os conceitos descritos em Visão geral da TMDL (Linguagem de Definição de Modelo Tabular).
A maneira mais fácil de explorar o TMDL é referenciar o pacote Nuget AMO (Objetos de Gerenciamento do Analysis Services) e usar os métodos da API TMDL para serializar e desserializar de e para TMDL.
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 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);
}
A saída é uma pasta com uma representação TMDL do modelo, desta forma:
Após a serialização em uma pasta, use um editor de texto para editar os arquivos TMDL. Por exemplo, usando 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 Visual Studio Code extensão de linguagem TMDL.
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 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 executada, a nova medida é implantada no modelo.
Tratamento de erros de serialização 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á gerado se o texto TMDL não for uma sintaxe válida. Por exemplo, palavra-chave ou recuo inválidos.TmdlSerializationException
será gerado 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 TmdlFormatException
código:
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;
}
Serialização de texto do objeto
O exemplo de código a seguir mostra como serializar uma coluna em TMDL:
var output = 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 para uma única variável de texto:
var output = new StringBuilder();
foreach (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 = 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();
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de