Biblioteki klienckie usług Analysis Services

Dotyczy: SQL Server Analysis Services Azure Analysis Services Fabric/Power BI Premium

Biblioteki klienckie są niezbędne, aby aplikacje klienckie i narzędzia łączyły się z usługami Analysis Services. Aplikacje klienckie firmy Microsoft, takie jak Power BI Desktop, Excel, SQL Server Management Studio (SSMS) i rozszerzenie projektów usług Analysis Services dla programu Visual Studio, instalują wszystkie trzy biblioteki klienckie i aktualizują je wraz z regularnymi aktualizacjami aplikacji. Niestandardowe aplikacje klienckie dla usług Analysis Services mogą również wymagać zainstalowania co najmniej jednej z tych bibliotek klienckich. Nowe wersje bibliotek klienckich są aktualizowane w przybliżeniu co miesiąc.

Ważne: Przed uzyskaniem najnowszych wersji zapoznaj się z Uwagi i ograniczenia.

Pobierz najnowszą wersję

Instalator Windows

Uwaga: Instalatory Windows dla obiektów zarządzania usługami Analysis Services (AMO/TOM) i ADOMD nie będą już aktualizowane i nie będą dostępne po 31 grudnia 2024 r. Aplikacje uzależnione od tych plików do pobrania Instalatora Windows powinny być migrowane do pakietów NuGet.

Pakiety NuGet

Obiekty zarządzania usługami Analysis Services (AMO/TOM) i biblioteki klienta ADOMD są dostępne jako pakiety do zainstalowania z NuGet.org. Zaleca się stanowczo przeprowadzenie migracji do odwołań NuGet zamiast korzystania z Instalatora Windows.

Zestawy pakietów NuGet AssemblyVersion są zgodne z semantycznym wersjonowaniem: MAJOR.MINOR.PATCH. Odwołania NuGet ładują oczekiwaną wersję, nawet jeśli istnieje inna wersja w usłudze GAC (wynikająca z instalacji MSI). Poprawka PATCH jest zwiększana dla każdej wersji. Wersje AMO i ADOMD są synchronizowane.

Począwszy od lipca 2024 r., pakiety AMO i ADOMD zawierają wersje z wieloma środowiskami uruchomieniowymi dla wszystkich obsługiwanych docelowych środowisk uruchomieniowych, zarówno .NET FX, jak i .NET Core; Wcześniejsze wersje pakietów przeznaczonych tylko dla pojedynczego środowiska uruchomieniowego ( .NET FX lub .NET Core) są dostępne na potrzeby zgodności z poprzednimi wersjami, ale nie są już aktualizowane.

Od września 2022 r. komunikacja oparta na protokole HTTP z usługami w chmurze, takimi jak Power BI i Azure Analysis Services, została znacznie ulepszona w przypadku AMO (AMO/TOM) i ADOMD .Net Core (wersja 19.48.0.0). Zaleca się zaktualizowanie do najnowszej wersji w celu skorzystania z ulepszeń wydajności.

Od lutego 2021 r. obsługa środowiska uruchomieniowego platformy .NET Core jest dostępna dla pakietów klienta AMO i ADOMD. Istnieje jednak kilka scenariuszy, które nie są obsługiwane przez wersje platformy .NET Core. Aby dowiedzieć się więcej, zobacz aspekty i ograniczenia w dalszej części tego artykułu.

AMO i ADOMD

Uwaga:

Nowe pakiety z wieloma środowiskami uruchomieniowymi nie mają już sufiksu ".retail.amd64" w tożsamości pakietu i są teraz po prostu nazywane Microsoft.AnalysisServices i Microsoft.AnalysisServices.AdomdClient.

Starsze pakiety .NET Framework i .NET Core są nadal dostępne w nuget.org w celu zapewnienia zgodności wstecznej, zachowując starą tożsamość z sufiksem ".retail.amd64" dla platformy .NET Framework i sufiksem ".NetCore.retail.amd64" dla platformy .NET Core.

Minimalna wymagana wersja

Protokół Transport Layer Security (TLS) w wersji 1.0/1.1 został przestarzały w usłudze Microsoft Entra ID 30 czerwca 2021 r. Protokół TLS 1.2 lub nowszy jest teraz wymagany. Protokół TLS 1.2 nie jest obsługiwany we wcześniejszych wersjach bibliotek klienckich usług Analysis Services. Nowsze wersje biblioteki klienta obejmują obsługę protokołu TLS 1.2 i nowszych oprócz innych ważnych ulepszeń zabezpieczeń.

