Use file column data

File columns store binary data. File columns may be in any custom or customizable Dataverse table.

File columns are different from the other system columns that can store binary data because you cannot directly set the values in a create or update operation or retrieve the file data with the record. You must use the methods described in this topic to create, retrieve, update, or delete binary data for file columns.

There are several different ways to work with file column data using Web API. All methods are supported equally. Choose the method that works best for you. Because binary files may be large, it is frequently necessary to split the file into multiple chunks, (or blocks) that can be sent or received sequentially or in parallel to improve performance.

File name column

Each file column has a supporting read-only string column that contains the name of the file. The schema name for this column has the same name as the file column, but has _Name appended to it. So if the schema name is sample_FileColumn, the supporting string column will be sample_FileColumn_Name. The logical name for the supporting column will be sample_filecolumn_name.

Note

The file name column does not appear in the Power Apps designer.

Behavior when retrieving

When you retrieve a record and include a file column, the value returned will be a unique identifier for the file. You can use this value to delete the file using the DeleteFile message. There is no other use for this id other than to check whether the column has a value. More information: Use the DeleteFile message.

The following examples show what you can expect when retrieving data from file columns as you would with other columns.

These examples retrieve the name, sample_filecolumn, and sample_filecolumn_name columns for account record with the primary key value of 352edda9-4c52-ed11-bba1-000d3a9933c9.

static void RetrieveAccountRecordWithFileColumns(IOrganizationService service) {

   Entity account = service.Retrieve(
         "account", 
         new Guid("352edda9-4c52-ed11-bba1-000d3a9933c9"), 
         new ColumnSet("name", "sample_filecolumn", "sample_filecolumn_name"));

   Console.WriteLine($"name: {account["name"]}");
   Console.WriteLine($"sample_filecolumn: {account["sample_filecolumn"]}");
   Console.WriteLine($"sample_filecolumn_name: {account["sample_filecolumn_name"]}");
}

Output:

name: Contoso Ltd.
sample_filecolumn: 63a6afb7-4c52-ed11-bba1-000d3a9933c9
sample_filecolumn_name: 25mb.pdf

Note

You must explicitly request the column to return the file id. If you use ColumnSet.AllColumns to true in your query the file column will not be returned. If you used new ColumnSet(true) in the function above, the result would be a System.Collections.Generic.KeyNotFoundException.

More information:

Upload Files

There at three different ways to upload files to a file column:

  • Use Dataverse messages available to both the SDK and Web API
  • Upload a file in a single request using Web API
  • Upload the file in chunks using Web API

Note

You should verify whether the column maximum file size is large enough to accept the file you are uploading. More information: Check maximum file size.

Use Dataverse messages to upload a file

You can use Dataverse messages using the SDK for .NET or Web API. Uploading a file this way requires using a set of three messages:

Message Description
InitializeFileBlocksUpload Use this message to indicate the column that you want to upload a file to. It returns a file continuation token that you can use to upload the file in blocks using the UploadBlock message and with CommitFileBlocksUpload.
UploadBlock Split your file into blocks and generate a blockid for each block. Then make multiple requests until all the blocks have been sent together with the file continuation token.
CommitFileBlocksUpload After you have sent requests for all the blocks using UploadBlock, use this message to commit the upload operation by sending:
- The list of generated blockids
- The name of the file
- The MIME type of the file
- The file continuation token

You can use a function like the following to upload a file using the InitializeFileBlocksUploadRequest, UploadBlockRequest, and CommitFileBlocksUploadRequest classes.

