Bibliotecas de cliente do Analysis Services

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 e as ferramentas cliente se conectem ao Analysis Services. Aplicações cliente Microsoft como Power BI Desktop, Excel, SQL Server Management Studio (SSMS) e extensão de projetos Analysis Services para Visual Studio instalam as três bibliotecas clientes e atualizam-nas juntamente com atualizações regulares de aplicações. Os aplicativos cliente personalizados para o Analysis Services também podem exigir que uma ou mais dessas bibliotecas de cliente sejam instaladas. Novas versões das bibliotecas de cliente são atualizadas aproximadamente mensalmente.

Importante: Antes de obter as versões mais recentes, certifique-se de ver Considerações e limitações.

Faça o download das últimas notícias

Instalador Windows

Nota: Os downloads do Instalador Windows para Analysis Services Management Objects (AMO/TOM) e ADOMD já não estão a ser atualizados e não estarão disponíveis após 31 de dezembro de 2024. As aplicações que dependem destes downloads do Windows Installer devem ser migradas para pacotes NuGet.

Pacotes NuGet

As bibliotecas de Objetos de Gestão de Serviços de Análise (AMO/TOM) e ADOMD estão disponíveis como pacotes instaláveis a partir de NuGet.org. É fortemente recomendado que migre para referências NuGet em vez de usar o Windows Installer.

Os assemblies dos pacotes NuGet AssemblyVersion seguem o versionamento semântico: MAIOR.MENOR.CORREÇÃO. As referências do NuGet carregam a versão esperada mesmo que haja uma versão diferente no GAC (resultante da instalação MSI). O PATCH é incrementado a cada lançamento. 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 multi-runtime para todos os tempos de execução alvo suportados, tanto .NET FX como .NET Core; versões anteriores dos pacotes que visavam apenas um único runtime, seja .NET FX ou .NET Core, estão disponíveis para compatibilidade retroativa, mas já não são atualizadas.

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

A partir de fevereiro de 2021, o suporte em runtime .NET Core está disponível para os pacotes clientes AMO e ADOMD. No entanto, existem alguns cenários que não são suportados pelas versões .NET Core. Para saber mais, consulte considerações e limitações mais adiante neste artigo.

AMO e ADOMD

Nota:

Os novos pacotes multi-runtime 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 .NET Framework e .NET Core ainda estão disponíveis em nuget.org para compatibilidade retroativa sob a identidade antiga com o sufixo ".retail.amd64" para .NET Framework, e o ". NetCore.retail.amd64" para .NET Core.

Versões mínimas necessárias

A versão 1.0/1.1 do protocolo de Segurança da Camada de Transporte (TLS) foi obsoleta em Microsoft Entra ID a 30 de junho de 2021. TLS 1.2 ou superior agora é necessário. O TLS 1.2 não é suportado em versões anteriores das bibliotecas de cliente do Analysis Services. As versões mais recentes da biblioteca de cliente incluem suporte para TLS 1.2 e superior, além de outros aprimoramentos de segurança importantes.

Para minimizar riscos e potenciais vulnerabilidades de segurança, a partir de 30 de junho de 2021, a segurança reforçada no Azure Analysis Services e no Power BI exigirá as seguintes versões ou versões superiores:

Considerações e limitações

AMO e ADOMD

A partir da versão 19.98.0.3:

• Um conjunto adicional de propriedades de cadeia de conexão pode ser usado para controlar a experiência de autenticação baseada em Entra-Id em conexões HTTP. Para obter mais informações, consulte o artigoAnalysis-Services propriedades da cadeia de conexão na documentação do produto.
• A comunicação baseada em HTTP é melhorada através de uma melhor gestão dos canais HTTP abertos na camada de transporte, especialmente ao utilizar as bibliotecas .NET Core.

Os pacotes AdomdClient e AMO da versão 19.94.1.1 substituem a versão 19.94.0.0. Por favor, atualize para a versão mais recente.

Com a versão 19.94.1.1:

• As classes de opções de serialização TMDL no pacote AMO incluem um conjunto de métodos de extensão para simplificar seu uso. Para obter mais detalhes, consulte a documentação de referência da API.
• As informações de erro em determinados cenários de criação de modelo semântico incluem detalhes adicionais para violações de compatibilidade e problemas de referência cruzada:
  • Violações de compatibilidade: A classe CompatibilityViolationException oferece informações detalhadas no texto da mensagem para ajudar na solução de problemas. Propriedades adicionais, como SupportedCompatibilityLevel e CompatibilityLevelRequest também expõem informações mais detalhadas.
  • Erros de referência cruzada: As classes TmdlDeserializationWithReferenceErrorsException e JsonDeserializationWithReferenceErrorsException fornecem mensagens de erro detalhadas que listam propriedades não resolvidas e oferecem detalhes adicionais sobre erros de referência cruzada. Essas novas classes de exceção podem ajudar a lidar com problemas de desserialização TMDL e TMSL.

