日期及时间属性的行为和格式

 

发布日期： 2017年1月

适用于： Dynamics 365 (online),Dynamics 365 (on-premises),Dynamics CRM 2016,Dynamics CRM Online

如果您在全球各地都有用户和办公室，正确地表示多个时区的日期和时间值很重要。DateTimeAttributeMetadata 类用于定义和管理 Dynamics 365 中类型 DateTime 的属性。 使用 DateTimeAttributeMetadata.DateTimeBehavior 属性定义是否包含时区信息存储日期和时间值，使用 DateTimeAttributeMetadata.Format 属性指定这些属性的显示格式。

您还可以使用 Dynamics 365 中的自定义区域定义日期和时间属性的行为和格式。详细信息：TechNet：日期及时间字段的行为和格式

备注

DateTimeAttributeMetadata。DateTimeBehavior 属性只有当您使用 Microsoft Dynamics CRM Online 2015 更新 1 或 Microsoft Dynamics 365（内部部署）时才可用。 此外，CRM Online 2015 更新 1 和 Dynamics 365（内部部署）中的所有日期和时间属性如今支持早在 1/1/1753 12:00 AM 的值。

对于早于 CRM Online 2015 更新 1 和 Dynamics 365（内部部署）的 Dynamics 365 版本，您不能定义日期和时间值的行为。 默认情况下，日期和时间值被存储为 UserLocal 行为，本主题后面有相关介绍。

本主题内容

指定日期及时间属性的行为

指定日期及时间属性的格式

DateOnly 行为不支持的日期和时间查询运算符

更改日期及时间属性的行为

转换数据库中的现有日期和时间值的行为

指定日期及时间属性的行为

可以使用 DateTimeBehavior 类为 DateTimeAttributeMetadata.DateTimeBehavior 属性指定值。DateTimeBehavior 类包含下列成员；每个成员返回具有与成员名称相同值：

