Skip to content

Commit aef094e

Browse files
buck1eybuck1ey
authored
Live publish
2 parents d017629 + 4e569ae commit aef094e

File tree

2 files changed

+23
-289
lines changed

2 files changed

+23
-289
lines changed

‎powerapps-docs/developer/data-platform/org-service/samples/create-update-multiple.md

Lines changed: 10 additions & 186 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
2-
title: "Sample: Use CreateMultiple and UpdateMultiple (Microsoft Dataverse) | Microsoft Docs" # Intent and product brand in a unique string of 43-59 chars including spaces
3-
description: "This sample shows how to perform bulk create and update operations by using a single web service method call." # 115-145 characters including spaces. This abstract displays in the search result.
4-
ms.date: 05/20/2023
2+
title: "Sample: Use CreateMultiple and UpdateMultiple (preview) (Microsoft Dataverse) | Microsoft Docs" # Intent and product brand in a unique string of 43-59 chars including spaces
3+
description: "This sample shows how to perform bulk create and update operations using several different approaches including the use of CreateMultipleRequest and UpdateMultipleRequest classes. The messages for these request classes are optimized to provide the most performant way to create or update records with Dataverse." # 115-145 characters including spaces. This abstract displays in the search result.
4+
ms.date: 06/01/2023
55
author: divkamath
66
ms.author: dikamath
77
ms.reviewer: jdaly
@@ -16,194 +16,18 @@ contributors:
1616
- phecke
1717
---
1818

19-
# Sample: Use CreateMultiple and UpdateMultiple
19+
# Sample: Use CreateMultiple and UpdateMultiple (preview)
2020

21-
This sample shows how to perform bulk create and update operations using several different approaches including the use of [CreateMultipleRequest](xref:Microsoft.Xrm.Sdk.Messages.CreateMultipleRequest) and [UpdateMultipleRequest](xref:Microsoft.Xrm.Sdk.Messages.UpdateMultipleRequest) classes. The messages for these request classes are optimized to provide the most performant way to create or update records with Dataverse.
21+
[!INCLUDE [cc-beta-prerelease-disclaimer](../../../../includes/cc-beta-prerelease-disclaimer.md)]
2222

