Use the Organization service

Article
03/16/2023
2 minutes to read

The Organization web service provides access to the business data, data table definitions (metadata), and data operations supported by the Dataverse platform. The Organization service is one of two Dataverse web services, the other being the Discovery service used to access Dataverse environment details.

Applications may access Dataverse through either of two programming interfaces. The first interface is the Dataverse SDK for .NET which is described later in this topic. The other interface is the Dataverse Web API. You can write code using either or both of these programming interfaces in the same application.

There are certain development scenarios in which the Organization service and the Dataverse SDK for .NET must be used (not the Web API). When writing custom code to extend the functionality of Dataverse, such as when creating plug-ins and custom workflow activities, you must build your code using the .NET Framework and Dataverse SDK.

Obtaining the SDK assemblies

The Organization service is accessed from .NET Framework or .NET Core based applications by using provided classes in the Dataverse SDK for .NET assemblies. For .NET Framework only development, the SDK assemblies are available in the Microsoft.CrmSdk.CoreAssemblies NuGet package. For .NET Framework or .NET Core development, the SDK assemblies are available in the Microsoft.PowerPlatform.Dataverse.Client NuGet package.

After adding the NuGet package to your Visual Studio project, you then have access to the namespaces and classes that enable your application to interact with the Organization and Discovery web services.

Interacting with the Organization service

In this section we cover some key concepts about using provided SDK classes to connect with the web services and perform operations.

Establishing a web service connection

The IOrganizationService interface provides a connection to the Organization service enabling applications to work with business data, and table and column definitions. There are two implementations of this interface in the SDK: CrmServiceClient and ServiceClient. For new application development, you should be using the ServiceClient class which supports newer authentication technologies (MSAL) and has a few additional features not available in CrmServiceClient. However, both client classes are mostly the same from an API perspective. You will see code samples in this documentation using either of these classes, and it is fairly easy to convert code that uses CrmServiceClient to use ServiceClient.

More information: Transition apps to Dataverse ServiceClient, IOrganizationService Interface

Web service operations

In the Dataverse SDK, web service operations are initiated by sending messages or message requests to the service. Each message has a name which indicates the purpose of the message, and the corresponding request class name is based on that message name. For example, to create a row of data in a table, you populate a create request with data and have the service client send (Execute) this request to the Organization service. The operation is 'create' and the message request is named CreateRequest. After executing a request, the service returns a response class object (e.g., CreateResponse) which contains an execution status and results data. This pattern is the same for the other operations that the service supports.

Take a look at the available message request and response classes in the Microsoft.Xrm.Sdk.Messages and Microsoft.Crm.Sdk.Messages namespaces.

About the legacy SOAP endpoint

The Organization service endpoint that was introduced in 2011, known as the SOAP endpoint, has been deprecated for some time now. This means that it will continue to work and be supported until we remove it. We have also announced that we will update the SDK for .NET assemblies so that they will continue to work after the endpoint is removed. This means that there will be updated SDK for .NET assemblies available before the endpoint is removed. Developers will be required to update their code to use these new assemblies at some point in the future. The key takeaway is that developers will access the Organization service using the SDK for .NET and ignore the endpoint and its protocol. More information: Transition apps to Dataverse ServiceClient

Since the Web API uses a different endpoint, it is not affected by this 2011 SOAP endpoint deprecation.

Next steps

Let's write some code! Quickstart: Organization service sample (C#)