Analysis Services client libraries

применимо: SQL Server Analysis Services Azure Analysis Services Fabric/Power BI Premium

Клиентские библиотеки необходимы для клиентских приложений и инструментов для подключения к службам Analysis Services. Клиентские приложения Майкрософт, такие как Power BI Desktop, Excel, SQL Server Management Studio (SSMS) и расширения проектов служб Analysis Services для Visual Studio устанавливают все три клиентские библиотеки и обновляют их вместе с регулярными обновлениями приложений. Для пользовательских клиентских приложений для служб Analysis Services также может потребоваться установить одну или несколько этих клиентских библиотек. Новые версии клиентских библиотек обновляются примерно ежемесячно.

Важно: перед получением последних версий обязательно просмотрите вопросы и ограничения.

Скачать последнюю версию

Установщик Windows

Примечание: установщики Windows для объектов управления службами Analysis Services (AMO/TOM) и ADOMD больше не будут обновляться и не будут доступны после 31 декабря 2024 года. Приложения, использующие эти загрузки установщика Windows, должны переноситься в пакеты NuGet.

Пакеты NuGet

Клиентские библиотеки служб Analysis Services Management Objects (AMO/TOM) и ADOMD доступны как устанавливаемые пакеты из NuGet.org. Настоятельно рекомендуется перейти на ссылки NuGet вместо использования установщика Windows.

NuGet package assemblies AssemblyVersion follow semantic versioning: MAJOR.MINOR.PATCH. NuGet-ссылки загружают ожидаемую версию, даже если в GAC находится другая версия (в результате установки через MSI). PATCH is incremented for each release. Версии AMO и ADOMD поддерживаются в синхронном состоянии.

Начиная с июля 2024 года пакеты AMO и ADOMD содержат выпуски с несколькими средами выполнения для всех поддерживаемых целевых сред выполнения, как для .NET FX, так и для .NET Core; Предыдущие выпуски пакетов, предназначенных только для одной среды выполнения , .NET FX или .NET Core, доступны для обратной совместимости, но больше не обновляются.

Начиная с сентября 2022 года, AMO (AMO/TOM) и ADOMD .Net Core (версия 19.48.0.0.0), взаимодействие на основе HTTP с облачными службами, такими как Power BI и Azure Analysis Services, значительно улучшается. Рекомендуется обновить до последней версии, чтобы воспользоваться улучшениями производительности.

Начиная с февраля 2021 г. поддержка среды выполнения .NET Core доступна для клиентских пакетов AMO и ADOMD. Однако существует несколько сценариев, которые не поддерживаются версиями .NET Core. Дополнительные сведения см. в соображениях и ограничениях, далее в этой статье.

AMO и ADOMD

Примечание.

Новые пакеты с несколькими средами выполнения больше не имеют суффикса .retail.amd64 в идентификаторе пакета и теперь просто называются Microsoft.AnalysisServices и Microsoft.AnalysisServices.AdomdClient.

The older .NET Framework and .NET Core packages are still available in nuget.org for backward compatibility under the old identity with the ".retail.amd64" suffix for .NET Framework, and the ".NetCore.retail.amd64" suffix for .NET Core.

Минимальные необходимые версии

Протокол TLS версии 1.0/1.1 был устаревшим в идентификаторе Microsoft Entra 30 июня 2021 г. Теперь требуется протокол TLS 1.2 или более поздней версии. TLS 1.2 не поддерживается в более ранних версиях клиентских библиотек служб Analysis Services. Более новые версии клиентской библиотеки включают поддержку TLS 1.2 и более поздних версий в дополнение к другим важным улучшениям безопасности.

Чтобы свести к минимуму риск и потенциальные уязвимости безопасности, начиная с 30 июня 2021 г., для повышения безопасности в Службах Azure Analysis Services и Power BI требуются следующие или более поздние версии:

Рекомендации и ограничения

AMO и ADOMD

Пакеты AdomdClient и AMO версии 19.94.1.1 заменяют версию 19.94.0.0. Обновите до последней версии.

С версией 19.94.1.1:

• Классы параметров сериализации TMDL в пакете AMO включают набор методов расширения для упрощения их использования. Дополнительные сведения см. в справочной документации по API.
• Сведения об ошибках в определенных сценариях разработки семантической модели включают дополнительные сведения о нарушениях совместимости и перекрестных проблемах со ссылкой:
  • Нарушения совместимости: класс CompatibilityViolationException предоставляет подробные сведения в тексте сообщения для устранения неполадок. Дополнительные свойства, такие как SupportedCompatibilityLevel и CompatibilityLevelRequest, также предоставляют более подробные сведения.
  • Ошибки перекрестных ссылок: классы TmdlDeserializationWithReferenceErrorsException и JsonDeserializationWithReferenceErrorsException предоставляют подробные сообщения об ошибках, которые перечисляют неразрешенные свойства и предоставляют дополнительные сведения об ошибках перекрестных ссылок. Эти новые классы исключений могут помочь в обработке проблем десериализации TMDL и TMSL.

