|
| 1 | +--- |
| 2 | +title: "Transition client applications to Dataverse ServiceClient | Microsoft Docs" # Intent and product brand in a unique string of 43-59 chars including spaces |
| 3 | +description: "Learn about the benefits of and the changes needed to transitions your client application to use Dataverse ServiceClient class for web service connections." # 115-145 characters including spaces. This abstract displays in the search result. |
| 4 | +ms.custom: "" |
| 5 | +ms.date: 06/01/2022 |
| 6 | +ms.reviewer: "pehecke" |
| 7 | +ms.topic: "article" |
| 8 | +author: "phecke" # GitHub ID |
| 9 | +ms.service: powerapps |
| 10 | +ms.subservice: dataverse-developer |
| 11 | +ms.author: "pehecke" # MSFT alias of Microsoft employees only |
| 12 | +manager: "kvivek" # MSFT alias of manager or PM counterpart |
| 13 | +search.audienceType: |
| 14 | + - developer |
| 15 | +search.app: |
| 16 | + - PowerApps |
| 17 | + - D365CE |
| 18 | +--- |
| 19 | + |
| 20 | +# Transition apps to Dataverse ServiceClient |
| 21 | + |
| 22 | +We are transitioning from [Microsoft Dataverse SDK for .NET](developer-tools.md#dataverse-sdk-for-net) to include a new web service client that uses MSAL for authentication. This article contains the information you need to understand why we are making these changes, what is impacted, and how to update your client applications so they continue to function as expected. |
| 23 | + |
| 24 | +> [!NOTE] |
| 25 | +> All our existing developer documentation and sample code use the Dataverse SDK APIs found in the [CoreAssemblies](https://www.nuget.org/packages/Microsoft.CrmSdk.CoreAssemblies/) NuGet package. Only this article that you are reading describes the newer [Dataverse.Client](https://www.nuget.org/packages/Microsoft.PowerPlatform.Dataverse.Client/) NuGet package and the changes required to make use of it. More documentation and sample code updates are coming. |
| 26 | +
|
| 27 | +## Why the change? |
| 28 | + |
| 29 | +There are quite a few good reasons for the changes to the Dataverse SDK for .NET. A few are called out below. |
| 30 | + |
| 31 | +### Cross-platform application support |
| 32 | + |
| 33 | +The new Dataverse [ServiceClient](xref:Microsoft.PowerPlatform.Dataverse.Client.ServiceClient) class supports .NET Core development. Navigate to [Microsoft.PowerPlatform.Dataverse.Client](https://www.nuget.org/packages/Microsoft.PowerPlatform.Dataverse.Client/) and select the **Frameworks** tab to see what build targets are supported. |
| 34 | + |
| 35 | +### MSAL authentication |
| 36 | + |
| 37 | +Microsoft Azure Active Directory Authentication Library (ADAL) support ends soon. Microsoft Authentication Library (MSAL) is the recommended authentication API going forward. Our new [ServiceClient](xref:Microsoft.PowerPlatform.Dataverse.Client.ServiceClient) API use MSAL while our older [CrmServiceClient](xref:Microsoft.Xrm.Tooling.Connector.CrmServiceClient) API uses ADAL. |
| 38 | + |
| 39 | +### Performance and functional benefits |
| 40 | + |
| 41 | +The Dataverse `ServiceClient` class supports a smaller interface surface, inline authentication by instance, and `ILogger`. As for inline authentication, you can pass a custom authentication handler function to the `ServiceClient` constructor. In this way you can have one authentication handler per web service connection instead of just one per process. |
| 42 | + |
| 43 | +## What is impacted? |
| 44 | + |
| 45 | +Below is a quick summary of the impact to certain types of coding projects. |
| 46 | + |
| 47 | +- Plug-ins or custom workflow activities - no changes, just business as usual |
| 48 | + |
| 49 | +- New or existing online applications - this article is definitely for you |
| 50 | + |
| 51 | +- On-premise applications - this article is not for you, yet |
| 52 | + |
| 53 | +## What do you need to do? |
| 54 | + |
| 55 | +The good news is that the class member signatures of `ServiceClient` and `CrmServiceClient` are the same, except for the class names themselves being slightly different. Application code should not need any significant changes. |
| 56 | + |
| 57 | +### .NET Framework based (online) application projects |
| 58 | + |
| 59 | +To update your application projects, follow these steps. |
| 60 | + |
| 61 | +1. Remove the older [CoreAssemblies](https://www.nuget.org/packages/Microsoft.CrmSdk.CoreAssemblies/) (and related) NuGet packages from your project. |
| 62 | +1. Add the newer [Dataverse.Client](https://www.nuget.org/packages/Microsoft.PowerPlatform.Dataverse.Client/) NuGet package to your project. |
| 63 | +1. Change every mention of the [CrmServiceClient](xref:Microsoft.Xrm.Tooling.Connector.CrmServiceClient) class to [ServiceClient](xref:Microsoft.PowerPlatform.Dataverse.Client.ServiceClient) in your code. |
| 64 | +1. Fix any namespace mismatch as the new `ServiceClient` class is now in the `Microsoft.PowerPlatform.Dataverse.Client` namespace. |
| 65 | + |
| 66 | +### .NET Core based (online) projects |
| 67 | + |
| 68 | +Simply add the [Dataverse.Client](https://www.nuget.org/packages/Microsoft.PowerPlatform.Dataverse.Client/) NuGet package to your projects, add code to call the Dataverse SDK APIs, and build. |
| 69 | + |
| 70 | +### Plug-ins or custom workflow activities |
| 71 | + |
| 72 | +Nothing really for you to do here. Continue using the [Microsoft.CrmSdk.CoreAssemblies](https://www.nuget.org/packages/Microsoft.CrmSdk.CoreAssemblies/) (and related) NuGet packages with .NET Framework 4.6.2. |
| 73 | + |
| 74 | +### On-premise clients |
| 75 | + |
| 76 | +Leave your application projects and code as is. Continue using the Microsoft.CrmSdk.CoreAssemblies NuGet package and `CrmServiceClient`class. However, plan to update your projects from using any custom service clients to instead use the `CrmServiceClient` or `ServiceClient` in the near future. See the planned [timeline](#timeline) for 2011 SOAP endpoint shutdown below. |
| 77 | + |
| 78 | +> [!NOTE] |
| 79 | +> If you are using custom authentication with `CrmServiceClient`, you can continue to use your custom authentication code with `ServiceClient`. |
| 80 | +
|
| 81 | +## Timeline |
| 82 | + |
| 83 | +The following table lists some important dates to keep in mind. |
| 84 | + |
| 85 | +| Timeframe | Event | |
| 86 | +| --- | --- | |
| 87 | +|June 2022|GA release of the [Microsoft.PowerPlatform.Dataverse.Client](https://www.nuget.org/packages/Microsoft.PowerPlatform.Dataverse.Client/) NuGet package| |
| 88 | +|Fall 2022|Planned shutdown of the 2011 SOAP endpoint for access by client applications not using our service clients (`CrmServiceClient` or `ServiceClient`)| |
| 89 | +|December 2022|Microsoft support for ADAL ends| |
| 90 | + |
| 91 | +### See also |
| 92 | + |
| 93 | +[ServiceClient code samples](https://github.com/microsoft/PowerApps-Samples/tree/master/cds/orgsvc/C%23-NETCore/ServiceClient) |
| 94 | +[Overview of the Microsoft Authentication Library (MSAL)](/azure/active-directory/develop/msal-overview) |
| 95 | +[Migrate applications to the Microsoft Authentication Library (MSAL)](/azure/active-directory/develop/msal-migration) |
| 96 | + |
| 97 | +[!INCLUDE[footer-include](../../includes/footer-banner.md)] |
0 commit comments