Live publish for 10 February 2024.

bishalgoswami · web-flow · commit 8a201cb52342 · 2024-02-10T06:00:08.000+05:30
diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json
@@ -1,5 +1,10 @@
 {
   "redirections": [
+   {
+      "source_path": "powerapps-docs/developer/data-platform/upsertmultiple.md",
+      "redirect_url": "bulk-operations#upsertmultiple",
+      "redirect_document_id": "false"
+   },
    {
       "source_path": "powerapps-docs/developer/data-platform/org-service/extend-code-generation-tool.md",
       "redirect_url": "/dynamics365/customerengagement/on-premises/developer/org-service/extend-code-generation-tool",
diff --git a/powerapps-docs/developer/data-platform/TOC.yml b/powerapps-docs/developer/data-platform/TOC.yml
@@ -49,8 +49,6 @@
     - name: Bulk Operation messages
       href: bulk-operations.md
       items:
-      - name: Use UpsertMultiple (preview)
-        href: upsertmultiple.md
       - name: Use DeleteMultiple (preview)
         href: deletemultiple.md
     - name: Create your own messages
diff --git a/powerapps-docs/developer/data-platform/best-practices/business-logic/avoid-batch-requests-plugin.md b/powerapps-docs/developer/data-platform/best-practices/business-logic/avoid-batch-requests-plugin.md
@@ -1,26 +1,15 @@
 ---
-title: "Do not use batch request types in plug-ins and workflow activities | MicrosoftDocs"
+title: "Don't use batch request types in plug-ins and workflow activities | MicrosoftDocs"
 description: "You shouldn't use ExecuteMultipleRequest or ExecuteTransactionRequest message request classes within the context of a plug-in or workflow activity."
-services: ''
 suite: powerapps
-documentationcenter: na
 author: jowells
-editor: ''
-tags: ''
-
-ms.devlang: na
-ms.topic: article
-ms.tgt_pltfrm: na
-ms.workload: na
-ms.date: 12/06/2019
+ms.date: 02/08/2024
 ms.subservice: dataverse-developer
 ms.author: jowells
 search.audienceType: 
   - developer
 ---
-# Do not use batch request types in plug-ins and workflow activities
-
-
+# Don't use batch request types in plug-ins and workflow activities
 
 **Category**: Usage, Reliability, Performance
 
@@ -30,28 +19,38 @@ search.audienceType:
 
 ## Symptoms
 
-Due to their long-running nature, using <xref:Microsoft.Xrm.Sdk.Messages.ExecuteMultipleRequest> or <xref:Microsoft.Xrm.Sdk.Messages.ExecuteTransactionRequest> message request classes within the context of a plug-in or workflow activity expose sandbox-isolated plug-in types to the two-minute (120000ms) channel timeout exception and can degrade the user experience for synchronous registrations.
+User experiences are degraded and time out errors might occur when you use *batch request types* in plug-ins and workflow activities that occur within synchronous operations.
+
+The following message request classes are considered *batch request types* because they perform operations on multiple records within a single request:
+
+- <xref:Microsoft.Xrm.Sdk.Messages.ExecuteMultipleRequest>
+- <xref:Microsoft.Xrm.Sdk.Messages.ExecuteTransactionRequest>
+- <xref:Microsoft.Xrm.Sdk.Messages.CreateMultipleRequest>
+- <xref:Microsoft.Xrm.Sdk.Messages.UpdateMultipleRequest>
+- <xref:Microsoft.Xrm.Sdk.Messages.UpsertMultipleRequest>
 
 
 <a name='guidance'></a>
 
 ## Guidance
 
-Use these batch messages where code is being executed outside of the platform execution pipeline, such as integration scenarios where network latency would likely reduce the throughput and increase the duration of larger, bulk operations.
+Use these batch messages in client applications to perform operations on multiple records. Don't use these messages within code that Dataverse invokes during the execution of another operation: a plug-in or workflow activity registered for a synchronous step.
 
 More specifically, use them in the following scenarios:
 
 - Use <xref:Microsoft.Xrm.Sdk.Messages.ExecuteMultipleRequest> to bulk load data or external processes that are intentional about executing long-running operations (greater than two minutes).
 
-- Use <xref:Microsoft.Xrm.Sdk.Messages.ExecuteMultipleRequest> to minimize the round trips between custom client and Dynamics 365 servers, thereby reducing the cumulative latency incurred.
+- Use <xref:Microsoft.Xrm.Sdk.Messages.ExecuteMultipleRequest> to minimize the round trips between custom client and Dataverse servers, to reduce the cumulative latency incurred.
+
+- Use <xref:Microsoft.Xrm.Sdk.Messages.ExecuteTransactionRequest> for external clients that require the batch of operations to be committed as a single, atomic database transaction or rollback if any exception is encountered. Be aware of the potential for database blocking during the long-running transaction.
 
-- Use <xref:Microsoft.Xrm.Sdk.Messages.ExecuteTransactionRequest> for external clients that require the batch of operations to be committed as a single, atomic database transaction or rollback if any exception is encountered. Be aware of the potential for database blocking for the duration of the long-running transaction.
+- [Use bulk operation messages](../../bulk-operations.md) (<xref:Microsoft.Xrm.Sdk.Messages.CreateMultipleRequest>, <xref:Microsoft.Xrm.Sdk.Messages.UpdateMultipleRequest>, and <xref:Microsoft.Xrm.Sdk.Messages.UpsertMultipleRequest>) for the same scenarios and to achieve a higher level of throughput.
 
 <a name='problem'></a>
 
 ## Problematic patterns
 
-Below is an example usage of <xref:Microsoft.Xrm.Sdk.Messages.ExecuteMultipleRequest> in the context of a plug-in.
+The following example shows using <xref:Microsoft.Xrm.Sdk.Messages.ExecuteMultipleRequest> in the context of a plug-in.
 
 > [!WARNING]
 > This scenario should be avoided.
@@ -100,11 +99,13 @@ This example includes usage of the type directly with the `Execute` method. The
 
 ## Additional information
 
-`ExecuteMultiple` and `ExecuteTransaction` messages are considered batch request messages. Their purpose is to minimize round trips between client and server over high-latency connections. Plug-ins either execute directly within the application process or in close proximity when sandbox-isolated, meaning latency is rarely an issue. Plug-in code should be very focused operations that execute quickly and minimize blocking to avoid exceeding timeout thresholds and ensure a responsive system for synchronous scenarios. Simply submit each request directly instead of batching them and submitting as a single request.
+The purpose of the `ExecuteMultiple` message is to minimize round trips between client and server over high-latency connections. Plug-ins either execute directly within the application process or in close proximity when sandbox-isolated, meaning latency is rarely an issue. Plug-in code should be focused operations that execute quickly and minimize blocking to avoid exceeding timeout thresholds and ensure a responsive system for synchronous scenarios. Submit each request directly instead of batching them and submitting as a single request.
 
 For example: `foreach (request in requests) service.Execute(request)`
 
-On the server side, the operations included in a batch request are executed sequentially and aren't done in parallel. This is the case even if the <xref:Microsoft.Xrm.Sdk.ExecuteMultipleSettings>.<xref:Microsoft.Xrm.Sdk.ExecuteMultipleSettings.ReturnResponses> property is set to false. Developers tend to use batch requests in this manner assuming that it will allow for parallel processing. Batch requests won't accomplish this objective. Another common motivator is an attempt to ensure that each operation is included in a transaction. This is unnecessary because the plug-in is often already being executed within the context of a database transaction, negating the need to use the `ExecuteTransaction` message.
+On the server side, the operations included in a batch request are executed sequentially and aren't done in parallel. This is the case even if the <xref:Microsoft.Xrm.Sdk.ExecuteMultipleSettings>.<xref:Microsoft.Xrm.Sdk.ExecuteMultipleSettings.ReturnResponses> property is set to false. Developers tend to use batch requests in this manner assuming that it allows for parallel processing. Batch requests don't accomplish this objective. 
+
+People use <xref:Microsoft.Xrm.Sdk.Messages.ExecuteTransactionRequest> to ensure that each operation is included in a transaction. This is unnecessary within a synchronous plug-in step because the plug-in already being executed within the context of a database transaction, negating the need to use the `ExecuteTransaction` message.
 
 <a name='seealso'></a>
 
diff --git a/powerapps-docs/developer/data-platform/bulk-operations.md b/powerapps-docs/developer/data-platform/bulk-operations.md
@@ -1,7 +1,7 @@
 ---
 title: Use bulk operation messages
 description: Learn how to use special APIs to perform operations on multiple rows of data in a Microsoft Dataverse table. 
-ms.date: 11/13/2023
+ms.date: 02/08/2024
 author: divkamath
 ms.author: dikamath
 ms.reviewer: jdaly
@@ -20,7 +20,7 @@ To get the best performance when you run operations on multiple rows of a Micros
 
 - [`CreateMultiple`](#createmultiple): Creates multiple records of the same type in a single request.
 - [`UpdateMultiple`](#updatemultiple): Updates multiple records of the same type in a single request.
-- [`UpsertMultiple` (preview)](upsertmultiple.md): Creates or updates multiple records of the same type in a single request.
+- [`UpsertMultiple`](upsertmultiple.md): Creates or updates multiple records of the same type in a single request.
 - [`DeleteMultiple` (preview)](deletemultiple.md): For elastic tables only. Deletes multiple records of the same type in a single request.
 
 > [!NOTE]
@@ -137,6 +137,7 @@ Updates multiple records of the same type in a single request.
 
 Just like when you update individual records, the data you send with `UpdateMultiple` must contain only the values you're changing. Learn how to [update records with SDK for .NET](org-service/entity-operations-update-delete.md) and [update records with the Web API](webapi/update-delete-entities-using-web-api.md#basic-update).
 
+
 ##### [SDK for .NET](#tab/sdk)
 
 Uses the [UpdateMultipleRequest class](xref:Microsoft.Xrm.Sdk.Messages.UpdateMultipleRequest).
@@ -217,9 +218,161 @@ OData-Version: 4.0
 
 ---
 
-#### Duplicate records in the payload
+#### Duplicate records in UpdateMultiple Targets parameter
+
+Multiple records with the same primary key or alternate key values in the payload are not supported with `UpdateMultiple`. When more than one record in the `Targets` parameter is uniquely identified by a primary or alternate key, the operation is performed on the first record only. Any subsequent records with the same key value(s) in the payload are ignored. [This behavior is different from `UpsertMultiple`](#duplicate-records-in-upsertmultiple-targets-parameter).
+
+### UpsertMultiple
+
+Use `Upsert` to integrate data with external sources when you don't know whether the table exists in Dataverse or not. `Upsert` operations frequently depend on alternate keys to identify records. Use `UpsertMultiple` to perform `Upsert` operations in bulk.
+
+##### [SDK for .NET](#tab/sdk)
+
+Uses the [UpsertMultipleRequest class](xref:Microsoft.Xrm.Sdk.Messages.UpsertMultipleRequest).
+
+This static `UpsertMultipleExample` method depends on a `samples_bankaccount` table that has a string column named `samples_accountname` configured as an alternate key. It also has a string column named `samples_description`. This code uses the [Entity constructor that sets the keyName and keyValue](use-alternate-key-reference-record.md#using-the-entity-class) to specify the alternate key value.
+
+```csharp
+/// <summary>
+/// Demonstrates using UpsertMultiple with alternate key values
+/// </summary>
+/// <param name="service">The authenticated IOrganizationService instance</param>
+static void UpsertMultipleExample(IOrganizationService service)
+{
+    var tableLogicalName = "samples_bankaccount";
+    // samples_accountname string column is configued as an alternate key
+    // for the samples_bankaccount table
+    var altKeyColumnLogicalName = "samples_accountname";
+
+    // Create one record to update with upsert
+    service.Create(new Entity(tableLogicalName)
+    {
+        Attributes =
+        {
+            {altKeyColumnLogicalName, "Record For Update"},
+            {"samples_description","A record to update using Upsert" }
+        }
+    });
+
+    // Using the Entity constructor to specify alternate key
+    Entity toUpdate = new(
+            entityName: tableLogicalName,
+            keyName: altKeyColumnLogicalName,
+            // Same alternate key value as created record.
+            keyValue: "Record For Update");
+    toUpdate["samples_description"] = "Updated using Upsert";
+
+    Entity toCreate = new(
+        entityName: tableLogicalName,
+        keyName: altKeyColumnLogicalName,
+        keyValue: "Record For Create");
+    toCreate["samples_description"] = "A record to create using Upsert";
+
+    // Add the records to a collection
+    EntityCollection records = new()
+    {
+        EntityName = tableLogicalName,
+        Entities = { toUpdate, toCreate }
+    };
+
+    // Send the request
+    UpsertMultipleRequest request = new()
+    {
+        Targets = records
+    };
+
+    var response = (UpsertMultipleResponse)service.Execute(request);
+
+    // Process the responses:
+    foreach (UpsertResponse item in response.Results)
+    {
+        Console.WriteLine($"Record {(item.RecordCreated ? "Created" : "Updated")}");
+    }
+}
+```
+
+**Output:**
+
+```
+Record Updated
+Record Created
+```
 
-Multiple records with the same primary key or alternate key values in the payload are not supported with `UpdateMultiple`. When more than one record in the `Targets` parameter is uniquely identified by a primary or alternate key, the operation is performed on the first record only. Any subsequent records with the same key value(s) in the payload are ignored.
+Whether a record is created or updated in this example depends on whether records exist with the matching `sample_keyattribute` value. No data is returned to indicate whether a record was created or updated.
+
+#### SDK examples
+
+Within [Sample: SDK for .NET Use bulk operations](org-service/samples/create-update-multiple.md), look for the [UpsertMultiple project](https://github.com/microsoft/PowerApps-Samples/blob/master/dataverse/orgsvc/C%23-NETCore/BulkOperations/UpsertMultiple/README.md)
+
+##### [Web API](#tab/webapi)
+
+Uses the [UpsertMultiple action](xref:Microsoft.Dynamics.CRM.UpsertMultiple).
+
+> [!IMPORTANT]
+> 
+> - You must set the `@odata.type` property for each item in the `Targets` parameter.
+> - The `UpsertMultiple` action returns `204 NoContent`. The `UpsertMultipleResponse` complex type is not returned.
+
+The following example shows using the `UpsertMultiple` action with a standard table named `sample_example`.
+These requests identify the records using an alternate key defined using a column named `sample_keyattribute`. 
+The `@odata.id` annotation identifies the record with a relative URL as described in [Use an alternate key to reference a record](use-alternate-key-reference-record.md)
+
+**Request**
+
+```http
+POST [Organization Uri]/api/data/v9.2/sample_examples/Microsoft.Dynamics.CRM.UpsertMultiple
+OData-MaxVersion: 4.0
+OData-Version: 4.0
+If-None-Match: null
+Accept: application/json
+Authorization: Bearer <access token>
+Content-Type: application/json; charset=utf-8
+Content-Length: 850
+
+{
+  "Targets": [
+    {
+      "@odata.type": "Microsoft.Dynamics.CRM.sample_example",
+      "sample_name": "sample record 0000001",
+      "@odata.id": "sample_examples(sample_keyattribute='0000001')"
+    },
+    {
+      "@odata.type": "Microsoft.Dynamics.CRM.sample_example",
+      "sample_name": "sample record 0000002",
+      "@odata.id": "sample_examples(sample_keyattribute='0000002')"
+    },
+    {
+      "@odata.type": "Microsoft.Dynamics.CRM.sample_example",
+      "sample_name": "sample record 0000003",
+      "@odata.id": "sample_examples(sample_keyattribute='0000003')"
+    },
+    {
+      "@odata.type": "Microsoft.Dynamics.CRM.sample_example",
+      "sample_name": "sample record 0000004",
+      "@odata.id": "sample_examples(sample_keyattribute='0000004')"
+      
+    }
+  ]
+}
+```
+
+**Response**
+
+```http
+HTTP/1.1 204 NoContent
+OData-Version: 4.0
+```
+---
+
+#### Availability
+
+`UpsertMultiple` is available for tables that support `CreateMultiple` and `UpdateMultiple`. This includes all elastic tables. The queries found in [Availability with standard tables](bulk-operations.md#availability-with-standard-tables) will not return results for `UpsertMultiple`, but you can use them to detect whether a table supports both `CreateMultiple` and `UpdateMultiple`.
+
+These queries will not return results for the `UpsertMultiple` message. A table that supports both `CreateMultiple` and `UpdateMultiple` will support `UpsertMultiple`.
+
+#### Duplicate records in UpsertMultiple Targets parameter
+
+Multiple records with the same primary key or alternate key values in the payload are not supported with `UpsertMultiple`. When more than one record in the `Targets` parameter is uniquely identified by a primary or alternate key, `UpsertMultiple` will return an error. [This behavior is different from `UpdateMultiple`](#duplicate-records-in-updatemultiple-targets-parameter).
 
 
 ## Standard and elastic table usage
@@ -293,8 +446,6 @@ When you use the Web API to perform a bulk operation on an elastic table, you ne
 Bulk operation message availability depends on whether you're using standard tables or elastic tables. All elastic tables support the `CreateMultiple`, `UpdateMultiple`, `UpsertMultiple`, and `DeleteMultiple` messages.
 
 See also:
-
-- [UpsertMultiple Availability](upsertmultiple.md#availability)
 - [DeleteMultiple Availability](deletemultiple.md#availability)
 
 #### Availability with standard tables
@@ -439,7 +590,9 @@ The default timeout set using ServiceClient is 4 minutes, which is long for any
 
 ### Not supported for use in plug-ins
 
-At this time, we don't support using bulk operation messages in plug-ins. More information: [Don't use batch request types in plug-ins and workflow activities](best-practices/business-logic/avoid-batch-requests-plugin.md).
+At this time, we don't support using bulk operation messages in plug-in code. More information: [Don't use batch request types in plug-ins and workflow activities](best-practices/business-logic/avoid-batch-requests-plugin.md).
+
+However, you *should* write plug-ins for the `CreateMultiple` and `UpdateMultiple` messages as described in [Write plug-ins for CreateMultiple and UpdateMultiple](write-plugin-multiple-operation.md).
 
 ## Troubleshooting common errors
 
diff --git a/powerapps-docs/developer/data-platform/upsertmultiple.md b/powerapps-docs/developer/data-platform/upsertmultiple.md
diff --git a/powerapps-docs/developer/data-platform/webapi/samples/create-update-multiple.md b/powerapps-docs/developer/data-platform/webapi/samples/create-update-multiple.md

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,10 @@`
`1`	`1`	`{`
`2`	`2`	`"redirections": [`
	`3`	`+ {`
	`4`	`+ "source_path": "powerapps-docs/developer/data-platform/upsertmultiple.md",`
	`5`	`+ "redirect_url": "bulk-operations#upsertmultiple",`
	`6`	`+ "redirect_document_id": "false"`
	`7`	`+ },`
`3`	`8`	`{`
`4`	`9`	`"source_path": "powerapps-docs/developer/data-platform/org-service/extend-code-generation-tool.md",`
`5`	`10`	`"redirect_url": "/dynamics365/customerengagement/on-premises/developer/org-service/extend-code-generation-tool",`