使用 OrganizationServiceContext 類別

 

發行︰ 2017年1月

適用於： Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online

在 Microsoft Dynamics 365 (線上和內部部署)，您可以使用 OrganizationServiceProxy 類別存取 Web 服務。 或者，您可以使用程式碼產生工具產生的 OrganizationServiceContext，存取其他功能。OrganizationServiceContext 類別讓您追蹤變更、管理身分識別與關係，以及存取 Microsoft Dynamics 365 LINQ 提供者。 此類別也包含 OrganizationServiceContext.SaveChanges 方法，用來送出內容追蹤之資料的變更。 此類別根據和 DataServiceContext 資料服務中 Windows Communication Foundation (WCF) 類別相同的概念。

若要產生此類別，請在產生早期繫結類型時提供 /serviceContextName 參數值。 程式碼產生工具使用此名稱，做為產生的類別名稱。 如需如何使用程式碼產生工具的詳細資訊，請參閱 使用程式碼產生工具 (CrmSvcUtil.exe) 建立早期繫結實體類別。 開發應用程式、外掛程式及工作流程活動時，您可以使用組織服務內容。

本主題內容

如何使用 OrganizationServiceContext 類別

使用 OrganizationServiceContext 類別追蹤變更

使用 OrganizationServiceContext 類別追蹤相關物件

使用 OrganizationServiceContext 類別儲存變更

在內容變更之後，使用虛擬方法

如何使用 OrganizationServiceContext 類別

若要具現化內容類別，您必須將實作 IOrganizationService 介面的物件傳遞給類別建構函式。 一個選項是傳遞 OrganizationServiceProxy 類別的執行個體。 如需 IOrganizationService 介面的詳細資訊，請參閱使用組織服務讀取和寫入資料或中繼資料。

下列程式碼範例會顯示如何建立內容類別的新執行個體。 在此範例中，內容類別命名為 AdventureWorksCycleServiceContext，方式是在程式碼產生工具上使用 /serviceContextName 參數指定名稱：

//For early bound types to work correctly, they have to be enabled on the proxy.
_serviceProxy.EnableProxyTypes();
AdventureWorksCycleServiceContext context = new AdventureWorksCycleServiceContext(_serviceProxy);

當您建立組織服務內容物件之後，即可開始追蹤建立、修改或刪除實體。 例如，下列程式碼範例顯示如何使用服務內容物件，具現化新連絡人，然後儲存至 Microsoft Dynamics 365 伺服器。

//  Create a new contact record;
AdventureWorksCycleServiceContext context = new AdventureWorksCycleServiceContext (_serviceProxy);
Contact contact = new Contact() 
 {
   FirstName = "Pamela",
   LastName = "Brown",
   Address1_Line1 = "123 Easy St.",
   Address1_City = "Atlanta",
   Address1_StateOrProvince = "GA",
   Address1_PostalCode = "32254",
   Telephone1 = "425-555-5678"   };
context.AddObject(contact);
context.SaveChanges();

在先前程式碼範例中有數個重點。 首先，在新連絡人具現化之後，您傳遞該連絡人物件至 OrganizationServiceContext.AddObject 方法，讓內容可以開始追蹤物件。 第二個重點是，使用 OrganizationServiceContext.SaveChanges 方法，新物件儲存至伺服器。

組織服務內容必須追蹤想要提交給 Microsoft Dynamics 365 的任何實體或關聯。 例如，您可以使用 LINQ 查詢擷取記錄，而內容會追蹤該實體或您可以使用 OrganizationServiceContext.Attach 方法造成內容開始追蹤實體。 您可以在用戶端應用程式中使用資料並建立新的實體、建立相關實體和修改現有的實體，但是，您必須在已追蹤實體上呼叫 SaveChanges 方法，送出變更至 Microsoft Dynamics 365 伺服器。

使用 OrganizationServiceContext 類別追蹤變更

若要判斷內容追蹤實體方式，您可以檢查實體執行個體的上 EntityState 屬性。 呼叫各個方法或使用 LINQ 查詢，您必須通知組織服務內容從 Microsoft Dynamics 365 追蹤實體。 從 .NET Language-Integrated Query (LINQ) 查詢傳回的所有實體都受到服務內容追蹤。

您可以在 OrganizationServiceContext 中呼叫下列其中一種方法來新增物件至服務內容。

