Bibliotecas de clientes do Analysis Services

  • Artigo

aplica-se a: SQL Server Analysis Services Azure Analysis Services Fabric/Power BI Premium

As bibliotecas de cliente são necessárias para que os aplicativos cliente e as ferramentas se conectem ao Analysis Services. Aplicativos cliente microsoft como Power BI Desktop, Excel, SQL Server Management Studio (SSMS) e extensão de projetos do Analysis Services para Visual Studio instalam todas as três bibliotecas de clientes e as atualizam juntamente com atualizações regulares de aplicativos. Aplicativos cliente personalizados para o Analysis Services também podem exigir que uma ou mais dessas bibliotecas de clientes sejam instaladas. As novas versões das bibliotecas de cliente são atualizadas mensalmente.

Importante: Antes de obter as versões mais recentes, veja considerações e limitações.

Baixar as últimas

Windows Installer

Baixar Versão
MSOLAP (amd64) 16.0.156.17
MSOLAP (x86) 16.0.156.17
amo 19.84.1.0
do ADOMD 19.84.1.0

Observação: os downloads do Windows Installer para AMO/TOM (Objetos de Gerenciamento do Analysis Services) e ADOMD não estão mais sendo atualizados e não estarão disponíveis após 31 de dezembro de 2024. Os aplicativos que dependem desses downloads do Windows Installer devem ser migrados para pacotes NuGet.

Pacotes NuGet

As bibliotecas de clientes AMO/TOM (Objetos de Gerenciamento do Analysis Services) e ADOMD estão disponíveis como pacotes instaláveis de NuGet.org. É altamente recomendável migrar para referências do NuGet em vez de usar o Windows Installer.

Os assemblies de pacote NuGet AssemblyVersion seguem o controle de versão semântico: MAJOR. MENOR. REMENDO. As referências do NuGet carregam a versão esperada mesmo se houver uma versão diferente no GAC (resultante da instalação do MSI). PATCH é incrementado para cada versão. As versões AMO e ADOMD são mantidas em sincronia.

A partir de julho de 2024, os pacotes AMO e ADOMD contêm versões de vários runtimes para todos os runtimes de destino com suporte, tanto .NET FX quanto .NET Core; versões anteriores dos pacotes direcionados apenas a um único runtime, .NET FX ou .NET Core, estão disponíveis para compatibilidade com versões anteriores, mas não são mais atualizadas.

A partir de setembro de 2022, AMO (AMO/TOM) e ADOMD .Net Core (versão 19.48.0.0), a comunicação baseada em HTTP com serviços de nuvem como o Power BI e o Azure Analysis Services é significativamente aprimorada. É recomendável que você atualize para a versão mais recente para aproveitar as melhorias de desempenho.

A partir de fevereiro de 2021, suporte ao runtime do .NET Core está disponível para os pacotes de cliente AMO e ADOMD. No entanto, há alguns cenários sem suporte para as versões do .NET Core. Para saber mais, consulte considerações e limitações posteriormente neste artigo.

AMO e ADOMD

Pacote Versão
amo 19.86.2.1
do ADOMD 19.86.2.1

Observação:

Os novos pacotes de vários runtimes não têm mais o sufixo ".retail.amd64" na identidade do pacote e agora são simplesmente chamados de Microsoft.AnalysisServices e Microsoft.AnalysisServices.AdomdClient.

Os pacotes mais antigos do .NET Framework e do .NET Core ainda estão disponíveis em nuget.org para compatibilidade com versões anteriores na identidade antiga com o sufixo ".retail.amd64" para .NET Framework e o ". Sufixo NetCore.retail.amd64" para .NET Core.

Versões mínimas necessárias

O protocolo TLS versão 1.0/1.1 foi preterido na ID do Microsoft Entra em 30 de junho de 2021. O TLS 1.2 ou superior agora é necessário. O TLS 1.2 não tem suporte em versões anteriores das bibliotecas de clientes do Analysis Services. Versões mais recentes da biblioteca de clientes incluem suporte para TLS 1.2 e superior, além de outros aprimoramentos de segurança importantes.

Para minimizar riscos e possíveis vulnerabilidades de segurança, a partir de 30 de junho de 2021, a segurança aprimorada no Azure Analysis Services e no Power BI exige as seguintes versões ou versões mais altas:

Lib de cliente Versão do arquivo Versão
MSOLAP 2018.151.61.21 15.1.61.21
AMO 15.1.61.21 19.12.3.0
ADOMD 15.1.61.21 19.12.3.0

Considerações e limitações

AMO e ADOMD