Начиная с версии 19.84.6 поддержка .NET FX 4.5 и .NET Core 3.0 в управляемых сборках больше недоступна. Клиентские сборки AS теперь выпускаются с поддержкой .NET FX 4.7.2, а также только для .NET 6.0 и .NET 8.0.

Начиная с версии 19.82.0.0, AMO и ADOMD поддерживают профили сервисных принципалов для проверки подлинности, как в следующем примере строки подключения. Дополнительные сведения см. в статье Использование профилей субъекта-службы для управления данными клиентов в мультитенантных приложениях. Пользователи не могут подключаться к рабочим областям, связанным с лицензией Premium Per-User, с помощью профилей сервисного принципала через конечную точку XMLA.

Data Source=powerbi://api.powerbi.com/v1.0/myorg/<WorkspaceName>;User ID=app:<service principal id>@<tenant id>;SPN Profile=<service-principal profile id>;Password=<service-principal's secret>

Начиная с версии 19.67.0, объекты подключения, такие как Microsoft.AnalysisServices.AdomdClient.AdomdConnection и Microsoft.AnalysisServices.Server, поддерживают новое свойство AccessToken, которое позволяет улучшить способ передачи внешних маркеров OAuth, используемых уровнем подключения XMLA. Дополнительные сведения см. в разделе Свойства строки подключения — идентификатор пользователя=...; Password=.

Начиная с версии 19.42.0.4, ADOMD.NET и AMO/TOM используют MSAL (Microsoft.Identity.Client) версии 4.43.0 или более поздней, а не ADAL для проверки подлинности пользователей с идентификатором Microsoft Entra при установке подключения к облачным службам, таким как Power-BI и Azure Analysis Services. Если ваше приложение или другой компонент, от которого зависит приложение, использует MSAL, может потребоваться обновить настройки перенаправления привязки приложения, если между версиями MSAL, используемыми компонентами, возникают конфликты.

AMO и ADOMD .Net Core

Поддерживаемые сценарии включают подключения к Службам Azure Analysis Services, Power BI Premium и службам SQL Server Analysis Services. Подключение на основе TCP поддерживается только для компьютеров Windows.

Интерактивный вход с Microsoft Entra ID поддерживается только для компьютеров Windows. Требуется среда выполнения рабочего стола .NET Core.

Зависимость в MSAL требует версии 4.43.0 или выше.

Version 19.14.0 of the .Net Core client libraries introduced preview support for Self-Contained publishing (both in a published directory, and in single-file mode), in addition to support for consumption by .NET 5.0 projects. Исправлены некоторые проблемы, связанные с подключением к службам SQL Server Analysis Services, которые были определены в предыдущем выпуске.

Версия 19.12.7.2 клиентских библиотек .Net Core представила поддержку служб SQL Server Analysis Services. Ранние версии предварительного просмотра поддерживали только Azure Analysis Services и семантические модели Power BI.

АМО

Starting with version 19.84.6, the support for TMDL in AMO\TOM is considered as in General-Availability status, and there won’t be any breaking changes in the API surface.

Версия 19.12.3.0 клиентской библиотеки AMO представляет новое перечисление, Microsoft.AnalysisServices.DataType. Однако предыдущее перечисление Microsoft.AnalysisServices.Tabular.DataType по-прежнему существует. If your code references the previous enumeration as DataType in a code file with statements to both namespaces (Microsoft.AnalysisServices, Microsoft.AnalysisServices.Tabular), due to the ambiguity, you could get an error when compiling. To resolve the error, fully qualify the reference to the enumeration.

Версия 19.61.1.4 клиентской библиотеки AMO представляет изменение поведения отката транзакций Microsoft.AnalysisServices.Server. В более ранних версиях вызов Server.RollbackTransaction() отправляет обработчику запрос на откат транзакции, а затем пытается откатить локальные изменения. В отличие от более ранних версий, в версиях 19.61.1.4 и более поздних, если локальные изменения невозможно безопасно откатить, табличные базы данных, включённые в транзакцию, блокируют любые дополнительные изменения до тех пор, пока они не будут полностью синхронизированы, а устаревшие изменения из откатированных транзакций не будут удалены. При изменении соответствующей табличной базы данных возникает исключение InvalidOperationException. Если код вызывает Server.RollbackTransaction(), рекомендуется следовать этому вызову с полной синхронизацией [Database.Refresh(true)] для любой табличной базы данных, которая изменяется в рамках транзакции.