/// <summary>
/// Uploads a file
/// </summary>
/// <param name="service">The service</param>
/// <param name="entityReference">A reference to the record with the file column</param>
/// <param name="fileAttributeName">The name of the file column</param>
/// <param name="fileInfo">Information about the file to upload.</param>
/// <param name="fileMimeType">The mime type of the file, if known.</param>
/// <returns></returns>
static Guid UploadFile(
         IOrganizationService service,
         EntityReference entityReference,
         string fileAttributeName,
         FileInfo fileInfo,
         string fileMimeType = null)
{

   // Initialize the upload
   InitializeFileBlocksUploadRequest initializeFileBlocksUploadRequest = new()
   {
         Target = entityReference,
         FileAttributeName = fileAttributeName,
         FileName = fileInfo.Name
   };

   var initializeFileBlocksUploadResponse =
         (InitializeFileBlocksUploadResponse)service.Execute(initializeFileBlocksUploadRequest);

   string fileContinuationToken = initializeFileBlocksUploadResponse.FileContinuationToken;

   // Capture blockids while uploading
   List<string> blockIds = new();

   using Stream uploadFileStream = fileInfo.OpenRead();

   int blockSize = 4 * 1024 * 1024; // 4 MB

   byte[] buffer = new byte[blockSize];
   int bytesRead = 0;

   long fileSize = fileInfo.Length;
   // The number of iterations that will be required:
   // int blocksCount = (int)Math.Ceiling(fileSize / (float)blockSize);
   int blockNumber = 0;

   // While there is unread data from the file
   while ((bytesRead = uploadFileStream.Read(buffer, 0, buffer.Length)) > 0)
   {
         // The file or final block may be smaller than 4MB
         if (bytesRead < buffer.Length)
         {
            Array.Resize(ref buffer, bytesRead);
         }

         blockNumber++;

         string blockId = Convert.ToBase64String(Encoding.UTF8.GetBytes(Guid.NewGuid().ToString()));

         blockIds.Add(blockId);

         // Copy the next block of data to send.
         var blockData = new byte[buffer.Length];
         buffer.CopyTo(blockData, 0);

         // Prepare the request
         UploadBlockRequest uploadBlockRequest = new()
         {
            BlockData = blockData,
            BlockId = blockId,
            FileContinuationToken = fileContinuationToken,
         };

         // Send the request
         service.Execute(uploadBlockRequest);
   }

   // Try to get the mimetype if not provided.
   if (string.IsNullOrEmpty(fileMimeType))
   {
         var provider = new FileExtensionContentTypeProvider();

         if (!provider.TryGetContentType(fileInfo.Name, out fileMimeType))
         {
            fileMimeType = "application/octet-stream";
         }
   }

   // Commit the upload
   CommitFileBlocksUploadRequest commitFileBlocksUploadRequest = new()
   {
         BlockList = blockIds.ToArray(),
         FileContinuationToken = fileContinuationToken,
         FileName = fileInfo.Name,
         MimeType = fileMimeType
   };

   var commitFileBlocksUploadResponse =
         (CommitFileBlocksUploadResponse)service.Execute(commitFileBlocksUploadRequest);

   return commitFileBlocksUploadResponse.FileId;

}

More information:

This function includes some logic to try and get the MIME type of the file using the FileExtensionContentTypeProvider.TryGetContentType(String, String) Method if it is not provided. If not found it will set the mime type to application/octet-stream.

Upload a file in a single request using Web API

If the size of the file is less than 128MB, you can upload the file in a single request using the Web API.

The following example uploads a text file named 4094kb.txt to the file column named sample_filecolumn on the account table for a record with accountid equal to cc4ed4a2-8c51-ed11-bba1-000d3a993550.

Request

PATCH [Organization Uri]/api/data/v9.2/accounts(cc4ed4a2-8c51-ed11-bba1-000d3a993550)/sample_filecolumn HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Content-Type: application/octet-stream
x-ms-file-name: 4094kb.txt
Content-Length: 4191273

< binary content removed for brevity>

Response

HTTP/1.1 204 NoContent
OData-Version: 4.0

Upload the file in chunks using Web API

To upload your file in chunks using the Web API, use the following set of requests.

The following example uploads a PDF file named 25mb.pdf to the file column named sample_filecolumn on the account table for a record with accountid equal to 2a9ebdff-8c51-ed11-bba1-000d3a9933c9.

