Image attributes

Certain system entities and all custom entities support images. Those entities that do support images can contain both a thumbnail and a full-size primary image. The thumbnail image can be seen in the web application when viewing the entity's form data. There can be multiple image attributes in an entity instance but there can be only one primary image. However, you can change the primary image from one image to another by setting IsPrimaryImage for that attribute to true. Each full-sized image attribute is limited to 30 MB in size. The SchemaName of the entity image attribute is EntityImage. More information: Entity images.

Thumbnail images and image metadata are stored in Common Data Service, which includes the information needed to retrieve the full image. Full images are stored in file storage on the Azure blob to reduce data storage consumption.

Web API (REST) .NET API (SOAP)
ImageAttributeMetadata ImageAttributeMetadata
IsPrimaryImage, MaxHeight, MaxWidth IsPrimaryImage, MaxHeight, MaxWidth

In addition to image attributes, custom entities support zero or more file attributes that can contain any file data. These file attributes can contain a much larger amount of data than image attributes. For more information see File attributes.

Note

The ability to store more than one image attribute in an entity instance, storage of image data in an Azure blob, a maximum image size of 30MB, and file attributes are supported in SdkClientVersion 9.0.45.329 or greater and Web API version 9.1 or greater.

Supporting attributes

When an image attribute is added to an entity some additional attributes are created to support it.

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}/image/download.aspx?entity={1}&attribute={2}&id={3}&timestamp={4}
  • 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:
    https://myorg.crm.dynamics.com/image/download.aspx?attribute=entityimage&entity=contact&id={ECB6D3DF-4A04-E311-AFE0-00155D9C3020}&timestamp=635120312218444444

EntityImageId

Attribute Type Name: UniqueIdentifierType

The unique identifier of the image

MaxSizeInKB attribute

This value represents the maximum size (in kilobytes) of the image data that the attribute can contain. Set this value to the smallest useable data size appropriate for your particular application. See the MaxSizeInKB property for the allowable size limit and the default value.

Note

MaxSizeInKB is set when the Image attribute is added to an entity. This cannot be changed after it is set.

CanStoreFullImage attribute

This value indicates if an image attribute can store a full image. See the CanStoreFullImage property.

Retrieve image data

To download thumbnail image attribute data, use the following APIs.

Web API (REST) .NET API (SOAP)
GET /api/data/v9.1/<entity-type(id)>/<image-attribute-name>/$value RetrieveRequest or RetrieveMultipleRequest

Note

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.

Image data transfers from the web service endpoints are limited to a maximum of 16 MB data in a single service call. Image data greater that that amount must be divided into 4 MB or smaller data blocks (chunks) where each block is received in a separate API call until all image data has been received. It is your responsibility to join the downloaded data blocks to form the complete image by combining the data blocks in the same sequence as the blocks were received.

More information on chunking: File attributes.

To download the full image attribute data use the following APIs.

Web API (REST) .NET API (SOAP)
none InitializeFileBlocksDownloadRequest
GET /api/data/v9.1/<entity-type(id)>/<image-attribute-name>/$value?size=full DownloadBlockRequest

Note that in this case the image attribute download makes use of the file attribute message requests.

Example: REST thumbnail download

Request

GET [Organization URI]/api/data/v9.1/accounts(b9ccec62-f266-e911-8196-000d3a6de638)/myentityimage/$value

Headers:
Content-Type: application/octet-stream

Response

204 No Content

Body:
byte[]

Example: REST full image download (<=16MB)

Request

GET [Organization URI]/api/data/v9.1/accounts(C0864F1C-0B71-E911-8196-000D3A6D09B3)/myentityimage/$value?size=full

Headers:
Content-Type: application/octet-stream

Response

204 No Content

Body:
byte[]

Response Headers:
x-ms-file-name: "sample.png"
x-ms-file-size: 12345

In the above example, the query string parameter size=full indicates to download the full image. The file name and size will be provided in the response headers.

Example: REST full image download (>16MB)

Request

GET [Organization URI]/api/data/v9.1/accounts(C0864F1C-0B71-E911-8196-000D3A6D09B3)/myentityimage/$value?size=full

Header:
Range: bytes=0-1023/8192

Response

206 Partial Content

Body:
byte[]

Response Headers:
x-ms-file-name: "sample.png"
x-ms-file-size: 8192
Location: api/data/v9.1/accounts(id)/myentityimage?FileContinuationToken

In the above example, the Range header indicates the first chunked download of 1024 bytes for an image that is 8192 bytes in total.

Upload image data

To update images, set the value of the image attribute to a byte array that contains the content of the image file. Thumbnail images are cropped and resized to a 144x144 pixel square by the web service to reduce the size of the data before being saved. The reduction in size follows these rules:

  • 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

300x428
image after resize

144x144
Second image resize example

91x130
second resize example

91x91

Images can be uploaded either in full up to the maximum size configured, or in chunks.

Note

As of this article's publication date, the restriction of using chunked upload for images greater than 16 MB has been removed. The chunking APIs will continue to be available to maintain backwards compatibility with existing solutions.

To upload full image data in single call, use the following APIs.

Web API (REST) .NET API (SOAP)
PUT or PATCH /api/data/v9.1/<entity-type(id)>/<image-attribute-name> CreateRequest or UpdateRequest

Example: REST full image upload

Request

PUT [Organization URI]/api/data/v9.1/accounts(C0864F1C-0B71-E911-8196-000D3A6D09B3)/myentityimage

Header:
Content-Type: application/octet-stream
x-ms-file-name: sample.png

Body:
byte[]

After the upload is completed, a thumbnail image is automatically created by the web service.

If your code is using the legacy method, image data transfers from the web service endpoints are limited to a maximum of 16 MB data in a single service call. Image data 16MB or greater must be divided into 4 MB or smaller data blocks (chunks) where each block is uploaded in a separate API call until all image data has been received. It is your responsibility to divide the image data into blocks up to 4MB in size and upload them in the correct sequence.

More information on chunking: File attributes.

To use the legacy chunking to upload image data greater than 16MB in size, use the following APIs.

Web API (REST) .NET API (SOAP)
none InitializeFileBlocksUploadRequest
PATCH /api/data/v9.1/<entity-type(id)>/<image-attribute-name> UploadBlockRequest
none CommitFileBlocksUploadRequest

Example: REST upload with chunking (first request)

Request

PATCH [Organization URI]/api/data/v9.1/accounts(id)/myentityimage

Headers:
x-ms-transfer-mode: chunked
x-ms-file-name: sample.png

Response

Response:
200 OK

Response Headers:
x-ms-chunk-size: 4096
Accept-Ranges: bytes 
Location: api/data/v9.1/accounts(id)/myentityimage?FileContinuationToken

In the above example, the x-ms-transfer-mode: chunked header indicates a chunked upload.

Example: REST upload with chunking (next request)

Request

PATCH [Organization URI]/api/data/v9.1/accounts(id)/myentityimage?FileContinuationToken

Headers:
Content-Range: bytes 0-4095/8192
Content-Type: application/octet-stream
x-ms-file-name: sample.png

Body:
byte[]

Response

204 No Content

In the above request, the next block of data is being uploaded. After all image data has been received by the web service, a thumbnail image is automatically created by the web service.

See also

File attributes
Introduction to Entities in Dynamics 365
Introduction to entity attributes in Dynamics 365
Sample: Set and retrieve entity images