Начиная с версии 19.77.0, при клонировании или копировании объекта метаданных в другой экземпляр объекта метаданных с помощью табличной объектной модели (TOM), TOM возвращает значение null для свойств, которые ссылались на объекты вне прямого дерева дочерних объектов MetadataObject. Необходимо добавить клонированный экземпляр MetadataObject в семантику модели, чтобы разрешить перекрестные ссылки на объекты вне дерева MetadataObject.

Например, при клонировании таблицы с разделом, ссылающимся на именованное выражение в EntityPartitionSource, свойство ExpressionSource объекта EntityPartitionSource возвращает значение NULL, пока клонированная таблица не будет добавлена в семантическую модель, как в фрагменте кода ниже, чтобы можно было разрешить ссылку на клонированный объект ExpressionSource. The clone must be added to the model because the cross-referenced named expression is a member of the model’s Expressions collection and not part of the table’s tree of child objects.

Table tableClone = model.Tables[0].Clone();
anotherModel.Tables.Add(tableClone);

ADOMD

Начиная с ADOMD (как .NET Framework, так и .NET Core) версии 19.61.1.4 сжатие полностью доступно на уровне транспорта XMLA. Предыдущие выпуски после версии 19.55.3.1 реализовали некоторую частичную поддержку сжатия. Были получены отчеты о проблемах с этими выпусками. Эти проблемы были исправлены в составе выпуска 16.61.1.4. Не забудьте обновить до версии 19.61.1.4 или более поздней версии, если возникают проблемы, связанные с сжатием.

MSOLAP

Начиная с версии 16.0.139.27 MSOLAP поддерживает профили субъектов-служб для проверки подлинности, как показано в следующем примере строки подключения. Дополнительные сведения см. в статье Использование профилей субъекта-службы для управления данными клиентов в мультитенантных приложениях.

Data Source=powerbi://api.powerbi.com/v1.0/myorg/<WorkspaceName>;User ID=app:<service principal id>@<tenant id>;SPN Profile=<service-principal profile id>;Password=<service-principal's secret>

Начиная с версии 16.0.134.22, MSOLAP поддерживает единый вход в фоновом режиме (SSO) с помощью диспетчера веб-учетных записей (WAM), доступного в Windows 10 и более поздних версиях, а также Windows Server 2019 и более поздних версий. При открытии нового HTTP-подключения MSOLAP получает маркер доступа следующим образом:

1. Если кэширование маркеров включено, а подходящий маркер доступен в кэше, MSOLAP использует кэшированный маркер.
2. Если подходящий кэшированный токен недоступен, MSOLAP пытается тихо получить токен доступа через WAM.
3. Если единый вход с использованием WAM не удался, MSOLAP переходит к интерактивной аутентификации и открывает окно входа.

Users can bypass the silent SSO flow and immediately launch the interactive authentication experience by providing an 'empty' user id in the connection-string (User ID='').

Начиная с версии 16.0.43.20 MSOLAP использует MSAL (Microsoft.Identity.Client) версии 4.43.0 или более поздней версии вместо ADAL для проверки подлинности пользователей с идентификатором Microsoft Entra при установке подключения к облачным службам, таким как Power-BI и Azure Analysis Services. Если ваше приложение или другой компонент, от которого зависит приложение, использует MSAL, может потребоваться обновить параметры перенаправления привязки приложения, если существуют конфликты между версиями MSAL, загруженными компонентами.

Регрессия, связанная с подключениями к облачным системам с помощью идентификатора Microsoft Entra, была обнаружена в версии OLEDB 16.0.4.17 (MSOLAP). Она была исправлена в версии 16.0.20.201. Из-за проблемы установленная версия 16.0.4.17, а также любая другая версия до 16.0.20.201, не может быть исправлена путем замены поставщика, даже если установка выполняется в режиме восстановления. Рекомендуется полностью удалить версию 16.0.4.17 [или другие проблемы], а затем установить версию 16.0.20.201 или более поздней.

В предыдущем выпуске MSOLAP было обновлено для подключения к облачным службам Analysis Services с помощью управляемой библиотеки проверки подлинности Майкрософт (MSAL). Начиная с версии 16.0.87.16 программа установки MSOLAP больше не устанавливает исходный компонент собственной библиотеки проверки подлинности Azure Active Directory (ADAL).

Общие сведения о клиентских библиотеках

Службы Analysis Services используют три клиентские библиотеки. ADOMD.NET и объекты управления службами Analysis Services (AMO) — это клиентские библиотеки. And Analysis Services OLE DB Provider (MSOLAP DLL) is a native client library. Как правило, все три устанавливаются одновременно.