A partir da versão 19.84.6, o suporte para .NET FX 4.5 e .NET Core 3.0 nos assemblies gerenciados não está mais disponível. Os assemblies do lado do cliente AS agora são lançados com suporte apenas para .NET FX 4.7.2, bem como .NET 6.0 e .NET 8.0.

Começando com a versão 19.82.0.0, AMO e ADOMD dão suporte a Perfis de Entidade de Serviço para autenticação, como no exemplo de cadeia de conexão a seguir. Para saber mais, consulte Usar perfis de entidade de serviço para gerenciar dados do cliente em aplicativos multilocatários.

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>

A partir da versão 19.67.0, objetos de conectividade como Microsoft.AnalysisServices.AdomdClient.AdomdConnection e Microsoft.AnalysisServices.Server dão suporte a uma nova propriedade AccessToken que permite uma maneira aprimorada de passar tokens OAuth externos para serem usados pela camada de conectividade XMLA. Para saber mais, consulte Propriedades da cadeia de conexão – ID do usuário=...; Password=.

A partir da versão 19.42.0.4, ADOMD.NET e AMO/TOM usam MSAL (Microsoft.Identity.Client) versão 4.43.0 ou superior em vez da ADAL para autenticar usuários com a ID do Microsoft Entra ao estabelecer uma conexão com serviços baseados em nuvem, como Power-BI e Azure Analysis Services. Se o aplicativo ou outro componente do qual o aplicativo depende estiver usando a MSAL, talvez seja necessário atualizar as configurações de redirecionamento de associação do aplicativo se houver conflitos entre as versões da MSAL carregadas pelos componentes.

AMO e ADOMD .Net Core

Os cenários com suporte incluem conexões com o Azure Analysis Services, o Power BI Premium e o SQL Server Analysis Services. A conectividade baseada em TCP tem suporte apenas para computadores Windows.

O logon interativo com a ID do Microsoft Entra tem suporte apenas para computadores Windows. O runtime da Área de Trabalho do .NET Core é necessário.

A dependência na MSAL requer a versão 4.43.0 ou superior.

A versão 19.14.0 das bibliotecas de clientes do .Net Core introduziu suporte de visualização para publicação de Self-Contained (em um diretório publicado e no modo de arquivo único), além do suporte para consumo por projetos do .NET 5.0. Vários problemas relacionados à conectividade com o SQL Server Analysis Services identificados na versão anterior foram corrigidos.

A versão 19.12.7.2 das bibliotecas de clientes do .Net Core introduziu suporte para o SQL Server Analysis Services. Versões de versão prévia inferior só suportavam modelos semânticos do Azure Analysis Services e do Power BI.

AMO

A partir da versão 19.84.6, o suporte para TMDL no AMO\TOM é considerado como em General-Availability status e não haverá alterações significativas na superfície da API.

A versão 19.12.3.0 da biblioteca de clientes AMO apresenta uma nova enumeração, Microsoft.AnalysisServices.DataType. No entanto, a enumeração anterior, Microsoft.AnalysisServices.Tabular.DataType ainda existe. Se o código fizer referência à enumeração anterior como DataType em um arquivo de código com instruções para ambos os namespaces (Microsoft.AnalysisServices, Microsoft.AnalysisServices.Tabular), devido à ambiguidade, você poderá receber um erro ao compilar. Para resolver o erro, qualifique totalmente a referência à enumeração.

A versão 19.61.1.4 da biblioteca de clientes AMO apresenta uma alteração no comportamento de reversão de transações de Microsoft.AnalysisServices.Server. Em versões anteriores, uma chamada para Server.RollbackTransaction() envia uma solicitação ao mecanismo para reverter a transação e, em seguida, tentar reverter as alterações locais. Ao contrário das versões anteriores, na versão 19.61.1.4 e posterior, se as alterações locais não puderem ser revertidas com segurança, os bancos de dados tabulares incluídos no bloco de transações poderão ser totalmente sincronizados e as alterações obsoletas da transação que foram revertidas serão removidas. Um InvalidOperationException é gerado quando uma alteração é feita no banco de dados tabular relevante. Se o código estiver chamando Server.RollbackTransaction(), é recomendável seguir essa chamada com uma sincronização completa [Database.Refresh(true)] para qualquer banco de dados tabular modificado como parte da transação.

Começando com a versão 19.77.0, ao clonar ou copiar um MetadataObject em outra instância de um MetadataObject usando o TOM (Modelo de Objeto Tabular), o TOM retorna nulo para propriedades que fazem referência cruzada a objetos fora da árvore direta de objetos filho do MetadataObject. Você deve adicionar a instância metadataObject clonada ao modelo semântico para que referências cruzadas a objetos fora da árvore MetadadosObject possam ser resolvidas.

