共用方式為

日期和時間屬性的行為與格式

  • 發行項

 

發行︰ 2016年11月

適用於： Dynamics CRM 2015

如果您有遍佈世界各地的使用者和分公司，正確顯示多個時區的日期與時間值是很重要的。DateTimeAttributeMetadata 類別用來定義和管理 CRM 中的 DateTime 屬性類型。 使用 DateTimeAttributeMetadata.DateTimeBehavior 屬性來定義儲存有或沒有時區資訊的日期和時間值，使用 DateTimeAttributeMetadata.Format 屬性來指定這些屬性的顯示格式。

在 Dynamics 365 也可以使用自訂區域來定義日期和時間屬性的行為與格式。其他資訊：TechNet：日期及時間欄位的行為與格式

注意

DateTimeAttributeMetadata.DateTimeBehavior 屬性只有當您使用 CRM Online 和已更新執行個體至 Microsoft Dynamics CRM Online 2015 更新 1 時才能使用。 此外，Microsoft Dynamics CRM Online 2015 更新 1 的所有日期和時間屬性目前支援早在 1/1/1753 12:00 AM 的值。

如果是其他 CRM 版本，您無法定義日期和時間值的行為。 根據預設，日期和時間值儲存為 UserLocal 行為，如本主題中稍後描述。

本主題內容

指定日期和時間屬性的行為

指定日期和時間屬性的格式

DateOnly 行為不支援日期和時間查詢運算子

變更日期和時間屬性的行為

轉換資料庫中現有日期和時間值的行為

指定日期和時間屬性的行為

您可以使用 DateTimeBehavior 類別來指定 DateTimeAttributeMetadata.DateTimeBehavior 屬性的值。DateTimeBehavior 類別包含下列成員；每個成員都會傳回一個字串，其中包含與成員名稱相同的值：

成員名稱和值

描述

UserLocal

  • 系統中儲存日期和時間值為 UTC 值。

  • 擷取作業傳回 UTC 值。

  • 更新作業將 UTC 值轉換成目前使用者的時區值，然後儲存這個更新值原狀或做為對等的 UTC 值，根據指定的更新值類型而定 (DateTimeKind)。 如果指定值為 UTC 類型，它依原狀儲存。 否則儲存對等的 UTC 值。

  • 擷取格式化的值會從 UTC 轉換成使用者目前的時區，根據使用者的時區及地區設定而定。

  • 對於 OData 端點，屬性會公開為 DateTimeOffset。

  • 此行為供例如 CreatedOn 和 ModifiedOn 等系統屬性使用，無法變更。 您應該對於要儲存有時區資訊的日期和時間值的自訂屬性使用此行為。

DateOnly

  • 在系統中儲存時間值為上午 12:00 (00:00:00) 的實際日期值。

  • 對於擷取和更新作業，不執行時區轉換，而且時間值一律是上午 12:00 (00:00:00)。

  • 擷取格式化的值，會顯示不含時區轉換的日期值。

  • 對於 OData 端點，屬性會公開為 DateTimeOffset。

  • 儲存生日和週年紀念日 (不需要時間資訊) 的自訂屬性應該使用此行為。

TimeZoneIndependent

  • 不論使用者時區，在系統中儲存實際日期和時間值。

  • 對於擷取和更新作業，不執行時區轉換，而且不論使用者時區，實際日期和時間值分別在系統中傳回或更新。

  • 擷取格式化的值會顯示日期和時間值 (不含時區轉換)，根據目前使用者時區及地區設定的格式而定。

  • 對於 OData 端點，屬性會公開為 DateTimeOffset。

  • 儲存旅館進房和退房時間資訊的屬性應該使用此行為。

下列範例程式碼示範如何為新日期時間屬性設定 UserLocal 行為：


// Create a date time attribute for the Account entity
// with the UserLocal behavior
dtAttribute = new DateTimeAttributeMetadata
{                             
    SchemaName = "new_SampleDateTimeAttribute",
    DisplayName = new Label("Sample Date Time Attribute", _languageCode),
    RequiredLevel = new AttributeRequiredLevelManagedProperty(AttributeRequiredLevel.None),                
    Description = new Label("Created by SDK Sample", _languageCode),                
    DateTimeBehavior = DateTimeBehavior.UserLocal,
    Format = DateTimeFormat.DateAndTime,
    ImeMode = ImeMode.Disabled
};