Клиентские приложения Майкрософт, такие как Power BI Desktop и Excel, устанавливают все три клиентские библиотеки и обновляют их при наличии новых версий. В зависимости от версии или частоты обновлений некоторые клиентские библиотеки могут не быть последними версиями, необходимыми службами Azure Analysis Services и Power BI. Это же относится к пользовательским приложениям или другим интерфейсам, таким как AsCmd, TOM, ADOMD.NET. Для этих приложений требуется вручную или программно устанавливать библиотеки. Клиентские библиотеки для ручной установки включены в пакеты дополнительных компонентов SQL Server в качестве распространяемых пакетов. Однако эти клиентские библиотеки привязаны к версии SQL Server и могут не быть последними. Убедитесь, что вы всегда устанавливаете последнюю, скачиваемую из этой статьи.

Типы клиентской библиотеки

Analysis Services OLE DB Provider (MSOLAP)

Поставщик OLE DB для служб Analysis Services (MSOLAP) — это родная клиентская библиотека для подключения к базам данных Analysis Services. Он используется косвенно как ADOMD.NET, так и AMO, делегируя запросы на подключение к поставщику данных. Вы также можете вызвать поставщика OLE DB непосредственно из кода приложения.

Поставщик OLE DB служб Analysis Services устанавливается автоматически большинством средств и клиентских приложений, используемых для доступа к базам данных служб Analysis Services. Он должен быть установлен на компьютерах, используемых для доступа к данным служб Analysis Services.

Поставщики OLE DB часто указываются в строках подключения. An Analysis Services connection string uses a different nomenclature to refer to the OLE DB Provider: MSOLAP.<version>.dll.

АМО

AMO — это управляемая клиентская библиотека, используемая для администрирования сервера и определения данных. Он устанавливается и используется утилитами и клиентскими приложениями. Например, SQL Server Management Studio (SSMS) использует AMO для подключения к Службам Analysis Services. Подключение с помощью AMO обычно минимальное, состоящее из "data source=\<servername>". После установки подключения используйте API для работы с коллекциями баз данных и основными объектами. Visual Studio и SSMS используют AMO для подключения к инстанции Аналитических служб.

ADOMD

ADOMD.NET — это клиентская библиотека управляемых данных, используемая для запроса данных служб Analysis Services. Он устанавливается и используется утилитами и клиентскими приложениями.

При подключении к базе данных свойства строки подключения для всех трех библиотек похожи. Почти любая строка подключения, определяемая для ADOMD.NET с помощью Microsoft.AnalysisServices.AdomdClient.AdomdConnection.ConnectionString также работает для AMO и поставщика OLE DB служб Analysis Services (MSOLAP). Дополнительные сведения см. в разделе свойства строки подключения.

Проверка установленных версий

OLEDDB (MSOLAP)

1. Go to C:\Program Files\Microsoft Analysis Services\AS OLEDB\. Если у вас несколько папок, выберите большее число.

2. Щелкните правой кнопкой мыши msolap.dll>Свойства>Сведения. Проверьте свойство product version. Примечание. Если имя файла msolap140.dll, оно старше последней версии и должно быть обновлено.

   диалоговое окно сведений о клиентской библиотеке MSOLAP

АМО

1. Go to C:\Windows\Microsoft.NET\assembly\GAC_MSIL\Microsoft.AnalysisServices\. Если у вас несколько папок, выберите большее число.

2. Щелкните правой кнопкой мыши Microsoft.AnalysisServices>Properties>Details.

   

ADOMD

1. Go to C:\Windows\Microsoft.NET\assembly\GAC_MSIL\Microsoft.AnalysisServices.AdomdClient\. Если у вас несколько папок, выберите большее число.

2. Щелкните правой кнопкой мыши Microsoft.AnalysisServices.AdomdClient>Свойства>сведения.

   диалоговое окно сведений о клиентской библиотеке ADOMD

Обновление вручную

Клиентские библиотеки обычно устанавливаются и обновляются автоматически вместе с инструментами и клиентскими приложениями, которые используют их. Однако в некоторых случаях клиентские библиотеки могут не обновляться автоматически, и каждый из них должен обновляться вручную. Чтобы обновить вручную, скачайте и запустите пакет установщика Windows (.msi) для каждой клиентской библиотеки.

Скачивание и обновление

1. Нажмите:

   • скачать MSOLAP (amd64) или скачать MSOLAP (x86)
   • Скачайте AMO
   • Скачивание ADOMD

2. В Загрузках, щелкните Windows Installer Package, чтобы запустить программу установки.

3. В разделе "Настройка" нажмите кнопку Далее.

4. Прочитайте лицензионное соглашение. Если вы согласны, выберите я принимаю условия лицензионного соглашения, а затем нажмите кнопку Далее.

5. Щелкните Установить.

6. По завершении нажмите кнопку Готово.