方法	使用
AddObject	新增實體至組織服務內容追蹤的一組實體。 實體的狀態在內容中設為 Created。 如果呼叫 SaveChanges 方法，此記錄會建立或新增至伺服器。
Attach	新增實體至組織服務內容追蹤的一組實體。 實體的狀態在內容中設為 Unchanged。 如果呼叫SaveChanges 方法，此實體不會傳送至伺服器，除非變更其狀態。
CreateQuery	新增查詢結果至組織服務內容追蹤的一組實體。

使用 OrganizationServiceContext 類別追蹤相關物件

在 Dynamics 365 和 Dynamics 365 (線上)，組織服務內容可讓您建立和更新實體之間的關聯。CrmSvcUtil 工具所產生以及位於早期繫結類別的導覽屬性可讓您存取和變更相關實體屬性和關聯。 組織服務內容必須追蹤相關實體，相關實體才能在伺服器中可供更新。

使用 OrganizationServiceContext 的下列方法，使用相關實體和新增實體至服務內容：

方法	使用
AddRelatedObject	新增目標至內容。 在目標實體上呼叫 Attach 方法，然後在來源實體和目標 (相關) 實體之間呼叫 AddLink 方法。
AttachLink	新增相關實體至內容以進行追蹤。 實體的狀態在內容中設為 Unchanged。
AddLink	建立來源和目標實體之間的關聯。 新增目標至內容。 目標實體的狀態在內容中設為 Created。
LoadProperty	載入指定的關聯的相關實體集。 使用導覽屬性，提供相關實體的存取。 對上層實體使用導覽屬性存取實體之後，在相關實體上呼叫 AddObject 方法。
UpdateObject	將 OrganizationServiceContext 中指定實體之狀態變更為已修改。
DeleteObject	將 OrganizationServiceContext 中指定實體之狀態變更為要刪除。

使用導覽屬性載入相關實體

您已使用 LINQ 擷取之實體的相關實體是 null，直到使用 LoadProperty 擷取它們。 下列程式碼範例顯示如何存取與特定連絡人記錄相關的工作記錄。

Contact pam = context.ContactSet.Where(c => c.FirstName == "Pamela").FirstOrDefault();
if (pam != null)
{
// pam.Contact_Tasks is null until you use LoadProperty
    context.LoadProperty(pam, "Contact_Tasks");
    Task firstTask = pam.Contact_Tasks.FirstOrDefault();
}

使用 OrganizationServiceContext 類別儲存變更

組織服務內容對追蹤的實體保有圖形。 組織服務內容處理實體變更和將其送出至伺服器的順序是很重要的。 先處理主要實體的更新，然後處理相關實體。 若主要實體的值是由相關實體設定的，更新伺服器上的資料時會使用該值。

如果當實體資訊儲存時發生錯誤，OrganizationServiceContext.SaveChanges 方法會擲回包含 SaveChangesResult 的新例外狀況類型，不論傳遞至方法的 SaveChangesOptions 參數值。

在內容變更之後，使用虛擬方法

有時候根據 OrganizationServiceContext 中的變更採取行動可能是必要的。 為了促進此程序，提供虛擬方法可讓您攔截或收到作業的通知。 若要利用這些方法，您必須從 OrganizationServiceContext 衍生或變更產生的組織內容。下表列出虛擬方法。

方法	描述
OnBeginEntityTracking	在實體之後附加至 OrganizationServiceContext 之後呼叫。
OnBeginLinkTracking	在連結之後附加至 OrganizationServiceContext 之後呼叫。
OnEndEntityTracking	在實體從 OrganizationServiceContext 中斷連結之後呼叫。
OnEndLinkTracking	在連結從 OrganizationServiceContext 中斷連結之後呼叫。
OnExecuting	在要求送出至 Microsoft Dynamics 365 Server 之前立即呼叫。
OnExecute	在要求送出至 Microsoft Dynamics 365 Server 之後立即呼叫之後，不管是否發生例外狀況。
OnSavingChanges	在呼叫 SaveChanges 之後，發生任何作業之前呼叫。
OnSaveChanges	當呼叫 SaveChanges 的所有作業完成時，或發生失敗時呼叫。

另請參閱

IOrganizationService
OrganizationServiceContext
在程式碼中使用早期繫結實體類別
範例：複雜 LINQ 查詢
使用程式碼產生工具 (CrmSvcUtil.exe) 建立早期繫結實體類別
使用早期繫結實體類別，進行建立、更新和刪除

Microsoft Dynamics 365

© 2017 Microsoft. 著作權所有，並保留一切權利。 著作權