Introduction to entity attributes in Dynamics 365 Customer Engagement (on-premises)

發行項
08/26/2022

Entities include a set of attributes that represent the data that can be included within each record. Developers need to understand the different types of attributes and how to work with them. The metadata for attributes describes the valid operations and behaviors of different types of attributes. Several types of attributes can be grouped by common behaviors.

The specific experience developers will have depends on their style of development. More information: Entity programming (early bound vs. late bound vs. developer extensions).

Note

This topic includes references to many metadata properties. To view the entity metadata for your organization, install the Metadata Browser solution described in Browse the metadata for your organization. You can also browse the reference documentation for entities in the Entity Reference.

Valid operations on attributes

Each attribute has metadata that describes the operations it supports. You need to be aware of the operations that are valid for the attributes you work with.

AttributeMetadata property	Description
IsValidForCreate	True if this attribute value is valid to be set when a record is created, otherwise false.
IsValidForRead	True if this attribute value can be retrieved, otherwise false.
IsValidForUpdate	True if this attribute value is valid to be set when a record is updated, otherwise false.

Types of attributes

Attributes are defined in metadata and the AttributeMetadata.AttributeTypeName property contains the value describing the type. The static AttributeTypeDisplayName members provide the list of possible types.

Note

The older AttributeType property contains data that is mostly aligned with AttributeTypeName, except that it shows ImageType attributes as Virtual. You should use the AttributeTypeName property rather than the AttributeType property.

The following section groups the types of attributes into the following categories so that you can more easily compare them:

Categorization data attributes
Collection data attributes
Date and time data attribute
Image data attributes
Quantity data attributes
Reference data attributes
String data attributes
Unique Identifier data attributes
Virtual attributes

Categorization data attributes

Each of the six attributes in this group inherit from a common EnumAttributeMetadata base class and use a pre-defined set of valid values to group records into categories.

Set Picklist, Status, and State attributes using an OptionSetValue with a Value property set to an integer that represents a valid option within the metadata.

Set Boolean attributes using a Boolean value, but recognize that this is a categorization limited to just two options.

EntityName attributes use a string value that is constrained to be a valid entity logical name in the organization.

Custom Picklist and Boolean attributes can be defined as calculated attributes. More information: Calculated attributes.

Metadata Type	AttributeTypeName Value	Description
PicklistAttributeMetadata	PicklistType	Valid values are set in the OptionMetadata.`Value` for that attribute defined within the OptionSetMetadata.Options. Within the customization tools in the application these attributes are called Option Set fields.
MultiSelectPicklistAttributeMetadata	MultiSelectPicklistType	Note: Multi-select picklist attributes were added with the Dynamics 365 Customer Engagement (on-premises) Version 9.x. More information Multi-Select Picklist attributes. Within the customization tools in the application these attributes are called Multi-Select Option Set fields.
StatusAttributeMetadata	StatusType	These system attributes are named `StatusCode`. Valid values are set in the StatusOptionMetadata.`Value` for that attribute defined within the OptionSetMetadata.Options. The `StatusOptionMetadata.State` property for each option describes the valid value for the corresponding `StateCode` value. Before you set the `StatusCode` you should verify that it's valid for the current `StateCode` value. Use the SetStateRequest message to set the `StatusCode` and `StateCode` attribute values when you need to change the state of the record. These attributes may have further restrictions on which values can be set. The StatusOptionMetadata.TransitionData property may contain information on which options are allowed when the EntityMetadata.`EnforceTransitions` value is true. More information: Define custom state model transitions.
StateAttributeMetadata	StateType	These system attributes are named `StateCode`. Valid values are set in the StateOptionMetadata.`Value` for that attribute defined within the OptionSetMetadata.Options. `StateCode` isn't valid for update. After the record is created, the `StateCode` can only be set using the SetStateRequest message. The `StateOptionMetadata.DefaultStatus` property for each option describes the default `StatusCode` that will be used if not set as a parameter in the `SetStateRequest`.
BooleanAttributeMetadata	BooleanType	Boolean attributes can be set directly using a Boolean value, but like the others they also have an OptionSet property with FalseOption and TrueOption properties that correspond to the Boolean options. Each of these properties defines a set of localized labels that represent what true and false mean for the attribute. Within the customization tools in the application these attributes are called Two Options fields because the meaning for each option can be any mutually exclusive pair of options, not just true and false. For example, the options might be large and small.
EntityNameAttributeMetadata	EntityNameType	These system attributes are paired with a unique identifier or reference attribute that is valid for multiple types. The value of this attribute is a string value representing the logical name of an entity. If the corresponding reference attribute is an EntityReference, the value of this attribute is the same as the `EntityReference.Name` property value.

