日時属性の動作と形式

公開日: 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: 日時フィールドの動作と形式

このトピックの内容

日時属性の動作の指定

日時属性の形式の指定

[日付のみ] の動作でサポートされない日付および時刻のクエリ演算子

日時属性の動作の変更

データベース内の既存の日時値の動作の変換

日時属性の動作の指定

DateTimeBehavior クラスを使用して、DateTimeAttributeMetadata.DateTimeBehavior プロパティの値を指定できます。DateTimeBehavior クラスには次のメンバーが含まれます; 各メンバーは、メンバー名と同じ値の文字列を返します:

次のサンプル コードは、新しい日時属性の 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 動作で作成されます。 完全なサンプル コードについては、「サンプル: 日時の動作の変換」を参照してください。

日時属性の形式の指定

DateTimeAttributeMetadata.Format プロパティを使用して、属性がシステムにどのように保存されているかに関係なく、属性の日付/時刻の表示形式を指定します。DateTimeFormat 列挙体を使用して、DateAndTime または DateOnly のいずれかの表示形式を指定できます。

DateTimeBehavior プロパティが DateOnly に設定されている場合、Format プロパティの値を DateAndTime に設定または変更することはできません。

[日付のみ] の動作でサポートされない日付および時刻のクエリ演算子

時刻関連のクエリ演算子は、DateOnly 動作に対してはサポートされません。 ここに表示されている時間固有のクエリ演算子を除いて、すべてのクエリ演算子がサポートされます。

• が X 分よりも古い

• が X 時間よりも古い

• が過去 X 時間

• が今後 X 時間

詳細:FetchXML の会計日クエリ演算子および "older than" 日付/時刻クエリ演算子

日時属性の動作の変更

Dynamics 365 インスタンスでシステム カスタマイザー ロールを所有していて、日時属性の CanChangeDateTimeBehavior 管理プロパティが True に設定されている場合、日時属性を更新してその動作を変更できます。

• 標準のエンティティとユーザー定義エンティティの 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 に行動が変更された属性の場合、ConvertDateAndTimeBehaviorRequest メッセージを使用して、データベース内の既存の UTC 値を適切な DateOnly 値に変換して、データのアノマリを回避することができます。

このメッセージを使用すると、UTC から DateOnly への値の変換に使用するタイム ゾーンを選択するための変換ルール (ConversionRule) を指定できます。 次のいずれかの変換ルールを指定できます。

• SpecificTimeZone: 指定された Dynamics 365 タイム ゾーンに従い、UTC 値を DateOnly 値に変換します。 この場合、TimeZoneCode パラメーターの値を指定する必要もあります。

• CreatedByTimeZone: UTC 値を、レコードを作成したユーザーの UI に表示される DateOnly 値に変換します。

• OwnerTimeZone: UTC 値を、レコードを所有するユーザーの UI に表示される DateOnly 値に変換します。

• LastUpdatedByTimeZone: UTC 値を、レコードを最後に更新したユーザーの UI に表示する DateOnly 値に変換します。

DateTimeBehaviorConversionRule クラスの 4 つのメンバーのいずれかを使用して、ConversionRule パラメーターの有効な値を指定できます。

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. All rights reserved. 著作権