Request

The first request must include this header:x-ms-transfer-mode: chunked

Set the file name using the x-ms-file-name query parameter.

PATCH [Organization Uri]/api/data/v9.2/accounts(2a9ebdff-8c51-ed11-bba1-000d3a9933c9)/sample_filecolumn?x-ms-file-name=25mb.pdf HTTP/1.1
x-ms-transfer-mode: chunked
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

Note

The file name can also be included as a x-ms-file-name request header, but this will not support file names outside the ASCII character set. If the header is used, it will take precedence over the x-ms-file-name query parameter.

Response

HTTP/1.1 200 OK
Accept-Ranges: bytes
Location: [Organization Uri]/api/data/v9.2/accounts(2a9ebdff-8c51-ed11-bba1-000d3a9933c9)/sample_filecolumn?sessiontoken=<sessiontoken value removed for brevity>
OData-Version: 4.0
x-ms-chunk-size: 4194304
Access-Control-Expose-Headers: x-ms-chunk-size

The response Location header includes a URL to use in subsequent requests. It includes a sessiontoken query parameter that indicates that all the requests sent using it are part of the same operation.

The response includes the following headers.

Header Description
x-ms-chunk-size Provides a recommended chunk size in bytes.
Accept-Ranges Indicates the server supports partial requests from the client for file downloads. The value bytes indicates that the range value in subsequent requests should be in bytes.
Access-Control-Expose-Headers Indicates that the x-ms-chunk-size header value should be made available to scripts running in the browser, in response to a cross-origin request.

Request

Subsequent requests should use the value of the Location header returned by the first request so that the sessiontoken value is included.

Each request must contain that portion of the file in the body and the following headers:

Header Description
x-ms-file-name The name of the file.
Content-Type Set to application/octet-stream
Content-Range Using this format:
<unit> <range-start>-<range-end>/<size>
The value of the first request: bytes 0-4194303/25870370 indicates that the measurement is using bytes. This request includes the first 4194303 bytes of a file that is 25870370 bytes (almost 25MB) in size.
Each subsequent request will see this value increase until the entire file has been sent:
bytes 4194304-8388607/25870370
bytes 8388608-12582911/25870370
bytes 12582912-16777215/25870370
bytes 16777216-20971519/25870370
bytes 20971520-25165823/25870370
bytes 25165824-25870369/25870370
Content-Length Indicates the size of the message. In the example above, this value for the last request will be 704546 rather than 4194304.
PATCH [Organization Uri]/api/data/v9.2/accounts(2a9ebdff-8c51-ed11-bba1-000d3a9933c9)/sample_filecolumn?sessiontoken=<sessiontoken value removed for brevity> HTTP/1.1
x-ms-file-name: 25mb.pdf
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Content-Type: application/octet-stream
Content-Range: bytes 0-4194303/25870370
Content-Length: 4194304

< byte[] content removed for brevity>

For each request that contains partial content, the response will be 206 PartialContent.

Response

HTTP/1.1 206 PartialContent
OData-Version: 4.0

For the final request that includes the last chunk of the file, the response will be 204 NoContent.

Response

HTTP/1.1 204 NoContent
OData-Version: 4.0

Check maximum file size

Before you upload a file you can check whether the size of the file exceeds the configured Maximum file size stored in the MaxSizeInKB property.

If you try to upload a file that is too large, you will get the following error:

Name: unManagedidsattachmentinvalidfilesize
Code: 0x80044a02
Number: -2147202558
Message: Attachment file size is too big.

You can use the following examples to check the maximum file size:

