Quickstart: Execute an SDK for .NET request (C#)

Artigo
12/05/2024

This topic shows you how to begin using classes in the SDK for .NET assemblies to work with Microsoft Dataverse business data. You will create a minimal console application to connect to your environment's Organization service using the ServiceClient class and execute a web service operation.

Your application will call the IOrganizationService.Execute method passing an instance of the WhoAmIRequest class. The result returned from the web service is a populated WhoAmIResponse.UserId value which is the unique identifier of your Dataverse system user account.

Note

This quick start example does not include exception handling for brevity. This is a minimum code example of what you need to connect to and use the SDK for .NET.

You can obtain the complete code sample from GitHub GetStarted. Consult the program's README for more details.

Prerequisites

Visual Studio (2022 or later)
Internet connection
Logon credentials of a Dataverse system user account for the target environment
URL address of the Dataverse environment you want to connect with
Basic understanding of the Visual C# language

Read the following important information about using a connection string or username/password authentication in application code.

Important

Microsoft recommends that you use the most secure authentication flow available. The authentication flow described in this article requires a very high degree of trust in the application, and carries risks that are not present in other flows. You should only use this flow when other more secure flows, such as managed identities, aren't viable.

Create Visual Studio project

Create a new .NET console app project. For this project we are using Visual Studio 2022 and targeting .NET 6.
In Solution Explorer, right-click the project you created and select Manage NuGet Packages... in the context menu.
Browse for the latest version of the Microsoft.PowerPlatform.Dataverse.Client NuGet package and install it.

Note

Your will be prompted to OK the preview changes, and then select I Accept in the Licence Acceptance dialog.

Add application code

In Solution Explorer, double-click Program.cs to edit that file. Replace the file's contents with the code shown below.

using Microsoft.Crm.Sdk.Messages;
using Microsoft.PowerPlatform.Dataverse.Client;
using Microsoft.Xrm.Sdk;

class Program
{
   // TODO Enter your Dataverse environment's URL and logon info.
   static string url = "https://yourorg.crm.dynamics.com";
   static string userName = "you@yourorg.onmicrosoft.com";
   static string password = "yourPassword";

   // This service connection string uses the info provided above.
   // The AppId and RedirectUri are provided for sample code testing.
   static string connectionString = $@"
   AuthType = OAuth;
   Url = {url};
   UserName = {userName};
   Password = {password};
   AppId = 51f81489-12ee-4a9e-aaae-a2591f45987d;
   RedirectUri = app://58145B91-0C36-4500-8554-080854F2AC97;
   LoginPrompt=Auto;
   RequireNewInstance = True";

   static void Main()
   {
      //ServiceClient implements IOrganizationService interface
      IOrganizationService service = new ServiceClient(connectionString);

      var response = (WhoAmIResponse)service.Execute(new WhoAmIRequest());

      Console.WriteLine($"User ID is {response.UserId}.");


      // Pause the console so it does not close.
      Console.WriteLine("Press the <Enter> key to exit.");
      Console.ReadLine();
   }
}

Change the values for the url, userName, and password as indicated by the // TODO code comment.

Note

You can find your environment URL in the legacy web application under Settings > Customization > Developer Resources or in Power Apps Settings (gear icon) > Developer Resources.

While this code sample places the username/password information in the code for simplicity, other code samples will use the more recommended approach of prompting for that information or storing it in a separate App.config or appsettings.json file.

You can find supported values for AuthType listed in Connection string parameters.

Run the program

Press F5 to run the program. The output should look something like this:

User ID is 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Press any key to exit.

Use the IOrganizationService interface methods

Notice that the Dataverse.Client.ServiceClient this program uses implements the IOrganizationService Interface which includes the Execute method.

To see and understand the IOrganizationService interface a little better, try this:

Go to the reference article for the WhoAmIRequest class.

Copy the example method from that article. It looks like this:

/// <summary>
/// Outputs the data returned from the WhoAmI message
/// </summary>
/// <param name="service">Authenticated client implementing the IOrganizationService interface</param>
static void WhoAmIExample(IOrganizationService service) {

   var response = (WhoAmIResponse)service.Execute(new WhoAmIRequest());

   Console.WriteLine($"OrganizationId:{response.OrganizationId}");
   Console.WriteLine($"BusinessUnitId:{response.BusinessUnitId}");
   Console.WriteLine($"UserId:{response.UserId}");

}

Notice that it accepts an IOrganizationService service instance as the parameter.

Paste this WhoAmIExample method below the Main method in your program

Replace the Main method in your program with this:

    static void Main()
 {
     //ServiceClient implements IOrganizationService interface
     IOrganizationService service = new ServiceClient(connectionString);

     WhoAmIExample(service: service);

     // Pause the console so it does not close.
     Console.WriteLine("Press the <Enter> key to exit.");
     Console.ReadLine();
 }

Run the sample again and you should see something like:

OrganizationId:00aa00aa-bb11-cc22-dd33-44ee44ee44ee
BusinessUnitId:11bb11bb-cc22-dd33-ee44-55ff55ff55ff
UserId:22cc22cc-dd33-ee44-ff55-66aa66aa66aa
Press the <Enter> key to exit.

Next Steps

Now that you have a simple console program that connects to Dataverse, use this project to try other methods and messages. You can use this Quick Start console application project to do ad-hoc testing.

Try other IOrganizationService interface methods

Tip

In our documentation you can find many example methods like this WhoAmIExample which accept an IOrganizationService service parameter.

Try the examples for these IOrganizationService methods methods:

Try other messages

You can find other messages that you can invoke using the Execute method in these name spaces:

Learn to work with record data

The following articles explain how to work with business data in Dataverse tables:

Explore our code samples

You can find SDK for .NET sample code in our GitHub repository at PowerApps-Samples/dataverse/orgsvc.

Use ServiceClient extensions

In addition to implementing the IOrganizationService interface, ServiceClient offers extension methods beyond the core methods defined by IOrganizationService and the capability to enable logging with ILogger. Learn more about using ServiceClient

Partilhar via