Aby zminimalizować ryzyko i potencjalne luki w zabezpieczeniach, począwszy od 30 czerwca 2021 r., zwiększone zabezpieczenia w usługach Azure Analysis Services i Power BI wymagają następujących lub wyższych wersji:

Zagadnienia i ograniczenia

AMO i ADOMD

Począwszy od wersji 19.84.6, obsługa platformy .NET FX 4.5 i .NET Core 3.0 w zarządzanych zestawach nie jest już dostępna. Zestawy AS po stronie klienta są teraz udostępniane z obsługą platformy .NET FX 4.7.2, a także platform .NET 6.0 i .NET 8.0.

Począwszy od wersji 19.82.0.0, AMO i ADOMD obsługują profile zasadnicze usługi do uwierzytelniania, jak w poniższym przykładzie ciągu połączenia. Aby dowiedzieć się więcej, zobacz Używanie profilów jednostki usługi do zarządzania danymi klientów w aplikacjach wielodostępnych. Użytkownicy nie mogą łączyć się z obszarami roboczymi skojarzonymi z licencją premium Per-User przy użyciu profilów głównych usługi za pośrednictwem punktu końcowego 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>

Począwszy od wersji 19.67.0, obiekty łączności, takie jak Microsoft.AnalysisServices.AdomdClient.AdomdConnection i Microsoft.AnalysisServices.Server, obsługują nową właściwość AccessToken, która umożliwia ulepszony sposób przekazywania zewnętrznych tokenów OAuth do użycia przez warstwę łączności XMLA. Aby dowiedzieć się więcej, zobacz właściwości parametrów połączenia — Identyfikator użytkownika=...; Password =.

Począwszy od wersji 19.42.0.4, ADOMD.NET i AMO/TOM używają biblioteki MSAL (Microsoft.Identity.Client) w wersji 4.43.0 lub nowszej zamiast biblioteki ADAL do uwierzytelniania użytkowników przy użyciu identyfikatora Entra firmy Microsoft podczas nawiązywania połączenia z usługami opartymi na chmurze, takimi jak Power-BI i Azure Analysis Services. Jeśli Twoja aplikacja lub inny składnik, od którego aplikacja zależy, używa biblioteki MSAL, może być konieczne zaktualizowanie ustawień przekierowania powiązań aplikacji, jeśli występują konflikty między wersjami MSAL ładowanymi przez składniki.

AMO i ADOMD .Net Core

Obsługiwane scenariusze obejmują połączenia z usługami Azure Analysis Services, Power BI Premium i SQL Server Analysis Services. Łączność oparta na protokole TCP jest obsługiwana tylko dla komputerów z systemem Windows.

Logowanie interakcyjne przy użyciu identyfikatora Entra firmy Microsoft jest obsługiwane tylko dla komputerów z systemem Windows. Środowisko uruchomieniowe programu .NET Core Desktop jest wymagane.

Zależność w biblioteki MSAL wymaga wersji 4.43.0 lub nowszej.

Wersja 19.14.0 bibliotek klienckich platformy .Net Core wprowadziła obsługę wersji zapoznawczej dla publikowania Self-Contained (zarówno w opublikowanym katalogu, jak i w trybie pojedynczego pliku), oprócz obsługi użycia przez projekty platformy .NET 5.0. Rozwiązano kilka problemów związanych z łącznością z usługami SQL Server Analysis Services, które zostały zidentyfikowane w poprzedniej wersji.

W wersji 19.12.7.2 bibliotek klienckich platformy .Net Core wprowadzono obsługę usług SQL Server Analysis Services. Niższe wersje zapoznawcza obsługują tylko modele semantyczne usług Azure Analysis Services i Power BI.

AMO

Począwszy od wersji 19.84.6, obsługa TMDL w AMO\TOM jest uznawana za będącą w statusie General-Availability i nie będzie żadnych zmian powodujących niezgodność w interfejsie API.