Collection data attributes

These system attributes return collections of values.

AttributeTypeName Value Description

CalendarRulesType There are no actual attributes that use the CalendarRulesType. When using the early binding style, the code generation tool will create the following two simulated attributes that aren't present in the metadata. These attributes actually represent a view of the calendar rules records associated in a one-to-many relationship to the entity instance.
- Calendar.CalendarRules relationship: calendar_calendar_rules
- Service.CalendarRules relationship: service_calendar_rules

PartyListType The following attributes allow for multiple EntityReference to be set for various types of activities.
ActivityPointer.allparties
Appointment.OptionalAttendees
Appointment.Organizer
Appointment.requiredattendees
CampaignActivity.from
CampaignActivity.Partners
CampaignResponse.Customer
CampaignResponse.from
CampaignResponse.Partner
Email.bcc
Email.cc
Email.from
Email.to
Fax.from
Fax.to
Letter.bcc
Letter.cc
Letter.from
Letter.to
PhoneCall.from
PhoneCall.to
RecurringAppointmentMaster.OptionalAttendees
RecurringAppointmentMaster.Organizer
RecurringAppointmentMaster.RequiredAttendees
ServiceAppointment.Customers
ServiceAppointment.Resources
SocialActivity.From
SocialActivity.Resources
SocialActivity.To

AttributeTypeName Value	Description
CalendarRulesType	There are no actual attributes that use the `CalendarRulesType`. When using the early binding style, the code generation tool will create the following two simulated attributes that aren't present in the metadata. These attributes actually represent a view of the calendar rules records associated in a one-to-many relationship to the entity instance. - `Calendar.CalendarRules` relationship: `calendar_calendar_rules` - `Service.CalendarRules` relationship: `service_calendar_rules`
PartyListType	The following attributes allow for multiple EntityReference to be set for various types of activities. ActivityPointer.allparties Appointment.OptionalAttendees Appointment.Organizer Appointment.requiredattendees CampaignActivity.from CampaignActivity.Partners CampaignResponse.Customer CampaignResponse.from CampaignResponse.Partner Email.bcc Email.cc Email.from Email.to Fax.from Fax.to Letter.bcc Letter.cc Letter.from Letter.to PhoneCall.from PhoneCall.to RecurringAppointmentMaster.OptionalAttendees RecurringAppointmentMaster.Organizer RecurringAppointmentMaster.RequiredAttendees ServiceAppointment.Customers ServiceAppointment.Resources SocialActivity.From SocialActivity.Resources SocialActivity.To

Date and time data attribute

Attributes with the metadata AttributeTypeName value of DateTimeType. Set these attributes using System.DateTime.

The DateTimeAttributeMetadata.Format property can be one of the following DateTimeFormat values:

DateAndTime: Display the date and time.
DateOnly: Display the date only

Custom Date and time attributes can be defined as calculated or rollup attributes. More information: Calculated and Rollup Attributes.

Image data attributes

For those entities, which support image attributes, the SchemaName of the entity image attribute is always EntityImage.

More information: Image Attributes, Entity images and Sample: Set and retrieve entity images.

Quantity data attributes

Attributes in this category use numerical data. Each of these attributes has a MaxValue and MinValue metadata property to set a range of valid values.

Custom Decimal, Integer, and Money attributes can be defined as calculated or rollup attributes. More information: Calculated and Rollup Attributes.

Metadata Type	AttributeTypeName Value	Description
BigIntAttributeMetadata	BigIntType	BigInt attributes are for internal use only.
DecimalAttributeMetadata	DecimalType	Use decimal values. The Precision metadata property sets the precision to be used for the attribute.
DoubleAttributeMetadata	DoubleType	Use double values. The Precision metadata property sets the precision to be used for the attribute.
IntegerAttributeMetadata	IntegerType	Use int values.
MoneyAttributeMetadata	MoneyType	Use Money which has a decimal``Value property. Each Money attribute has a corresponding system calculated base currency money attribute that is used to calculate the value in the organization’s base currency when multiple currencies have been enabled for the organization. The IsBaseCurrency property identifies whether a money attribute represents the base currency. More information: Transaction Currency (Currency) Entity. Money attributes also have a PrecisionSource metadata property that can specify the level of precision that should be used. The integer value in this property determines whether: - 0: The precision is determined by the Precision metadata property. - 1: The `Organization.PricingDecimalPrecision` value. - 2: The `TransactionCurrency.CurrencyPrecision` that is associated with the current record.