Por exemplo, ao clonar uma tabela com uma partição que referencia uma expressão nomeada em um EntityPartitionSource, a propriedade ExpressionSource do EntityPartitionSource retorna nulo até que a tabela clonada seja adicionada ao modelo semântico como no snippet de código abaixo para que a referência expressionsource clonada possa ser resolvida. O clone deve ser adicionado ao modelo porque a expressão nomeada entre referências é um membro da coleção Expressions do modelo e não faz parte da árvore de objetos filho da tabela.

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

ADOMD

A partir do ADOMD (ambos .NET Framework e .NET Core) versão 19.61.1.4, a compactação está totalmente disponível na camada de transporte XMLA. Versões anteriores após a versão 19.55.3.1 implementaram algum suporte parcial para compactação. Foram recebidos relatórios sobre problemas com essas versões. Esses problemas foram corrigidos como parte da versão 16.61.1.4. Certifique-se de atualizar para 19.61.1.4 ou posterior se você estiver enfrentando problemas relacionados à compactação.

MSOLAP

A partir da versão 16.0.139.27, o MSOLAP dá suporte a Perfis de Entidade de Serviço para autenticação, como no exemplo de cadeia de conexão a seguir. Para saber mais, consulte Usar perfis de entidade de serviço para gerenciar dados do cliente em aplicativos multilocatários.

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>

A partir da versão 16.0.134.22, o MSOLAP dá suporte ao SSO (Single Sign-On) silencioso usando o WAM (Web Account Manager), disponível no Windows 10 e superior, bem como no Window Server 2019 e superior. Quando uma nova conexão HTTP é aberta, o MSOLAP obtém um token de acesso da seguinte maneira:

  1. Se o cache de token estiver habilitado e um token adequado estiver disponível no cache, o MSOLAP usará o token armazenado em cache.
  2. Se um token armazenado em cache adequado não estiver disponível, o MSOLAP tentará obter um token de acesso silenciosamente por meio do WAM.
  3. Se o SSO usando o WAM falhar, o MSOLAP retornará à autenticação interativa e abrirá a janela de logon.