W wersji 19.12.3.0 biblioteki klienta AMO wprowadzono nowe wyliczenie Microsoft.AnalysisServices.DataType. Jednak poprzednie wyliczenie Microsoft.AnalysisServices.Tabular.DataType nadal istnieje. Jeśli kod odwołuje się do poprzedniego wyliczenia jako DataType w pliku kodu z instrukcjami dla obu przestrzeni nazw (Microsoft.AnalysisServices, Microsoft.AnalysisServices.Tabular), ze względu na niejednoznaczność, można napotkać błąd kompilacji. Aby rozwiązać ten problem, należy w pełni zakwalifikować odwołanie do wyliczenia.

Wersja 19.61.1.4 biblioteki klienta AMO wprowadza zmianę zachowania wycofywania transakcji Microsoft.AnalysisServices.Server. We wcześniejszych wersjach, wywołanie Server.RollbackTransaction() wysyła żądanie do silnika, aby wycofać transakcję, a następnie próbuje wycofać lokalne zmiany. W przeciwieństwie do wcześniejszych wersji, w wersji 19.61.1.4 lub nowszej, jeśli nie można bezpiecznie wycofać lokalnych zmian, tabelaryczne bazy danych zawarte w transakcji blokują wszelkie dodatkowe zmiany, dopóki nie zostaną w pełni zsynchronizowane, a przestarzałe zmiany z transakcji, które zostały wycofane, zostaną usunięte. InvalidOperationException jest zgłaszana po wprowadzeniu zmiany w odpowiedniej tabelarycznej bazie danych. Jeśli kod wywołuje Server.RollbackTransaction(), zaleca się wykonanie tego wywołania za pomocą pełnej synchronizacji [Database.Refresh(true)] dla każdej tabelarycznej bazy danych zmodyfikowanej w ramach transakcji.

Począwszy od wersji 19.77.0, przy klonowaniu bądź kopiowaniu MetadataObject do innego wystąpienia MetadataObject przy użyciu modelu obiektów tabelarycznych (TOM), TOM zwraca wartość null dla właściwości, które odwołują się do obiektów zewnętrznych poza bezpośrednim drzewem obiektów podrzędnych MetadataObject. Należy dodać sklonowane wystąpienie MetadataObject do modelu semantycznego, aby można było rozpoznać odwołania krzyżowe do obiektów spoza drzewa MetadataObject.

Na przykład podczas klonowania tabeli z partycją, która odwołuje się do nazwanego wyrażenia w jednostce EntityPartitionSource, właściwość ExpressionSource elementu EntityPartitionSource zwraca wartość null, dopóki sklonowana tabela nie zostanie dodana do modelu semantycznego, tak jak w poniższym fragmencie kodu, aby można było rozwiązać sklonowane odwołanie ExpressionSource. Klon musi zostać dodany do modelu, ponieważ nazwane wyrażenie jest elementem członkowskim kolekcji Expressions modelu, a nie częścią drzewa tabel obiektów podrzędnych.

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

ADOMD

Począwszy od usługi ADOMD (zarówno .NET Framework, jak i .NET Core) w wersji 19.61.1.4, kompresja jest w pełni dostępna w warstwie transportu XMLA. Poprzednie wersje po wersji 19.55.3.1 zaimplementowały częściową obsługę kompresji. Raporty dotyczące problemów z tymi wersjami zostały odebrane. Te problemy zostały rozwiązane w ramach wersji 16.61.1.4. Pamiętaj o uaktualnieniu do wersji 19.61.1.4 lub nowszej, jeśli występują problemy związane z kompresją.

MSOLAP

Począwszy od wersji 16.0.139.27, MSOLAP obsługuje profile jednostki usługi do uwierzytelniania, jak w poniższym przykładzie parametrów połączenia. Aby dowiedzieć się więcej, zobacz Używanie profilów jednostki usługi do zarządzania danymi klientów w aplikacjach wielodostępnych.

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>

Począwszy od wersji 16.0.134.22, MSOLAP obsługuje dyskretne jednokrotne Sign-On (SSO) przy użyciu Menedżera kont sieci Web (WAM), dostępnego w systemie Windows 10 lub nowszym, a także windows Server 2019 i nowszych. Po otwarciu nowego połączenia HTTP usługa MSOLAP uzyskuje token dostępu w następujący sposób:

1. Jeśli buforowanie tokenów jest włączone i odpowiedni token jest dostępny w pamięci podręcznej, msOLAP używa buforowanego tokenu.
2. Jeśli odpowiedni token buforowany jest niedostępny, msOLAP próbuje uzyskać token dostępu dyskretnie za pośrednictwem WAM.
3. Jeśli logowanie jednokrotne przy użyciu WAM nie powiodło się, funkcja MSOLAP powraca do uwierzytelniania interakcyjnego i pojawi się okno logowania.

Użytkownicy mogą pominąć dyskretny przepływ jednokrotnego logowania i natychmiast uruchomić środowisko uwierzytelniania interaktywnego, podając pusty identyfikator użytkownika w parametrach połączenia (User ID='').

Począwszy od wersji 16.0.43.20, funkcja MSOLAP używa biblioteki MSAL (Microsoft.Identity.Client) w wersji 4.43.0 lub nowszej zamiast biblioteki ADAL do uwierzytelniania użytkowników za pomocą identyfikatora Microsoft Entra podczas nawiązywania połączenia z usługami opartymi na chmurze, takimi jak Power-BI i Azure Analysis Services. Jeśli Twoja aplikacja lub inny składnik, od którego zależy aplikacja, korzysta z biblioteki MSAL, konieczne może być zaktualizowanie ustawień przekierowania powiązań aplikacji, jeśli istnieją konflikty między wersjami biblioteki MSAL ładowanymi przez składniki.

W wersji 16.0.4.17 OLEDB (MSOLAP) wykryto regresję związaną z połączeniami z systemami opartymi na chmurze przy użyciu identyfikatora Microsoft Entra ID. Został on naprawiony w wersji 16.0.20.201. Ze względu na charakter problemu zainstalowana wersja 16.0.4.17, a także jakakolwiek inna wersja przed wersją 16.0.20.201 nie może zostać poprawiona przez supgradację dostawcy, nawet jeśli instalacja jest uruchamiana w trybie naprawy. Zaleca się całkowite odinstalowanie wersji 16.0.4.17 [lub inną problematyczną], a następnie zainstalowanie wersji 16.0.20.201 lub nowszej.

We wcześniejszej wersji biblioteka MSOLAP została zaktualizowana w celu nawiązania połączenia z usługami Analysis Services opartymi na chmurze przy użyciu zarządzanej biblioteki Microsoft Authentication Library (MSAL). Począwszy od wersji 16.0.87.16, instalator MSOLAP nie instaluje już oryginalnego natywnego składnika Biblioteki uwierzytelniania usługi Azure Active Directory (ADAL).

Omówienie bibliotek klienckich

Usługi Analysis Services korzystają z trzech bibliotek klienckich. ADOMD.NET i AMO (obiekty zarządzania Analysis Services) to zarządzane biblioteki klienckie. Dostawca OLE DB usług Analysis Services (MSOLAP DLL) to natywna biblioteka kliencka. Zazwyczaj wszystkie trzy są instalowane w tym samym czasie.

Aplikacje klienckie firmy Microsoft, takie jak Power BI Desktop i Excel, instalują wszystkie trzy biblioteki klienckie i aktualizują je, gdy są dostępne nowe wersje. W zależności od wersji lub częstotliwości aktualizacji niektóre biblioteki klienckie mogą nie być najnowszymi wersjami wymaganymi przez usługi Azure Analysis Services i Power BI. To samo dotyczy aplikacji niestandardowych lub innych interfejsów, takich jak AsCmd, TOM, ADOMD.NET. Te aplikacje wymagają ręcznego lub programowego instalowania bibliotek. Biblioteki klienta do ręcznej instalacji są zawarte w pakietach funkcji programu SQL Server jako pakietach dystrybucyjnych. Jednak te biblioteki klienckie są powiązane z wersją programu SQL Server i mogą nie być najnowsze. Upewnij się, że zawsze instalujesz najnowszą wersję, którą można pobrać z tego artykułu.

Typy bibliotek klienta

Dostawca OLE DB usług Analysis Services (MSOLAP)

Dostawca OLE DB dla Analysis Services (MSOLAP) jest natywną biblioteką kliencką dla połączeń z bazami danych Analysis Services. Jest używany pośrednio przez ADOMD.NET i AMO, delegując żądania połączeń do dostawcy danych. Możesz również wywołać dostawcę OLE DB bezpośrednio z kodu aplikacji.