A partir da versão 19.84.6, o suporte para .NET FX 4.5 e .NET Core 3.0 nos assemblies geridos deixou de estar disponível. Os assemblies do lado do cliente do AS são agora lançados com suporte exclusivamente para .NET FX 4.7.2, .NET 6.0 e .NET 8.0.

A partir da versão 19.82.0.0, AMO e ADOMD suportam Perfis Principais de Serviço para autenticação, como no seguinte exemplo de connection string. Para saber mais, consulte Usar perfis de entidade de serviço para gerir dados de clientes em aplicações multilocatárias. Os utilizadores não conseguem conectar-se a workspaces associados a uma licença Premium Per-User utilizando Perfis de Service Principal através do XMLA endpoint.

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, oferecem suporte a uma nova propriedade AccessToken que permite uma maneira aprimorada de passar tokens OAuth externos a serem usados pela camada de conectividade XMLA. Para saber mais, consulte Propriedades da cadeia de conexão - ID do usuário = ...; Senha=.

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

AMO e ADOMD .Net Core

Cenários suportados incluem ligações ao Azure Analysis Services, Power BI Premium e SQL Server Analysis Services. A conectividade baseada em TCP é suportada apenas para computadores Windows.

O login interativo com Microsoft Entra ID é suportado apenas para computadores Windows. É necessário o runtime .NET Core Desktop.

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

A versão 19.14.0 das bibliotecas cliente .Net Core introduziu suporte de pré-visualização para publicação Self-Contained (tanto num diretório publicado como em modo de ficheiro único), além de suporte para consumo por projetos .NET 5.0. Vários problemas relacionados com a conectividade ao SQL Server Analysis Services, identificados na versão anterior, foram corrigidos.

A versão 19.12.7.2 das bibliotecas cliente .Net Core introduziu suporte para SQL Server Analysis Services. Versões de pré-visualização inferiores suportavam apenas modelos semânticos do Azure Analysis Services e Power BI.

AMO

A partir da versão 19.98.0.3, o nível de compatibilidade padrão para bancos de dados modelo tabular é 1700. Os bancos de dados criados sem especificar explicitamente um nível de compatibilidade usam o nível 1700, por padrão.

A partir da versão 19.84.6, o suporte para TMDL em AMO\TOM é considerado como estando no status General-Availability, e não haverá nenhuma alteração na interface da API.

A versão 19.12.3.0 da biblioteca de cliente AMO introduz uma nova enumeração, Microsoft.AnalysisServices.DataType. No entanto, a enumeração anterior, Microsoft.AnalysisServices.Tabular.DataType ainda existe. Se seu 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á obter 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 cliente AMO introduz uma alteração no comportamento de reversão de transação do 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, em 19.61.1.4 e posteriores, se as alterações locais não puderem ser revertidas com segurança, os bancos de dados tabulares incluídos na transação bloquearão quaisquer alterações adicionais até que possam ser totalmente sincronizadas 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 seu 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.

A partir da versão 19.77.0, ao clonar ou copiar um MetadataObject em outra instância de um MetadataObject usando o TOM (Tabular Object Model), o TOM retorna null para propriedades que fazem referência cruzada a objetos fora da árvore direta de objetos filho do MetadataObject. Você deve adicionar a instância de MetadataObject clonada ao modelo semântico para que as referências cruzadas a objetos fora da árvore MetadataObject possam ser resolvidas.

Por exemplo, ao clonar uma tabela com uma partição que faz referência a uma expressão nomeada em um EntityPartitionSource, a propriedade ExpressionSource do EntityPartitionSource retorna null até que a tabela clonada seja adicionada ao modelo semântico, como no trecho 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 com múltiplas referências é um membro da coleção de Expressões do modelo e não faz parte da árvore dos objetos filho da tabela.

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

ADOMD

A partir do ADOMD (tanto .NET Framework como .NET Core) versão 19.61.1.4, a compressã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 estiver enfrentando problemas relacionados à compactação.

MSOLAP

A partir da versão 17.0.25.23, um conjunto adicional de propriedades de cadeia de conexão pode ser usado para controlar a experiência de autenticação baseada em Entra-Id em conexões HTTP. Para obter mais informações, consulte o artigoAnalysis-Services propriedades da cadeia de conexão na documentação do produto.

A partir da versão 16.0.139.27, o MSOLAP suporta Perfis Principais de Serviço para autenticação, como no seguinte exemplo de connection string. Para saber mais, consulte Usar perfis de entidade de serviço para gerir dados de clientes em aplicações multilocatárias.

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 suporta o Single Sign-On silencioso (SSO) usando Web Account Manager (WAM), disponível em versões Windows 10 e superiores, bem como no Windows Server 2019 e versões superiores. 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 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 WAM falhar, o MSOLAP retornará à autenticação interativa e exibirá a janela de login.

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

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

Uma regressão relacionada com ligações a sistemas baseados na cloud usando o Microsoft Entra ID foi descoberta na versão 16.0.4.17 do OLEDB (MSOLAP). 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. Recomenda-se desinstalar completamente a versão 16.0.4.17 [ou outra versão problemática] e, em seguida, instalar a versão 16.0.20.201 ou posterior.