/// <summary>
/// Retrieves the MaxSizeInKb property of a file column.
/// </summary>
/// <param name="service">IOrganizationService</param>
/// <param name="entityLogicalName">The logical name of the table that has the column</param>
/// <param name="fileColumnLogicalName">The logical name of the file column.</param>
/// <returns></returns>
/// <exception cref="Exception"></exception>
public static int GetFileColumnMaxSizeInKb(IOrganizationService service, string entityLogicalName, string fileColumnLogicalName) {

   RetrieveAttributeRequest retrieveAttributeRequest = new() { 
         EntityLogicalName = entityLogicalName,
         LogicalName = fileColumnLogicalName
   };

   RetrieveAttributeResponse retrieveAttributeResponse;
   try
   {
         retrieveAttributeResponse = (RetrieveAttributeResponse)service.Execute(retrieveAttributeRequest);
   }
   catch (Exception)
   {
         throw;
   }

   if (retrieveAttributeResponse.AttributeMetadata is FileAttributeMetadata fileColumn)
   {
         return fileColumn.MaxSizeInKB.Value;
   }
   else
   {
         throw new Exception($"{entityLogicalName}.{fileColumnLogicalName} is not a file column.");
   }
}

More information:

Download Files

There at three different ways to download files to a file column:

  • Use Dataverse messages available to both the SDK and Web API
  • Download a file in a single request using Web API
  • Download the file in chunks using Web API

Use Dataverse messages to download a file

You can use Dataverse messages using the SDK for .NET or Web API. Downloading a file this way requires using a pair of messages:

Message Description
InitializeFileBlocksDownload Use this message to indicate the column that you want to download a file from. It returns the file size in bytes and a file continuation token that you can use to download the file in blocks using the DownloadBlock message.
DownloadBlock Request the size of the block, the offset value and the file continuation token.

Once you have downloaded all the blocks, you must join them to create the entire downloaded file.

You can use a function like the following to download a file using the SDK using the InitializeFileBlocksDownloadRequest and DownloadBlockRequest classes.

/// <summary>
/// Downloads a file
/// </summary>
/// <param name="service">The service</param>
/// <param name="entityReference">A reference to the record with the file column</param>
/// <param name="fileAttributeName">The name of the file column</param>
/// <returns></returns>
private static byte[] DownloadFile(
            IOrganizationService service,
            EntityReference entityReference,
            string fileAttributeName)
{
   InitializeFileBlocksDownloadRequest initializeFileBlocksDownloadRequest = new()
   {
         Target = entityReference,
         FileAttributeName = fileAttributeName
   };

   var initializeFileBlocksDownloadResponse =
         (InitializeFileBlocksDownloadResponse)service.Execute(initializeFileBlocksDownloadRequest);

   string fileContinuationToken = initializeFileBlocksDownloadResponse.FileContinuationToken;
   long fileSizeInBytes = initializeFileBlocksDownloadResponse.FileSizeInBytes;

   List<byte> fileBytes = new();

   long offset = 0;
   long blockSizeDownload = 4 * 1024 * 1024; // 4 MB

   // File size may be smaller than defined block size
   if (fileSizeInBytes < blockSizeDownload)
   {
         blockSizeDownload = fileSizeInBytes;
   }

   while (fileSizeInBytes > 0)
   {
         // Prepare the request
         DownloadBlockRequest downLoadBlockRequest = new()
         {
            BlockLength = blockSizeDownload,
            FileContinuationToken = fileContinuationToken,
            Offset = offset
         };

         // Send the request
         var downloadBlockResponse =
                  (DownloadBlockResponse)service.Execute(downLoadBlockRequest);

         // Add the block returned to the list
         fileBytes.AddRange(downloadBlockResponse.Data);

         // Subtract the amount downloaded,
         // which may make fileSizeInBytes < 0 and indicate
         // no further blocks to download
         fileSizeInBytes -= (int)blockSizeDownload;
         // Increment the offset to start at the beginning of the next block.
         offset += blockSizeDownload;
   }

   return fileBytes.ToArray();
}

More information:

Download a file in a single request using Web API

The following example downloads a text file named 4094kb.txt from the file column named sample_filecolumn on the account table for a record with accountid equal to cc4ed4a2-8c51-ed11-bba1-000d3a993550.