Dostawca OLE DB usług Analysis Services jest instalowany automatycznie przez większość narzędzi i aplikacji klienckich używanych do uzyskiwania dostępu do baz danych usług Analysis Services. Należy go zainstalować na komputerach używanych do uzyskiwania dostępu do danych usług Analysis Services.

Dostawcy OLE DB są często określeni w parametrach połączenia. Parametr połączenia usług Analysis Services używa innej nomenklatury dla dostawcy OLE DB: MSOLAP.<wersja>.dll.

AMO

AMO to zarządzana biblioteka klienta używana do administrowania serwerem i definicji danych. Jest on instalowany i używany przez narzędzia i aplikacje klienckie. Na przykład program SQL Server Management Studio (SSMS) używa usługi AMO do nawiązywania połączenia z usługami Analysis Services. Połączenie korzystające z usługi AMO jest zwykle minimalne, składające się z "data source=\<servername>". Po nawiązaniu połączenia można użyć interfejsu API do pracy z kolekcjami baz danych i głównymi obiektami. Zarówno program Visual Studio, jak i program SSMS używają programu AMO do nawiązywania połączenia z wystąpieniem usług Analysis Services.

ADOMD

ADOMD.NET to zarządzana biblioteka klienta danych używana do wykonywania zapytań dotyczących danych usług Analysis Services. Jest on instalowany i używany przez narzędzia i aplikacje klienckie.

Podczas nawiązywania połączenia z bazą danych właściwości parametrów połączenia dla wszystkich trzech bibliotek są podobne. Prawie każdy ciąg połączenia zdefiniowany dla ADOMD.NET przy użyciu Microsoft.AnalysisServices.AdomdClient.AdomdConnection.ConnectionString również działa dla AMO i dostawcy OLE DB usług Analysis Services (MSOLAP). Aby dowiedzieć się więcej, zobacz właściwości ciągu połączenia.

Sprawdzanie zainstalowanych wersji

OLEDDB (MSOLAP)

1. Przejdź do C:\Program Files\Microsoft Analysis Services\AS OLEDB\. Jeśli masz więcej niż jeden folder, wybierz większą liczbę.

2. Kliknij prawym przyciskiem myszy msolap.dll>Właściwości>Szczegóły. Sprawdź właściwość wersji produktu . Uwaga: jeśli nazwa pliku jest msolap140.dll, jest starsza niż najnowsza wersja i powinna zostać uaktualniona.

   okno dialogowe

AMO

1. Przejdź do C:\Windows\Microsoft.NET\assembly\GAC_MSIL\Microsoft.AnalysisServices\. Jeśli masz więcej niż jeden folder, wybierz większą liczbę.

2. Kliknij prawym przyciskiem myszy Microsoft.AnalysisServices>Właściwości>Szczegóły.

   okno dialogowe

ADOMD

1. Przejdź do C:\Windows\Microsoft.NET\assembly\GAC_MSIL\Microsoft.AnalysisServices.AdomdClient\. Jeśli masz więcej niż jeden folder, wybierz większą liczbę.

2. Kliknij prawym przyciskiem myszy Microsoft.AnalysisServices.AdomdClient>Właściwości>Szczegóły.

   okno dialogowe

Ręczne aktualizowanie

Biblioteki klienckie są zwykle instalowane i aktualizowane automatycznie wraz z narzędziami i aplikacjami klienckimi, które ich używają. Jednak w niektórych przypadkach biblioteki klienckie mogą nie być aktualizowane automatycznie i każda z nich musi być aktualizowana ręcznie. Aby zaktualizować ręcznie, pobierz i uruchom pakiet Instalatora Windows (.msi) dla każdej biblioteki klienta.

Aby pobrać i zaktualizować

1. Kliknij:

   • pobierz MSOLAP (amd64) lub pobierz MSOLAP (x86)
   • pobierz AMO
   • Pobierz ADOMD

2. W Pliki do pobraniakliknij pakiet instalacyjny Windows, aby uruchomić konfigurację.

3. W Konfiguracji kliknij pozycję Dalej.

4. Przeczytaj umowę licencyjną. Jeśli zgadzasz się, wybierz pozycję Akceptuję warunki umowy licencyjnej, a następnie kliknij przycisk Dalej.

5. Kliknij pozycję Zainstaluj.

6. Po zakończeniu kliknij Zakończ.