CreateAttributeRequest createAttributeRequest = new CreateAttributeRequest
{
    EntityName = Account.EntityLogicalName,
    Attribute = dtAttribute
};
_serviceProxy.Execute(createAttributeRequest);
Console.WriteLine("Created attribute '{0}' with UserLocal behavior\nfor the Account entity.\n", 
                            dtAttribute.SchemaName);

在範例程式碼，也可以直接指定字串值，設定 DateTimeBehavior 屬性的值：DateTimeBehavior = "UserLocal"

如果建立日期和時間屬性時未指定行為，預設建立具有 UserLocal 行為的屬性。 如需完整的範例程式碼，請參閱範例：轉換日期和時間行為。

重要

  • 當您建立行為設為 DateOnly 或 TimeZoneIndependent 的日期和時間屬性，您無法變更屬性的行為。其他資訊：變更日期和時間屬性的行為

  • 使用 DateOnly 或 TimeZoneIndependent 行為的日期和時間屬性，在舊版離線模式的 Dynamics CRM for Outlook 用戶端編輯時會視同有 UserLocal 行為。 這是因為用戶端不了解新的行為，不會視它們與 UserLocal 不同 (在其他 CRM 版本的現有行為，但 Microsoft Dynamics CRM Online 2015 更新 1 除外)。 在升級時，日期和時間屬性不會轉換為新的行為，因此最佳做法是升級所有 Dynamics CRM for Outlook 用戶端到最新版本，才讓自訂員採用其中一個新的行為。 在線上，編輯包含新行為的欄位資料會正常運作。

    舊版 Dynamics CRM for Outlook 用戶端同樣不了解比 1/1/1900 更早的日期 (其他 CRM 版本支援之日期和時間類型的最早值，但 Microsoft Dynamics CRM Online 2015 更新 1 除外)。 使用者離線時無法開啟日期比 1/1/1900 更早的記錄。 不過，連線後一切會正常運作。 您必須升級至 Dynamics CRM for Outlook 用戶端的最新版本，才能在離線模式下使用最早 1/1/1753 上午 12:00 日期的屬性。

  • 如果您使用自訂程式碼，在 CRM 執行個體中實作日期時間行為，由於新行為功能，在 Microsoft Dynamics CRM Online 2015 更新 1 可能不會如預期運作。

指定日期和時間屬性的格式

使用 DateTimeAttributeMetadata.Format 屬性指定屬性的日期/時間顯示格式，不論它如何儲存在系統中。 您可以使用 DateTimeFormat 列舉指定顯示格式：DateAndTime 或 DateOnly。

如果 DateTimeBehavior 屬性設為 DateOnly，您無法設定或變更 Format 屬性的值為 DateAndTime。

DateOnly 行為不支援日期和時間查詢運算子

DateOnly 行為不支援時間相關查詢運算子。 除了這裡所列示的時間特定查詢運算子，支援所有其他查詢運算子。

  • 早於 X 分鐘

  • 早於 X 小時

  • 過去 X 小時

  • 未來 X 小時

其他資訊：FetchXML 中的會計年度日期和 "older than" 日期/時間查詢運算子

變更日期和時間屬性的行為

如果您有 CRM 執行個體的系統自訂員角色，而且日期和時間屬性的 CanChangeDateTimeBehavior 受管理屬性設為 True，您可以更新日期和時間屬性變更其行為。

警告

在變更日期和時間屬性的行為之前，應先檢閱屬性的任何相依性，例如商務規則、工作流程和計算或彙總屬性，確保變更行為沒有產生任何問題。 使用 CanChangeDateTimeBehavior 受管理屬性，系統自訂員可以限制修改現有日期和時間屬性的行為。

至少在變更日期和時間屬性的行為之後，您應該開啟相依於已變更日期和時間屬性的所有商務規則、工作流程、計算屬性和彙總屬性記錄，檢閱資訊，並儲存記錄確定使用最新屬性行為與值。