23-
This sample is a Visual Studio .NET 6.0 solution that contains five different projects that perform the same operations in different ways so that you can compare the performance of each method.
24-
25-
You can download the sample from [here](https://github.com/microsoft/PowerApps-Samples/tree/master/dataverse/orgsvc/C%23-NETCore/xMultipleSamples).
26-
27-
[!INCLUDE[cc-terminology](../../includes/cc-terminology.md)]
28-
29-
## Prerequisites
30-
31-
- Microsoft Visual Studio 2022
32-
- Access to Dataverse with system administrator or system customizer privileges.
33-
34-
## How to run this sample
35-
36-
1. Clone or download the [PowerApps-Samples](https://github.com/microsoft/PowerApps-Samples) repository.
37-
1. Open the `PowerApps-Samples/dataverse/orgsvc/C#-NETCore/xMultipleSamples/xMultipleSamples.sln` file using Visual Studio 2022.
38-
1. Edit the `appsettings.json` file. Set the connection string `Url` and `Username` parameters as appropriate for your test environment.
39-
1. The environment Url can be found in the Power Platform admin center. It has the form `https://<environment-name>.crm.dynamics.com`.
40-
1. Build the solution, select the desired project as the startup project and press **F5** to run the console application in debug mode.
41-
42-
When the sample runs, you're prompted in the default browser to select an environment user account and enter a password. To avoid having to enter a password every time you run a sample, insert a `Password` parameter into the connection string in the appsettings.json file. For example:
43-
44-
```json
45-
{
46-
"ConnectionStrings": {
47-
"default": "AuthType=OAuth;Url=https://myorg.crm.dynamics.com;[email protected];Password=mypassword;RedirectUri=http://localhost;AppId=51f81489-12ee-4a9e-aaae-a2591f45987d;LoginPrompt=Auto"
48-
}
49-
}
50-
```
51-
> [!TIP]
52-
> You can set a user environment variable named `DATAVERSE_APPSETTINGS` to the file path of the appsettings.json file stored anywhere on your computer. The samples will use that appsettings file if the environment variable exists and is not null. Be sure to log out and back in again after you define the variable for it to take effect. To set an environment variable, go to **Settings** > **System** > **About**, select **Advanced system settings**, and then choose **Environment variables**.
53-
54-
## What this sample does
55-
56-
This sample is a .NET 6.0 Visual Studio 2022 solution that contains five projects that perform the same operations:
57-
58-
1. Create a new custom table named `sample_example` if it doesn't already exist.
59-
1. Prepare a configurable number of `sample_example` entity instances for the custom table representing records to create.
60-
61-
Each record has the `sample_name` column value set with an incrementing number. The first value is `sample record 0000001`.
62-
63-
1. Create the `sample_example` records. Each project uses a different method.
64-
1. Update the set of entity instances by appending text to the `sample_name` attribute.
65-
1. Update the `sample_example` records using the same method they were created.
66-
1. Use a [BulkDeleteRequest](xref:Microsoft.Crm.Sdk.Messages.BulkDeleteRequest) to delete the `sample_example` records created and report on the success of this request.
67-
1. Delete the custom `sample_example` table created in the first step, unless configured not to.
68-
69-
Each project uses a shared set of settings in the `Settings.cs` file that allow you to control:
70-
71-
- `NumberOfRecords`: The number of records to create. The default value is 100 but you can raise it to 1000 or higher.
72-
- `BypassCustomPluginExecution`: Whether custom plug-in logic should be bypassed. This setting is useful to observe the performance impact of plug-ins registered on events for the table.
73-
- `DeleteTable`: Whether to delete the custom `sample_example` table at the end of the sample. If you want to test plug-ins that use events on this table, setting this to true preserves the table so you can run the samples multiple times while testing plug-ins.
74-
75-
The `Settings.cs` file is included in each project. Apply the change in one project and they're set for all of them.
76-
77-
### Supporting examples
78-
79-
The shared `Utility.cs` class contains static methods to perform operations that are common in each sample. These methods aren't the primary focus of the sample, but might be of interest:
80-
81-
|Method |Description |
82-
|---------|---------|
83-
|`TableExists`|Detects whether a table with the specified schema name exists.|
84-
|`BulkDeleteRecordsByIds`|Asynchronously deletes a group of records for a specified table by ID.|
85-
|`IsMessageAvailable`|Detect whether a specified message is supported for the specified table.|
86-
|`CreateExampleTable`|Creates the table used by projects in this solution if it doesn't already exist.|
87-
|`DeleteExampleTable`|Deletes the table used by projects in this solution, unless the `DeleteTable` setting is false.|
88-
89-
## How this sample works
90-
91-
By default the **CreateUpdateMultiple** project should be set as the startup project for the solution. To try any of the other samples, select the project in Solution Explorer and choose **Set as startup project**.
92-
93-
> [!NOTE]
94-
> [Sample: CreateMultiple and UpdateMultiple plug-ins](createmultiple-updatemultiple-plugin.md) is designed to work together with this sample to demonstrate how plug-ins can be migrated from `Create` and `Update` to `CreateMultiple` and `UpdateMultiple` messages.
95-
96-
### Demonstrate
97-
98-
As mentioned in [What this sample does](#what-this-sample-does) above, this sample demonstrates how to create and update records in bulk for a custom table created by the sample. To demonstrate this, it must create a custom table and clean up when you finish running the sample.
99-
100-
Details about each project and the default output are described below:
101-
102-
#### CreateUpdateMultiple
103-
104-
This project uses [CreateMultipleRequest](xref:Microsoft.Xrm.Sdk.Messages.CreateMultipleRequest) and [UpdateMultipleRequest](xref:Microsoft.Xrm.Sdk.Messages.UpdateMultipleRequest) classes to perform bulk create and update operations.
23+
These sample applications on GitHub show how to perform bulk create and update operations using several different approaches including the use of [CreateMultipleRequest](xref:Microsoft.Xrm.Sdk.Messages.CreateMultipleRequest) and [UpdateMultipleRequest](xref:Microsoft.Xrm.Sdk.Messages.UpdateMultipleRequest) classes. The messages for these request classes are optimized to provide the most performant way to create or update records with Dataverse.
10524

106-
This project sends two requests, each attempting to complete operations for the total configured number of records.
107-
108-
The output of this project with 100 records includes:
109-
110-
```
111-
Sending CreateMultipleRequest...
112-
Created 100 records in 1 seconds.
113-
Preparing 100 records to update..
114-
Sending UpdateMultipleRequest...
115-
Updated 100 records in 3 seconds.
116-
```
117-
118-
#### ExecuteMultiple
119-
120-
This project uses the [ExecuteMultipleRequest class](xref:Microsoft.Xrm.Sdk.Messages.ExecuteMultipleRequest) class to perform bulk create and update operations.
121-
122-
Because `ExecuteMultiple` is limited to 1000 requests and the sample may be configured to create more records than 1000, this project chunks the total number of requests into groups of 1000 and sends as many requests as needed to perform the respective operations.
123-
124-
The output of this project with 100 records includes:
125-
126-
```
127-
Preparing 100 records to create...
128-
Sending 1 ExecuteMultipleRequest to create...
129-
Sending ExecuteMultipleRequest 1...
130-
Created 100 records in 4 seconds.
131-
Preparing 100 records to update...
132-
Sending 1 ExecuteMultipleRequest to update...
133-
Sending ExecuteMultipleRequest 1...
134-
Updated 100 records in 4 seconds.
135-
```
136-
137-
The output of this project with 2000 records includes:
138-
139-
```
140-
Preparing 2000 records to create...
141-
Sending 2 ExecuteMultipleRequests to create...
142-
Sending ExecuteMultipleRequest 1...
143-
Sending ExecuteMultipleRequest 2...
144-
Created 2000 records in 58 seconds.
145-
Preparing 2000 records to update...
146-
Sending 2 ExecuteMultipleRequests to update...
147-
Sending ExecuteMultipleRequest 1...
148-
Sending ExecuteMultipleRequest 2...
149-
Updated 2000 records in 76 seconds.
150-
```
151-
152-
#### ParallelCreateUpdate
153-
154-
This project uses the <xref:System.Threading.Tasks.Parallel.ForEachAsync%2A?displayProperty=fullName> together with the [Microsoft.PowerPlatform.Dataverse.Client.ServiceClient.ServiceClient.CreateAsync Method](/dotnet/api/microsoft.powerplatform.dataverse.client.serviceclient.createasync)
155-
and [Microsoft.PowerPlatform.Dataverse.Client.ServiceClient.ServiceClient.UpdateAsync Method](/dotnet/api/microsoft.powerplatform.dataverse.client.serviceclient.updateasync) to perform individual create and update operations using multiple threads.
156-
157-
The number of threads used depends on the [ServiceClient.RecommendedDegreesOfParallelism Property](xref:Microsoft.PowerPlatform.Dataverse.Client.ServiceClient.RecommendedDegreesOfParallelism), which is based on the value of the `x-ms-dop-hint` response header. The `x-ms-dop-hint` response header provides a hint for the Degree Of Parallelism (DOP) that represents a number of threads that should provide good results for a given environment.
158-
159-
The output of this project with 100 records includes:
160-
161-
```
162-
Sending create requests in parallel...
163-
Created 100 records in 3 seconds.
164-
Preparing 100 records to update..
165-
Sending update requests in parallel...
166-
Updated 100 records in 3 seconds.
167-
```
168-
169-
#### ParallelCreateUpdateMultiple
170-
171-
This project uses the <xref:System.Threading.Tasks.Parallel.ForEachAsync%2A?displayProperty=fullName> together with the [Microsoft.PowerPlatform.Dataverse.Client.ServiceClient.ServiceClient.ExecuteAsync Method](/dotnet/api/microsoft.powerplatform.dataverse.client.serviceclient.executeasync) to perform multiple create and update operations using multiple threads.
172-
173-
The number of threads used depends on the [ServiceClient.RecommendedDegreesOfParallelism Property](xref:Microsoft.PowerPlatform.Dataverse.Client.ServiceClient.RecommendedDegreesOfParallelism), which is based on the value of the `x-ms-dop-hint` response header. The `x-ms-dop-hint` response header provides a hint for the Degree Of Parallelism (DOP) that represents a number of threads that should provide good results for a given environment.
174-
175-
The output of this project with 100 records includes:
176-
177-
```
178-
Sending create requests in parallel...
179-
Created 100 records in 1 seconds.
180-
Preparing 100 records to update..
181-
Sending update requests in parallel...
182-
Updated 100 records in 3 seconds.
183-
```
184-
185-
186-
#### SimpleLoop
187-
188-
This project simply loops through the list of prepared Entity instances to perform individual create and update operations sequentially using the [CreateRequest](xref:Microsoft.Xrm.Sdk.Messages.CreateRequest) and [UpdateRequest](xref:Microsoft.Xrm.Sdk.Messages.UpdateRequest) classes.
189-
190-
> [!NOTE]
191-
> This sample represents the case where no effort is applied to maximize throughput. It should represent the worst case for performance.
192-
193-
The output of this project with 100 records includes:
194-
195-
```
196-
Sending create requests one at a time...
197-
Created 100 records in 10 seconds.
198-
Preparing 100 records to update..
199-
Sending update requests one at a time...
200-
Updated 100 records in 12 seconds.
201-
```
202-
203-
### Clean up
25+
This sample is a Visual Studio .NET 6.0 solution that contains five different projects that perform the same operations in different ways so that you can compare the performance of each method.
20426

205-
By default, when each project in the solution completes successfully, all the records created in the custom `sample_example` table are deleted and the `sample_example` table is also deleted. But it's expected that you'll change the `DeleteTable` setting to preserve the table when running each of the samples. Make sure to set it to `true` the last time you run one of the projects so that the table will be deleted.
27+
See the README.md file in each sample for detailed instructions about how to run the sample and what it does.
20628

29+
> [!div class="nextstepaction"]
30+
> [SDK for .NET Create and Update Multiple Sample](https://github.com/microsoft/PowerApps-Samples/blob/master/dataverse/orgsvc/C%23-NETCore/xMultipleSamples/README.md)
20731
20832
### See Also
20933

0 commit comments

Comments
 (0)