Request

GET [Organization Uri]/api/data/v9.2/accounts(cc4ed4a2-8c51-ed11-bba1-000d3a993550)/sample_filecolumn/$value HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

Response

The response includes the following headers.

Header Description
x-ms-file-size The size of the file in bytes.
x-ms-file-name The name of the file.
mimetype The MIME type of the file.
Access-Control-Expose-Headers Indicates that the x-ms-file-size, x-ms-file-name, and mimetype header values should be made available to scripts running in the browser, in response to a cross-origin request.
HTTP/1.1 200 OK
x-ms-file-size: 4191273
x-ms-file-name: 4094kb.txt
mimetype: text/plain
Access-Control-Expose-Headers: x-ms-file-size; x-ms-file-name; mimetype

< byte[] content removed for brevity. >

Download the file in chunks using Web API

To download your file in chunks using the Web API, use the following set of requests.

The following example downloads a PDF file named 25mb.pdf to the file column named sample_filecolumn on the account table for a record with accountid equal to 2a9ebdff-8c51-ed11-bba1-000d3a9933c9.

Request

Use the Range header to specify the number of bytes to return using this format:
<unit>=<range-start>-<range-end>
Where the unit is bytes and the range-start for the first request is 0.

You won't know how many iterations are required to download the entire file until you get the first response where the x-ms-file-size response header tells you the size of the file.

While the <range-start> is smaller than total size of the file, for each subsequent request increment the <range-start> and <range-end> values to request the next chunk of the file.

GET [Organization Uri]/api/data/v9.2/accounts(2a9ebdff-8c51-ed11-bba1-000d3a9933c9)/sample_filecolumn/$value HTTP/1.1
Range: bytes=0-4194303
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

Response

The response includes the following headers:

Header Description
x-ms-file-size The size of the file in bytes.
x-ms-file-name The name of the file.
x-ms-chunk-size Provides a recommended chunk size in bytes.
mimetype The MIME type of the file.
Access-Control-Expose-Headers Indicates that the x-ms-file-size, x-ms-file-name, x-ms-chunk-size, and mimetype header values should be made available to scripts running in the browser, in response to a cross-origin request.
HTTP/1.1 206 PartialContent
x-ms-file-size: 25870370
x-ms-file-name: 25mb.pdf
x-ms-chunk-size: 4194304
mimetype: application/pdf
Access-Control-Expose-Headers: x-ms-file-size; x-ms-file-name; x-ms-chunk-size; mimetype
OData-Version: 4.0

< byte[] content removed for brevity. >

Delete Files

There at two different ways to delete files to a file column:

  • Use the Dataverse DeleteFile message available to both the SDK and Web API
  • Send a DELETE request using Web API to the file column of the record.

Use the DeleteFile message

Using the unique identifier returned from the CommitFileBlocksUploadResponse.FileId or retrieved from from the column as described in Behavior when retrieving, you can delete the file using the DeleteFile message.

You can use a function like the following to delete a file using the unique identifier using the DeleteFileRequest Class.

static Guid DeleteFile(IOrganizationService service, Guid fileId)
{
   DeleteFileRequest deleteFileRequest = new()
   {
      FileId = fileId
   };
   service.Execute(deleteFileRequest);
}

Send DELETE request to the file column

With the Web API, you can delete a file by sending a DELETE request to the location of the file resource.

The following example deletes file data for a column named sample_filecolumn on the account table for a record with accountid equal to 2a9ebdff-8c51-ed11-bba1-000d3a9933c9.

Request

DELETE [Organization Uri]/api/data/v9.2/accounts(2a9ebdff-8c51-ed11-bba1-000d3a9933c9)/sample_filecolumn HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

Response

HTTP/1.1 204 NoContent
OData-Version: 4.0

More information: Delete a single property value

See Also

Column data types > File columns
File columns
Sample: File Operations using Dataverse SDK for .NET
Sample: File Operations using Dataverse Web API