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.

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.

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.

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

To upload image data less than or equal to 16MB in size, 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

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 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 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

You could also use the Initialize/Upload/Commit block message requests for an image attribute <=16MB in size (instead of the Create/Update message requests) if you chunk the image data.

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

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.

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

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