Reference data attributes

These attributes are commonly referred to as lookup attributes and each of them contain an EntityReference value. The difference between these attributes is the kinds of entities they can associate to. The Targets metadata property contains a String[] of the valid entity logical names that represent valid targets for the lookup. Custom lookup attributes can only have a single type in the Targets property.

The PartyListType also represent a kind of reference data attribute, but since they contain a collection of references, they are included in the Collection data attributes.

Metadata Type	AttributeTypeName Value	Description
LookupAttributeMetadata	CustomerType	These system lookup attributes can link to Account or Contact entity records. Contact.ParentCustomerId Contract.BillingCustomerId Contract.CustomerId ContractDetail.CustomerId CustomerOpportunityRole.CustomerId CustomerRelationship.CustomerId CustomerRelationship.PartnerId Entitlement.CustomerId Incident.CustomerId Invoice.CustomerId Lead.CustomerId Opportunity.CustomerId Quote.CustomerId SalesOrder.CustomerId SocialActivity.PostAuthor SocialActivity.PostAuthorAccount SocialProfile.CustomerId
LookupAttributeMetadata	LookupType	These lookup attributes can be used to set references to a record of the type indicated by the Targets metadata property. Some system lookups don't have a value set for the `Targets` property, but the intended entity should be apparent based on the entity relationship that is associated to the lookup.
LookupAttributeMetadata	OwnerType	These system lookups are always named `OwnerId` and each user-owned entity will have one. They can reference either SystemUser or Team records.

String data attributes

There are two types of attributes that use string data.

Metadata Type	AttributeTypeName Value	Description
StringAttributeMetadata	StringType	An attribute for a string value to which a format can be applied. More information: StringAttributeMetadata formats. Custom String attributes can be defined as calculated attributes. More information: Calculated attributes.
MemoAttributeMetadata	MemoType	An attribute for a string value intended for notes. This attribute is equivalent to String attributes with the `FormatName` property value set to `TextArea`.

Unique identifier data attributes

Attributes with the metadata AttributeTypeName value of UniqueidentifierType contain nullable System.Guid values.

Each entity instance includes one attribute that represents the unique identifier for the record. This attribute has a schema name that follows the naming convention <entity schema name>+ID. For example, the Account entity the schema name for the attribute representing the unique identifier is named AccountId. This value is also available directly using the Entity.Id property. This attribute is always returned when you retrieve an entity, even if you don't include it in the ColumnSet of a query. This value is null for a newly instantiated entity. While it is valid to set a Guid value to define the unique identifier when you create a new record, for best performance we recommend that you leave it null and allow the system to assign a value when the record is created. After a record is saved this value becomes read-only.

Entities may include other unique identifier attributes depending on the capabilities of the entity. For example, entities that are enabled for business processes will contain unique identifier attributes for ProcessId and StageId to track the current business process associated with the record. Certain system relationships that might normally use an EntityReference value will use a unique identifier instead. For example the Account and Contact entities each have two unique identifier attributes (Address1_AddressId and Address2_AddressId) that correspond to CustomerAddress records created when an Account or Contact is created.

Virtual attributes

The metadata for an entity will include some attributes with the metadata AttributeTypeName value of VirtualType. These attributes can't be used in code.

Logical attributes

Logical attributes contain values that are stored in different database tables than other attributes in the entity. In most cases this internal implementation isn't relevant to working with Dynamics 365 Customer Engagement (on-premises). When you use logical attributes as sources for a calculated field the values in the calculated field can't be sorted. Use the AttributeMetadata.IsLogical property to detect if an attribute is a logical attribute.

The most common logical attributes are those which store address information in several special entities: CompetitorAddress, CustomerAddress, InternalAddress, LeadAddress, and PublisherAddress. There are eight system entities that include a complete set of attributes for two addresses using logical attributes. Each of these attributes begins with “Address*”, such as Address1_City or Address2_Latitude.

共用方式為