Os usuários podem ignorar o fluxo de SSO silencioso e iniciar imediatamente a experiência de autenticação interativa fornecendo uma ID de usuário 'vazia' na cadeia de conexão (ID do usuário=').

A partir da versão 16.0.43.20, o MSOLAP usa a MSAL (Microsoft.Identity.Client) versão 4.43.0 ou superior em vez da ADAL para autenticar usuários com a ID do Microsoft Entra ao estabelecer uma conexão com serviços baseados em nuvem, como Power-BI e Azure Analysis Services. Se o aplicativo ou outro componente do qual o aplicativo depende estiver usando a MSAL, talvez seja necessário atualizar as configurações de redirecionamento de associação do aplicativo se houver conflitos entre as versões da MSAL carregadas pelos componentes

Uma regressão relacionada a conexões com sistemas baseados em nuvem usando a ID do Microsoft Entra foi descoberta na versão 16.0.4.17 do MSOLAP (OLEDB). Foi corrigido na versão 16.0.20.201. Devido à natureza do problema, uma versão 16.0.4.17 instalada, bem como qualquer outra versão anterior à 16.0.20.201, não pode ser corrigida atualizando o provedor, mesmo que a instalação seja executada no modo de reparo. É recomendável desinstalar completamente a versão 16.0.4.17 [ou outra problemática] e instalar a versão 16.0.20.201 ou posterior.

Em uma versão anterior, o MSOLAP foi atualizado para se conectar ao Analysis Services baseado em nuvem usando a MSAL (Biblioteca de Autenticação da Microsoft) gerenciada. A partir da versão 16.0.87.16, a instalação do MSOLAP não instala mais o componente original da ADAL (Biblioteca de Autenticação do Azure Active Directory) nativo.

Noções básicas sobre bibliotecas de cliente

O Analysis Services utiliza três bibliotecas de clientes. ADOMD.NET e AMO (Objetos de Gerenciamento do Analysis Services) são bibliotecas de cliente gerenciadas. E o Provedor OLE DB do Analysis Services (MSOLAP DLL) é uma biblioteca de cliente nativa. Normalmente, os três são instalados ao mesmo tempo.

Aplicativos cliente da Microsoft, como o Power BI Desktop e o Excel, instalam todas as três bibliotecas de clientes e as atualizam quando novas versões estão disponíveis. Dependendo da versão ou da frequência das atualizações, algumas bibliotecas de clientes podem não ser as versões mais recentes exigidas pelo Azure Analysis Services e pelo Power BI. O mesmo se aplica a aplicativos personalizados ou outras interfaces, como AsCmd, TOM, ADOMD.NET. Esses aplicativos exigem a instalação manual ou programática das bibliotecas. As bibliotecas de cliente para instalação manual são incluídas em pacotes de recursos do SQL Server como pacotes distribuíveis. No entanto, essas bibliotecas de clientes estão vinculadas à versão do SQL Server e podem não ser as mais recentes. Certifique-se de sempre instalar o artigo mais recente e baixável.

Tipos de biblioteca de cliente

Provedor OLE DB do Analysis Services (MSOLAP)

O MSOLAP (Provedor OLE DB) do Analysis Services é a biblioteca de clientes nativa para conexões de banco de dados do Analysis Services. Ele é usado indiretamente por ADOMD.NET e AMO, delegando solicitações de conexão ao provedor de dados. Você também pode chamar o Provedor OLE DB diretamente do código do aplicativo.

O Provedor OLE DB do Analysis Services é instalado automaticamente pela maioria das ferramentas e aplicativos cliente usados para acessar bancos de dados do Analysis Services. Ele deve ser instalado em computadores usados para acessar dados do Analysis Services.

Os provedores OLE DB geralmente são especificados em cadeias de conexão. Uma cadeia de conexão do Analysis Services usa uma nomenclatura diferente para se referir ao Provedor OLE DB: MSOLAP.<versão>.dll.

AMO

AMO é uma biblioteca de cliente gerenciada usada para administração de servidor e definição de dados. Ele é instalado e usado por ferramentas e aplicativos cliente. Por exemplo, o SSMS (SQL Server Management Studio) usa AMO para se conectar ao Analysis Services. Uma conexão usando AMO normalmente é mínima, consistindo em "data source=\<servername>". Depois que uma conexão é estabelecida, você usa a API para trabalhar com coleções de banco de dados e objetos principais. Tanto o Visual Studio quanto o SSMS usam AMO para se conectar a uma instância do Analysis Services.

ADOMD

ADOMD.NET é uma biblioteca de clientes de dados gerenciados usada para consultar dados do Analysis Services. Ele é instalado e usado por ferramentas e aplicativos cliente.

Ao se conectar a um banco de dados, as propriedades da cadeia de conexão para todas as três bibliotecas são semelhantes. Quase qualquer cadeia de conexão definida para ADOMD.NET usando Microsoft.AnalysisServices.AdomdClient.AdomdConnection.ConnectionString também funciona para AMO e o PROVEDOR OLE DB do Analysis Services (MSOLAP). Para saber mais, consulte propriedades da cadeia de conexão.

Verificar versões instaladas

OLEDDB (MSOLAP)

  1. Vá para C:\Program Files\Microsoft Analysis Services\AS OLEDB\. Se você tiver mais de uma pasta, escolha o número mais alto.

  2. Clique com o botão direito do mouse emdetalhes de propriedades msolap.dll. Verifique a propriedade da versão do produto . Observação: se o nome do arquivo for msolap140.dll, ele será mais antigo que a versão mais recente e deverá ser atualizado.

    de detalhes da biblioteca do cliente MSOLAP

AMO

  1. Vá para C:\Windows\Microsoft.NET\assembly\GAC_MSIL\Microsoft.AnalysisServices\. Se você tiver mais de uma pasta, escolha o número mais alto.

  2. Clique com o botão direito do mouse Detalhes das PropriedadesMicrosoft.AnalysisServices.

    de detalhes da biblioteca do cliente AMO

ADOMD

  1. Vá para C:\Windows\Microsoft.NET\assembly\GAC_MSIL\Microsoft.AnalysisServices.AdomdClient\. Se você tiver mais de uma pasta, escolha o número mais alto.

  2. Clique com o botão direito do mouse Microsoft.AnalysisServices.AdomdClient>Properties>Details.

    caixa de diálogo de detalhes da biblioteca de clientes do ADOMD

Atualizar manualmente

As bibliotecas de cliente normalmente são instaladas e atualizadas automaticamente, juntamente com ferramentas e aplicativos cliente que as usam. No entanto, em alguns casos, as bibliotecas de cliente podem não ser atualizadas automaticamente e cada uma deve ser atualizada manualmente. Para atualizar manualmente, baixe e execute o pacote do Windows Installer (.msi) para cada biblioteca de clientes.

Para baixar e atualizar

  1. Clique:

  2. No Downloads, clique em um Pacote do Windows Installer para executar a Instalação.

  3. Na Instalação, clique em Próximo.

  4. Leia o contrato de licença. Se você concordar, selecione aceito os termos no contrato de licençae, em seguida, clique em Próximo.

  5. Clique Instalar.

  6. Quando concluído, clique em Concluir.