Numa versão anterior, o MSOLAP foi atualizado para se ligar aos Serviços de Análise baseados na cloud utilizando a Microsoft Authentication Library (MSAL) gerida. A partir da versão 16.0.87.16, a configuração do MSOLAP deixa de instalar o componente nativo original da Biblioteca de Autenticação do Azure Active Directory (ADAL).

Noções básicas sobre bibliotecas de clientes

O Analysis Services utiliza três bibliotecas de cliente. ADOMD.NET e os Objetos de Gestão de Serviços de Análise (AMO) são bibliotecas de clientes geridas. E o provedor OLE DB do Analysis Services (MSOLAP DLL) é uma biblioteca de cliente nativa. Normalmente, todos os três são instalados ao mesmo tempo.

Aplicações clientes da Microsoft, como o Power BI Desktop e o Excel, instalam as três bibliotecas clientes e atualizam-nas quando há novas versões disponíveis. Dependendo da versão ou frequência das atualizações, algumas bibliotecas clientes podem não ser as versões mais recentes exigidas pelo Azure Analysis Services e Power BI. O mesmo se aplica a aplicações personalizadas ou outras interfaces como AsCmd, TOM, ADOMD.NET. Estas aplicações requerem a instalação manual ou programática das bibliotecas. As bibliotecas clientes para instalação manual estão incluídas nos pacotes de funcionalidades do SQL Server como pacotes distribuíveis. No entanto, estas bibliotecas clientes estão associadas à versão do SQL Server e podem não ser as mais recentes. Certifique-se de instalar sempre o mais recente, disponível para download a partir deste artigo.

Tipos de biblioteca de cliente

Fornecedor OLE DB do Analysis Services (MSOLAP)

O provedor OLE DB do Analysis Services (MSOLAP) é a biblioteca de cliente nativa para conexões de banco de dados do Analysis Services. É usado indiretamente tanto pelo ADOMD.NET como pelo AMO, delegando pedidos de ligação ao fornecedor 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 de Serviços de Análise utiliza 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 servidores e definição de dados. É instalado e utilizado por ferramentas e aplicações de cliente. Por exemplo, o SQL Server Management Studio (SSMS) utiliza o AMO para se ligar ao Analysis Services. Uma conexão usando AMO é normalmente mínima, consistindo em . 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 como o SSMS usam AMO para se ligar a uma instância de Serviços de Análise.

ADOMD

ADOMD.NET é uma biblioteca cliente de dados gerida utilizada para consultar dados do Analysis Services. É instalado e utilizado por ferramentas e aplicações de cliente.

Ao ligar a uma base de dados, as propriedades da connection string para as três bibliotecas são semelhantes. Quase qualquer connection string que definas para ADOMD.NET usando Microsoft.AnalysisServices.AdomdClient.AdomdConnection.ConnectionString também funciona para a AMO e para o Analysis Services OLE DB Provider (MSOLAP). Para mais informações, consulte Propriedades da cadeia de conexão.

Verifique as versões instaladas

OLEDDB (MSOLAP)

1. Vá para . Se você tiver mais de uma pasta, escolha o número maior.

2. Clique com o botão direito do rato msolap.dllPropriedadesDetalhes. Verifique a propriedade de versão do produto . Nota: Se o nome do ficheiro for msolap140.dll, é mais antigo do que a versão mais recente e deve ser atualizado.

   caixa de diálogo de detalhes da biblioteca do cliente MSOLAP

AMO

1. Vai a C:\Windows\Microsoft.NET\assembly\GAC_MSIL\Microsoft.AnalysisServices\. Se você tiver mais de uma pasta, escolha o número maior.

2. Clique com o botão direito do mouse Microsoft.AnalysisServicesPropriedadesDetalhes.

   diálogo de detalhes da biblioteca de cliente AMO

ADOMD

1. Vai a C:\Windows\Microsoft.NET\assembly\GAC_MSIL\Microsoft.AnalysisServices.AdomdClient\. Se você tiver mais de uma pasta, escolha o número maior.

2. Clique com o botão direito do rato Microsoft.AnalysisServices.AdomdClientPropriedadesDetalhes.

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

Atualizar manualmente

Normalmente, as bibliotecas de cliente são instaladas e atualizadas automaticamente, juntamente com as ferramentas e os aplicativos cliente que as utilizam. 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, descarregue e execute o pacote Windows Instalador (.msi) para cada biblioteca cliente.

Para baixar e atualizar

1. Clique:

   • Download MSOLAP (amd64) ou Download MSOLAP (x86)
   • Baixar AMO
   • Baixar ADOMD

2. Em Downloads, clique num Pacote do Instalador do Windows para executar a instalação.

3. Em Configuração, clique em Avançar.

4. Leia o contrato de licença. Se concordar, selecione Aceito os termos do contrato de licençae, em seguida, clique em Seguinte.

5. Clique, Instalar.

6. Quando terminar, clique em Concluir.