Image attributes

Entity records that include image data provide a unique experience within the application. As a developer you need to understand how you work with image data.

Only certain system entities and custom entities support images. For information about which system entities support images, see Entity images.

Supporting attributes

For those entities which support image attributes, the SchemaName of the entity image attribute is always EntityImage. When an image attribute is added to an entity some additional attributes are created to support it.


Clients that do not use the current .NET assemblies need to include SdkClientVersion with a value of ‘’ or higher in order to receive ImageAttributeMetadata attributes. More information: SdkClientVersion.

EntityImage_Timestamp attribute

Attribute Type Name: BigIntType

The value represents when the image was last updated and is used to help make sure that the latest version of the image is downloaded and cached on the client.

EntityImage_URL attribute

Attribute Type Name: StringType

An absolute URL to display the entity image in a client.

The URL is composed this way:

  • 0 : The organization URL

  • 1 : The entity logical name

  • 2 : The attribute logical name

  • 3 : The EntityImageId value.

  • 4 : The EntityImage_Timestamp value

    For example:{ECB6D3DF-4A04-E311-AFE0-00155D9C3020}&timestamp=635120312218444444


Attribute Type Name: UniqueIdentifierType

The unique identifier of the image

Retrieving image data

When you use RetrieveMultiple or Retrieve the EntityImage is not included when the ColumnSet.AllColumns property is set to true. Because of the potential size of data in this attribute, to return this attribute you must explicitly request it.

The binary data representing the image isn’t returned using the deprecated ExecuteFetchRequest class. You should use RetrieveMultipleRequest instead.

More information: Sample: Set and retrieve entity images.

Uploading image data

To update images set the value of the EntityImage to a byte[] that contains the content of the file. All images are displayed in a 144x144 pixel square. Images will be cropped and resized to reduce the size of the data before being saved.

  • Images with at least one side larger than 144 pixels are cropped on center to 144x144.

  • Images with both sides smaller than 144 are cropped square to their smallest side.

    The following table shows two examples.

Before After
Image before resize

image after resize

Second image resize example

second resize example


More information: Sample: Set and retrieve entity images.

See also

Introduction to Entities in Dynamics 365 Customer Engagement (on-premises)
Introduction to entity attributes in Dynamics 365 Customer Engagement (on-premises)
Sample: Set and retrieve entity images