在變更計算或彙總屬性的日期與時間行為之後，開啟導出欄位或彙總欄位定義編輯器，然後儲存欄位定義以確保屬性在行為變更之後是有效的。 系統自訂員可以按一下 [編輯] (在 CRM 自訂區域中 [欄位類型] 旁邊)，開啟計算或彙總屬性的欄位定義編輯器。其他資訊：定義導出欄位及定義彙總欄位

  • 內建和自訂實體的 CreatedOn 和 ModifiedOn 屬性的預設行為設定為 UserLocal，而 CanChangeDateTimeBehavior 受管理屬性設為 False，表示您無法變更這些屬性的行為。 雖然使用者可以變更 CanChangeDateTimeBehavior 受管理屬性值 (屬於自訂實體的這些屬性)，但仍無法變更屬性的行為。

  • 針對新的自訂日期和時間屬性，CanChangeDateTimeBehavior 受管理屬性設為 True。 這表示您可以將自訂日期和時間屬性的行為從 UserLocal 變更為 DateOnly 或 TimeZoneIndependent；不允許其他行為。

    如果是升級至 Microsoft Dynamics CRM Online 2015 更新 1 的 CRM 組織中的自訂日期和時間屬性，CanChangeDateTimeBehavior 受管理屬性設為 True，除非屬性或上層實體無法自訂。

    注意

    當您更新屬性的 DateTimeBehavior 屬性從 UserLocal 到 DateOnly，請確定同時將 Format 屬性從 DateAndTime 變更為 DateOnly。 否則，會發生例外。

  • Microsoft Dynamics CRM Online 2015 更新 1 的下列內建日期和時間屬性預設為 DateOnly，而 CanChangeDateTimeBehavior 受管理屬性設為這些屬性的 False，表示您無法變更這些屬性的行為：

    日期和時間屬性

    上層實體

    anniversary

    Contact

    birthdate

    Contact

    duedate

    Invoice

    estimatedclosedate

    Lead

    actualclosedate

    Opportunity

    estimatedclosedate

    Opportunity

    finaldecisiondate

    Opportunity

    validfromdate

    Product

    validtodate

    Product

    closedon

    Quote

    expireson

    Quote

    不過，如果這些內建日期和時間屬性屬於升級至 Microsoft Dynamics CRM Online 2015 更新 1 的組織，在已升級組織，這些屬性的行為設為 UserLocal，而 CanChangeDateTimeBehavior 受管理屬性設為 True，而且您只可以將這些屬性的行為變更為 DateOnly。 不允許其他行為轉換。

在更新屬性的行為之後，就必須發行自訂，變更才會生效。 更新日期和時間屬性的行為，可確定在變更屬性行為之後輸入/更新的所有值，都會根據新行為儲存在系統中。 這不會影響資料庫中已儲存的值，它們繼續儲存為 UTC 值。 不過，當您使用 SDK 取得現有值或在 UI 檢視時，現有值根據屬性的新行為顯示。 例如，如果將客戶實體的自訂屬性的行為從 UserLocal 變更為 DateOnly，然後使用 SDK 擷取現有客戶記錄，日期和時間會顯示為 <Date>，後面接著上午 12:00 (00:00:00) 時間。 同理，若將行為從 UserLocal 變更為 TimeZoneIndependent，資料庫的實際值依原狀顯示，沒有時區轉換。

下列範例程式碼示範如何更新日期及時間屬性的行為：


// Retrieve the attribute to update its behavior and format
RetrieveAttributeRequest attributeRequest = new RetrieveAttributeRequest
{
    EntityLogicalName = Account.EntityLogicalName,
    LogicalName = "new_sampledatetimeattribute",
    RetrieveAsIfPublished = false
};
// Execute the request
RetrieveAttributeResponse attributeResponse =
                (RetrieveAttributeResponse)_serviceProxy.Execute(attributeRequest);

Console.WriteLine("Retrieved the attribute '{0}'.",
                attributeResponse.AttributeMetadata.SchemaName);

// Modify the values of the retrieved attribute
DateTimeAttributeMetadata retrievedAttributeMetadata =
                (DateTimeAttributeMetadata)attributeResponse.AttributeMetadata;
retrievedAttributeMetadata.DateTimeBehavior = DateTimeBehavior.DateOnly;
retrievedAttributeMetadata.Format = DateTimeFormat.DateOnly;

// Update the attribute with the modified value
UpdateAttributeRequest updateRequest = new UpdateAttributeRequest
{
    Attribute = retrievedAttributeMetadata,
    EntityName = Account.EntityLogicalName,
    MergeLabels = false
};
_serviceProxy.Execute(updateRequest);
Console.WriteLine("Updated the behavior and format of '{0}' to DateOnly.",
    retrievedAttributeMetadata.SchemaName);

// Publish customizations to the account entity
PublishXmlRequest pxReq = new PublishXmlRequest
{
    ParameterXml = String.Format("<importexportxml><entities><entity>account</entity></entities></importexportxml>")
};
_serviceProxy.Execute(pxReq);
Console.WriteLine("Published customizations to the Account entity.\n");

