使用 ExecuteMultiple 提升大量資料載入的效能
發行︰ 2016年11月
適用於： Dynamics CRM 2015
您可以使用 ExecuteMultipleRequest 訊息在 Microsoft Dynamics CRM 2015 和 Microsoft Dynamics CRM Online 2015 更新 中支援更高傳輸量的大量訊息傳遞案例，尤其是 Microsoft Dynamics CRM Online，其中網路延遲可能是最大的限制因素。ExecuteMultipleRequest 會接受訊息 Requests 的輸入集合，執行每一個訊息要求，依它們出現在輸入集合中的順序，以及選擇性地傳回 Responses 集合，其中包含每個訊息的回覆或發生的錯誤。 輸入集合中的每個訊息要求都會分別以不同的資料庫交易處理。ExecuteMultipleRequest 是使用 IOrganizationService.Execute 方法執行。
一般來說，ExecuteMultipleRequest 的行為與您在輸入要求集合中分別執行每個訊息要求的行為相同，但是效能更佳。 您可以使用服務 Proxy 的 CallerId 參數，而且適用於執行輸入要求集合中的每個訊息。 外掛程式和工作流程活動的執行方式會如同處理每個訊息一般。
外掛程式形式的自訂程式碼和自訂工作流程活動甚至可以執行 ExecuteMultipleRequest。 不過，有幾個重點必須記住。 已註冊的同步外掛程式擲回的例外狀況會在回覆集合項目 Fault 參數中傳回。 如果外掛程式是在資料庫交易中執行，則外掛程式會執行 ExecuteMultipleRequest，而且會啟始交易回復，回復中包括 ExecuteMultipleRequest 所執行要求產生的所有資料變更。
本主題內容
範例
指定執行階段執行選項
執行階段限制
處理批次大小錯誤
範例
下列範例程式碼將示範執行多個建立作業的單一 ExecuteMultipleRequest。 稱為「設定」(Setting) 的執行階段執行選項可用來控制要求處理和傳回的結果。 這些執行階段選項將在下一節中討論。
// Get a reference to the organization service.
using (_serviceProxy = new OrganizationServiceProxy(serverConfig.OrganizationUri, serverConfig.HomeRealmUri,serverConfig.Credentials, serverConfig.DeviceCredentials))
{
// Enable early-bound type support to add/update entity records required for this sample.
_serviceProxy.EnableProxyTypes();
#region Execute Multiple with Results
// Create an ExecuteMultipleRequest object.
requestWithResults = new ExecuteMultipleRequest()
{
// Assign settings that define execution behavior: continue on error, return responses.
Settings = new ExecuteMultipleSettings()
{
ContinueOnError = false,
ReturnResponses = true
},
// Create an empty organization request collection.
Requests = new OrganizationRequestCollection()
};
// Create several (local, in memory) entities in a collection.
EntityCollection input = GetCollectionOfEntitiesToCreate();
// Add a CreateRequest for each entity to the request collection.
foreach (var entity in input.Entities)
{
CreateRequest createRequest = new CreateRequest { Target = entity };
requestWithResults.Requests.Add(createRequest);
}
// Execute all the requests in the request collection using a single web method call.
ExecuteMultipleResponse responseWithResults =
(ExecuteMultipleResponse)_serviceProxy.Execute(requestWithResults);
// Display the results returned in the responses.
foreach (var responseItem in responseWithResults.Responses)
{
// A valid response.
if (responseItem.Response != null)
DisplayResponse(requestWithResults.Requests[responseItem.RequestIndex], responseItem.Response);
// An error has occurred.
else if (responseItem.Fault != null)
DisplayFault(requestWithResults.Requests[responseItem.RequestIndex],
responseItem.RequestIndex, responseItem.Fault);
}
' Get a reference to the organization service.
_serviceProxy = ServerConnection.GetOrganizationProxy(serverConfig)
Using _serviceProxy
' Enable early-bound type support to add/update entity records required for this sample.
_serviceProxy.EnableProxyTypes()
'#Region "Execute Multiple with Results"
' Create an ExecuteMultipleRequest object.
' Assign settings that define execution behavior: continue on error, return responses.
' Create an empty organization request collection.
requestWithResults = New ExecuteMultipleRequest() With
{
.Settings = New ExecuteMultipleSettings() With
{
.ContinueOnError = False,
.ReturnResponses = True
},
.Requests = New OrganizationRequestCollection()
}
' Create several (local, in memory) entities in a collection.
Dim input As EntityCollection = GetCollectionOfEntitiesToCreate()
' Add a CreateRequest for each entity to the request collection.
For Each entity In input.Entities
Dim createRequest_Renamed As CreateRequest = New CreateRequest With {.Target = entity}
requestWithResults.Requests.Add(createRequest_Renamed)
Next entity
' Execute all the requests in the request collection using a single web method call.
Dim responseWithResults As ExecuteMultipleResponse =
CType(_serviceProxy.Execute(requestWithResults), ExecuteMultipleResponse)
' Display the results returned in the responses.
For Each responseItem In responseWithResults.Responses
If responseItem.Response IsNot Nothing Then
' A valid response.
DisplayResponse(requestWithResults.Requests(responseItem.RequestIndex),
responseItem.Response)
ElseIf responseItem.Fault IsNot Nothing Then
' An error has occurred.
DisplayFault(requestWithResults.Requests(responseItem.RequestIndex),
responseItem.RequestIndex, responseItem.Fault)
End If
Next responseItem
若要檢視完整的範例，請參閱範例：執行多個請求。
指定執行階段執行選項
ExecuteMultipleRequest 的 Settings 參數會套用至控制執行行為和傳回結果的要求集合中的所有要求。 讓我們深入了解這些選項。
ExecuteMultipleSettings 成員 |
描述 |
|---|---|
若為 true，則繼續處理集合中的下一個要求，即使處理集合中的目前要求已傳回錯誤。 若為 false，則不繼續處理下一個要求。 |
|
若為 true，則傳回來自所處理的每個訊息要求的回覆。 若為 false，則不傳回回覆。 如果設為 true 且要求的原始設計為不傳回回覆，則該要求的 ExecuteMultipleResponseItem 會設定為 null。 不過，即使為 false，如果傳回錯誤，Responses 集合將不會是空的。 如果傳回錯誤，集合中每個傳回錯誤的已處理要求都會有一個回覆項目，而且 Fault 將設定為發生的實際錯誤。 |
例如，在包含六個要求的要求集合中，第三個和第五個要求傳回錯誤，下表將指出 Responses 集合中會包函的內容。
設定 |
回覆集合內容 |
|---|---|
ContinueOnError=true, ReturnResponses=true |
6 個回覆項目：其中 2 個的 Fault 設定為值。 |
ContinueOnError=false, ReturnResponses=true |
3 個回覆項目：其中 1 個的 Fault 設定為值。 |
ContinueOnError=true, ReturnResponses=false |
2 個回覆項目：其中 2 個的 Fault 設定為值。 |
ContinueOnError=false, ReturnResponses=false |
1 個回覆項目：其中 1 個的 Fault 設定為值。 |
回覆項目中的 RequestIndex 參數表示與回覆相關聯的要求的序號，以零起始。 在前面的範例中，第三個要求的要求索引為 2。
執行階段限制
使用 ExecuteMultipleRequest 有數項相關限制，如下列清單中所述。
不允許遞迴 - ExecuteMultipleRequest 無法叫用 ExecuteMultipleRequest。 存在要求集合中的 ExecuteMultipleRequest 將會對該要求項目產生錯誤。
最大批次大小 – 能夠新增至要求集合中的要求數目有所限制。 如果超過該限制，則會在第一個要求尚未執行之前就擲回錯誤。 1000 要求數目上限是一般，雖然可對 Microsoft Dynamics 365 部署設定此最大數量。 此限制的部署設定為 BatchSize。
同時呼叫的節流 – 對於 Microsoft Dynamics CRM Online，每個組織最多只能有 2 個同時執行的 ExecuteMultipleRequest。 如果超過該限制，則會在第一個要求尚未執行之前就擲回「伺服器忙碌中」錯誤。 對於內部部署的部署，預設不會啟用節流。 此限制的部署設定為 ExecuteAsyncPerOrgMaxConnectionsPerServer。
處理批次大小錯誤
當您的輸入要求集合超過最大批次大小時，該怎麼做？ 您的程式碼無法透過部署 Web 服務直接查詢最大批次大小，除非它是以具有部署系統管理員角色的帳戶執行。
好消息是，您可以使用另一種方法。 當輸入 Requests 集合中的要求數目超過組織允許的最大批次大小時，會從 ExecuteMultipleRequest 呼叫傳回錯誤。 錯誤中也會傳回最大批次大小。 您的程式碼可以檢查該值，重新調整輸入要求集合的大小，以符合指出的限制，然後重新送出 ExecuteMultipleRequest。 下列程式碼片段將示範此邏輯的一部分。
catch (FaultException<OrganizationServiceFault> fault)
{
// Check if the maximum batch size has been exceeded. The maximum batch size is only included in the fault if it
// the input request collection count exceeds the maximum batch size.
if (fault.Detail.ErrorDetails.Contains("MaxBatchSize"))
{
int maxBatchSize = Convert.ToInt32(fault.Detail.ErrorDetails["MaxBatchSize"]);
if (maxBatchSize < requestWithResults.Requests.Count)
{
// Here you could reduce the size of your request collection and re-submit the ExecuteMultiple request.
// For this sample, that only issues a few requests per batch, we will just print out some info. However,
// this code will never be executed because the default max batch size is 1000.
Console.WriteLine("The input request collection contains %0 requests, which exceeds the maximum allowed (%1)",
requestWithResults.Requests.Count, maxBatchSize);
}
}
// Re-throw so Main() can process the fault.
throw;
}
Catch fault As FaultException(Of OrganizationServiceFault)
' Check if the maximum batch size has been exceeded. The maximum batch size is only included in the fault if it
' the input request collection count exceeds the maximum batch size.
If fault.Detail.ErrorDetails.Contains("MaxBatchSize") Then
Dim maxBatchSize As Integer = Convert.ToInt32(fault.Detail.ErrorDetails("MaxBatchSize"))
If maxBatchSize < requestWithResults.Requests.Count Then
' Here you could reduce the size of your request collection and re-submit the ExecuteMultiple request.
' For this sample, that only issues a few requests per batch, we will just print out some info. However,
' this code will never be executed because the default max batch size is 1000.
Console.WriteLine("The input request collection contains %0 requests, which exceeds the maximum allowed (%1)", requestWithResults.Requests.Count, maxBatchSize)
End If
End If
' Re-throw so Main() can process the fault.
Throw
End Try
另請參閱
Execute
OrganizationRequest
OrganizationResponse
使用 IOrganizationService Web 服務讀取和寫入資料或中繼資料
組織服務中的 xRM 訊息
探索服務的訊息
組織服務中的 CRM 訊息
匯入資料
© 2017 Microsoft. 著作權所有，並保留一切權利。 著作權