成员名称和值	说明
UserLocal	在系统中将日期和时间值存储为 UTC 值。 检索操作返回 UTC 值。 更新操作将 UTC 值转换为当前用户的时区值，然后直接存储更新值，或作为同等 UTC 值存储更新值，具体取决于为更新指定的值的类型 (DateTimeKind)。 如果指定值是 UTC 类型，它直接存储。 否则，存储 UTC 等效值。 检索格式化的值基于用户的时区和区域设置将 UTC 转换为用户的当前时区。 对于 OData 终结点，属性公开为 DateTimeOffset。 此行为用于系统属性，类似 CreatedOn 和 ModifiedOn，并且无法更改。 应将此行为用于您要包含区域信息存储的日期和时间值的自定义属性。
DateOnly	在系统中将包含时间值的实际日期值存储为 12:00 AM (00:00:00)。 对于检索和更新操作，不会执行时区转换，时间值始终为上午 12 AM (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 = "UserLocal" 设置 DateTimeBehavior 属性的值

在创建时日期和时间属性时如果不指定行为，属性默认将随 UserLocal 一起创建。 有关完整示例代码的信息，请参阅示例：转换日期和时间行为。

重要

• 一旦创建日期和时间属性时将行为设置为 DateOnly 或 TimeZoneIndependent，则无法更改属性的行为。详细信息：更改日期及时间属性的行为

• 当在脱机模式下在 Dynamics 365 for Outlook 客户端的早期版本中被编辑时，带 DateOnly 或 TimeZoneIndependent 行为的日期和时间属性会被视为拥有 UserLocal 行为。 这是因为客户端不理解新行为，因此不会将其与 UserLocal（早于 CRM Online 2015 更新 1 或 Dynamics 365（内部部署）的 Dynamics 365 版本中的现有行为）区别对待。 日期和时间属性不会在升级时被转换到新行为，所以这里的最佳做法是在定制员采用新行为之一前，将所有 Dynamics 365 for Outlook 客户端升级到最新版本。 联机时，编辑有新行为的字段的数据效果良好。

  较旧的 Dynamics 365 for Outlook 客户端同样不理解早于 1/1/1900（早于 CRM Online 2015 更新 1 和 Dynamics 365（内部部署）的 Dynamics 365 版本中日期和时间类型支持的最早值）的日期。 脱机时，用户将无法打开日期早于 1/1/1900 的记录。 但是，联机时将正常工作。 您还必须升级到 Dynamics 365 for Outlook 客户端的最新版本，才能在脱机模式下使用日期早达 1/1/1753 12:00 AM 的属性。

• 如果您使用自定义代码在 Dynamics 365 实例中实现日期时间行为，则由于新行为所致，它可能不能按预期在 CRM Online 2015 更新 1 和 Dynamics 365（内部部署）中工作。

指定日期及时间属性的格式

使用 DateTimeAttributeMetadata.Format 属性指定属性的日期/时间显示格式，不考虑它如何在系统中存储。 您可以使用 DateTimeFormat 枚举指定显示格式：DateAndTime 或 DateOnly。

如果 DateTimeBehavior 属性设置为 DateOnly，则无法将 Format 属性的值设置或更改为 DateAndTime。

DateOnly 行为不支持的日期和时间查询运算符

时间相关查询运算符不受 DateOnly 行为支持。 除了此处列出的时间特定查询运算符外，所有其他查询运算符均受支持。

• X 分钟以前

• X 小时以前

• 最近 X 小时

• 今后 X 小时

详细信息：FetchXML 中的会计日期和“早于”日期/时间查询运算符

更改日期及时间属性的行为

如果您在您的 Dynamics 365 实例中有系统定制员角色，并日期和时间属性的 CanChangeDateTimeBehavior 托管属性设置为 True，可以更新日期和时间属性以更改其行为。

注意

在更改日期和时间属性的行为之前，应查看属性的所有依赖项，如业务规则、工作流和计算或汇总属性，确保行为更改没有导致出现问题。 系统定制员可以使用 CanChangeDateTimeBehavior 托管属性限制修改现有的日期和时间属性的行为。

至少，在更改日期和时间属性的行为后，您应该打开依赖于更改的日期和时间属性的每个业务规则、工作流、计算属性和汇总属性记录，查看信息，然后保存记录以确保使用了最新的属性行为和值。

在更改计算或汇总属性的数据和时间行为后，打开计算或汇总字段定义编辑器，并保存字段定义以确保属性在行为更改后仍然有效。 系统定制者可以通过单击 Dynamics 365 中自定义区域的“字段类型”旁边的“编辑”，打开计算或汇总属性的字段定义编辑器。详细信息：定义计算字段和定义汇总字段

• 默认情况下，自带和自定义实体的 CreatedOn 和 ModifiedOn 属性的行为设置为 UserLocal，CanChangeDateTimeBehavior 托管属性设置为 False，表示您无法更改这些属性的行为。 虽然用户可以更改自定义实体的这些属性的 CanChangeDateTimeBehavior 托管属性的值，但是，仍然不能更改属性的行为。

• 对于新的自定义日期和时间属性，CanChangeDateTimeBehavior 托管属性设置为 True。 这意味着您可以将自定义日期和时间属性的行为从 UserLocal 更改为 DateOnly 或 TimeZoneIndependent，不允许其他转换行为。

  对于升级到 CRM Online 2016 更新 或 Dynamics 365（内部部署）的 Dynamics 365 组织的一部分的日期和时间属性，CanChangeDateTimeBehavior 托管属性设置为 True，除非属性或父实体不可自定义。

  备注

  在将属性的 DateTimeBehavior 属性从 UserLocal 更新到 DateOnly 时，请确保同时将 Format 属性从 DateAndTime 更改为 DateOnly。 否则，将出现异常。

• 默认情况下，CRM Online 2015 更新 1 和 Dynamics 365（内部部署）中的以下自带日期和时间属性设置为 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 2016 更新 或 Dynamics 365（内部部署）的组织，这些属性的行为设置为 UserLocal，CanChangeDateTimeBehavior 托管属性设置为升级的组织中的 True，您只能将这些属性的行为更改为 DateOnly。 不允许其他行为转换。

在更新属性的行为后，必须发布自定义才能使更改生效。 更新日期和时间属性的行为确保属性行为更改后输入/更新的所有值，都根据新行为存储在系统中。 这不会影响已经存储在数据库中的值，它们继续存储为 UTC 值。 但是，当您使用 SDK 检索现有值或在 UI 进行查看时，现有值根据属性的新行为显示。 例如，如果您在客户实体上将自定义属性的行为从 UserLocal 更改为 DateOnly 并使用 SDK 检索现有客户记录，日期和时间将显示为 <Date> 后面跟时间，即 12 AM (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 中检索时由 Dynamics 365 根据新行为显示，如前面部分所述。 对于行为已经从 UserLocal 更改为 DateOnly 的属性，您可以将数据库中现有的 UTC 值转换为适当的 DateOnly 值，避免使用 ConvertDateAndTimeBehaviorRequest 消息引起的数据异常。

消息让您可以指定转换规则 (ConversionRule)，以选择将值从 UTC 转换为 DateOnly 时使用的时区。 您可以指定以下转换规则之一：

• SpecificTimeZone：根据指定的 Dynamics 365 时区代码将 UTC 值转换为 DateOnly 值。 在这种情况下，您还需要为 TimeZoneCode 参数指定值。

• CreatedByTimeZone：将 UTC 值转换为创建记录用户在 UI 能看到的 DateOnly 值。

• OwnerTimeZone：将 UTC 值转换为拥有记录用户在 UI 能看到的 DateOnly 值。

• LastUpdatedByTimeZone：将 UTC 值转换为最后更新记录用户在 UI 能看到的 DateOnly 值。

您可以使用 DateTimeBehaviorConversionRule 类的四成员之一为 ConversionRule 参数指定有效值。

备注

• ConvertDateAndTimeBehaviorRequest 属性只有当您使用 CRM Online 2015 更新 1 或 Dynamics 365（内部部署）时才可用。 在 Dynamics 365 早期版本中不可用。

• 您必须在您的 Dynamics 365 实例中拥有系统管理员角色才能执行 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：行为和日期及时间字段的格式
自定义实体属性元数据

Microsoft Dynamics 365

© 2017 Microsoft。 保留所有权利。 版权