Introducción a TMDL

Se aplica a: SQL Server 2016 y versiones posteriores analysis Services Azure Analysis Services Fabric/Power BI Premium

Importante

El lenguaje de definición de modelos tabulares (TMDL) se encuentra actualmente en versión preliminar. Cuando se encuentra en versión preliminar, es probable que la funcionalidad y la documentación cambien.

Antes de empezar a trabajar con este artículo, asegúrese de comprender exhaustivamente los conceptos descritos en Introducción al lenguaje de definición de modelos tabulares (TMDL).

La manera más fácil de explorar TMDL es hacer referencia al paquete NuGet Objetos de administración de Analysis Services (AMO) y usar los métodos de la API de TMDL para serializar y deserializar hacia y desde TMDL.

Obtención de los paquetes NuGet

Obtención de una representación del modelo TMDL

En el ejemplo de código siguiente se muestra cómo obtener una representación de modelo TMDL de un modelo semántico en un área de trabajo de 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 salida es una carpeta con una representación TMDL del modelo, de la siguiente manera:

Después de serializar en una carpeta, use un editor de texto para editar los archivos TMDL. Por ejemplo, mediante Visual Studio Code podemos agregar una nueva medida, [Importe de ventas (equipos)]:

/// 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 obtener una mejor experiencia, puede instalar Visual Studio Code extensión de lenguaje TMDL.

Implementación de una representación del modelo TMDL

En el ejemplo de código siguiente se muestra cómo implementar una representación de modelo TMDL del modelo en un área de trabajo de 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();
    }               
}

Cuando se ejecuta, la nueva medida se implementa en el modelo.

Control de errores de serialización de TMDL

Cuando se detecta un error en los métodos de serialización TMDL, además de producir algunas excepciones comunes de .NET como ArgumentException y InvalidOperationException, también se devuelven excepciones específicas de TMDL.

• TmdlFormatException se produce si el texto TMDL no es una sintaxis válida. Por ejemplo, palabra clave o sangría no válidas.

• TmdlSerializationException se produce si el texto TMDL es válido, pero infringe la lógica de metadatos de TOM. Por ejemplo, el tipo de valor no coincide con el tipo esperado.

Además de los detalles de la excepción, se incluye lo siguiente:

• document path: ruta de acceso al archivo TMDL con errores.
• line number: número de línea con errores.
• line text: texto de línea con errores.

Ejemplo de código que controla 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;
}    

Serialización de texto de objeto

En el ejemplo de código siguiente se muestra cómo serializar una columna en TMDL:

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

Console.WriteLine(output);

Salida:

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

Serialización de secuencias

En el ejemplo de código siguiente se muestra cómo serializar un modelo semántico en una sola variable 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());

En el ejemplo de código siguiente se muestra cómo deserializar desde TMDL, excepto los roles:

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