Начало работы с TMDL

Применимо к: SQL Server 2016 и более поздних версий Analysis Services Azure Analysis Services Fabric/Power BI Premium

Важно!

Язык определения табличных моделей (TMDL) в настоящее время находится на этапе предварительной версии. Функциональные возможности и документация в предварительной версии с высокой вероятностью могут изменяться.

Прежде чем приступить к работе с этой статьей, обязательно изучите основные понятия, описанные в обзоре языка определения табличных моделей (TMDL).

Самый простой способ изучить TMDL — сослаться на пакет NuGet для управляющих объектов Analysis Services (AMO) и использовать методы API TMDL для сериализации и десериализации в TMDL и из TMDL.

Получение пакетов NuGet

Получение представления модели TMDL

В следующем примере кода показано, как получить представление модели TMDL семантической модели в рабочей области 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);

}

Выходные данные представляют собой папку с TMDL-представлением модели, как показано ниже:

После сериализации в папку используйте текстовый редактор для редактирования файлов TMDL. Например, с помощью Visual Studio Code можно добавить новую меру [Объем продаж (компьютеры)]:

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

Для улучшения работы можно установить расширение языка TMDL Visual Studio Code.

Развертывание представления модели TMDL

В следующем примере кода показано, как развернуть представление модели TMDL в рабочей области 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();
    }               
}

При выполнении новая мера развертывается в модели.

Обработка ошибок сериализации TMDL

При обнаружении ошибки в методах сериализации TMDL, помимо создания нескольких распространенных исключений .NET, таких как ArgumentException и InvalidOperationException, также возвращаются исключения, относящиеся к TMDL.

• TmdlFormatException возникает, если текст TMDL не является допустимым синтаксисом. Например, недопустимый ключевое слово или отступ.

• TmdlSerializationException возникает, если текст TMDL является допустимым, но нарушает логику метаданных TOM. Например, тип значения не соответствует ожидаемому типу.

Помимо сведений об исключении, включается следующее:

• document path: путь к файлу TMDL с ошибками.
• line number: номер строки с ошибками.
• line text: текст строки с ошибками.

Пример обработки 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;
}    

Сериализация текста объекта

В следующем примере кода показано, как сериализовать столбец в TMDL:

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

Console.WriteLine(output);

Выходные данные:

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

Потоковая сериализация

В следующем примере кода показано, как сериализовать семантиковую модель в одну текстовую переменную:

var output = new StringBuilder();

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

Console.WriteLine(output.ToString());

В следующем примере кода показано, как выполнить десериализацию из TMDL, за исключением ролей:

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