如需完整的範例程式碼，請參閱範例：轉換日期和時間行為。

轉換資料庫中現有日期和時間值的行為

當您更新日期和時間屬性，將其行為從 UserLocal 變更為 DateOnly 或 TimeZoneIndependent，系統不自動轉換資料庫中的現有屬性值。 行為變更只影響在變更行為之後輸入或更新的屬性值。 系統的現有日期和時間值持續為 UTC，並在透過 SDK 擷取或在 UI 檢視時 CRM 根據新的行為顯示，如上一節中的指示。 針對行為已從 UserLocal 變更為 DateOnly 的屬性，可使用 ConvertDateAndTimeBehaviorRequest 訊息將資料庫的現有 UTC 值轉換為正確 DateOnly 值以避免資料異象。

此訊息讓您指定轉換規則 (ConversionRule)，選取時區以用於從 UTC 轉換值為 DateOnly。 您可以選擇下列其中一個轉換規則：

  • SpecificTimeZone：將 UTC 值轉換成 DateOnly 值，根據指定的 CRM 時區代碼。 在此情況下，您也需要為 TimeZoneCode 參數指定值。

  • CreatedByTimeZone：將 UTC 值轉換成 DateOnly 值，建立記錄的使用者可在 UI 看到此值。

  • OwnerTimeZone：將 UTC 值轉換成 DateOnly 值，擁有記錄的使用者可在 UI 看到此值。

  • LastUpdatedByTimeZone：將 UTC 值轉換成 DateOnly 值，上次更新記錄的使用者可在 UI 看到此值。

您可以使用 DateTimeBehaviorConversionRule 類別的四成員其中一個來為 ConversionRule 參數指定有效值。

注意

  • ConvertDateAndTimeBehaviorRequest 訊息只有當您使用 CRM Online 和已更新執行個體至 Microsoft Dynamics CRM Online 2015 更新 1 時才能使用。 它無法用於 Microsoft Dynamics CRM (內部部署)。

  • 您必須有 CRM 執行個體的系統管理員角色，才能執行 ConvertDateAndTimeBehaviorRequest 訊息。

當您執行 ConvertDateAndTimeBehaviorRequest 訊息時，會建立系統作業 (非同步處理作業) 執行轉換要求。 在訊息回覆的 ConvertDateAndTimeBehaviorResponse.JobId 屬性顯示系統作業 ID (因轉換要求而建立此系統作業)。 在系統作業完成之後，請檢查系統作業詳細資料 (AsyncOperation.Message) 檢視轉換詳細資料或錯誤 (如果有)。

注意

建議您將多個屬性轉換群組成單一轉換工作，且一次執行單一轉換工作，確認轉換沒有發生衝突並確保最佳系統效能。

使用 ConvertDateAndTimeBehaviorRequest 訊息時考慮的重點：

  • 在訊息執行期間，您應該避免 Dynamics 365 解決方案的任何重大變更，例如匯入解決方案或刪除屬性或上層實體。 這樣做可能會產生非預期的行為，但是資料遺失不會發生。

  • 在系統中因為執行訊息而完成的更新，不會執行工作流程或外掛程式。

  • 在系統中因為執行訊息而完成的更新，不會變更屬性的 [上次修改日期] 值，不過會稽核以協助系統管理員確認轉換的時間與屬性的原始/變更值。

下列範例程式碼示範如何使用訊息：


ConvertDateAndTimeBehaviorRequest request = new ConvertDateAndTimeBehaviorRequest()
{
    Attributes = new EntityAttributeCollection() 
            { 
                new KeyValuePair<string, StringCollection>("account", new StringCollection() 
                { "new_sampledatetimeattribute" }) 
            },
    ConversionRule = DateTimeBehaviorConversionRule.SpecificTimeZone.Value,
    TimeZoneCode = 190, // Time zone code for India Standard Time (IST) in CRM
    AutoConvert = false // Conversion must be done using ConversionRule
};

// Execute the request
ConvertDateAndTimeBehaviorResponse response = (ConvertDateAndTimeBehaviorResponse)_serviceProxy.Execute(request);

如需完整的範例程式碼，請參閱範例：轉換日期和時間行為。

另請參閱

範例：轉換日期和時間行為
TechNet：日期及時間欄位的行為與格式
自訂實體屬性中繼資料

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