Dataverse file columns store binary content on a table row, but they are not ordinary attributes. A standard row create or update request does not contain the file bytes, and retrieving the row returns file metadata rather than the content. This guide explains how to inspect a file column, upload a file through the Web API or .NET SDK, and download it without confusing the file identifier with the file itself.
1. Understand the Dataverse file-column model
Imagine an Account table with a file column named new_contractfile. Dataverse also exposes a companion read-only name attribute, new_contractfile_name. When you retrieve the Account, the file attribute is an identifier; the companion attribute contains the file name. Neither is the file’s binary content.
File columns are different from Notes attachments stored in the Annotation table. Choose the API based on the storage model used by your application.
2. Check the column’s configured maximum size
Inspect the file attribute metadata before accepting an upload. Replace the organization URL, table logical name, and column logical name:
GET https://YOURORG.crm.dynamics.com/api/data/v9.2/EntityDefinitions(LogicalName='account')/Attributes(LogicalName='new_contractfile')/Microsoft.Dynamics.CRM.FileAttributeMetadata?$select=MaxSizeInKB
Accept: application/json
OData-Version: 4.0
OData-MaxVersion: 4.0
Use the returned MaxSizeInKB value to validate the file size before starting the transfer. The configured column limit still applies when you use chunked transfer. Also validate the file type and apply any required malware scanning; a file name or MIME type supplied by a client is not proof that the content is safe.
3. Upload a smaller file with one Web API request
For files within the supported single-request size, send the raw binary body to the file-column property. Do not wrap the bytes in a JSON object or Base64-encode them into JSON. The example below uses an existing Account row:
PATCH https://YOURORG.crm.dynamics.com/api/data/v9.2/accounts(ACCOUNT-GUID)/new_contractfile
Authorization: Bearer ACCESS_TOKEN
OData-Version: 4.0
OData-MaxVersion: 4.0
Accept: application/json
Content-Type: application/octet-stream
x-ms-file-name: contract.pdf
<raw binary file content>
A successful upload commonly returns 204 No Content. Confirm the exact request shape and size limit against the current Dataverse file-column documentation for your environment. The caller must have the required table and row access, and the record and file column must exist.
4. Upload a file in blocks with the Dataverse .NET SDK
For block-based uploads, the SDK exposes InitializeFileBlocksUploadRequest, UploadBlockRequest, and CommitFileBlocksUploadRequest. Initialize once to obtain a continuation token, upload each block using that token, then commit the block IDs in the same order in which the bytes were read.
The following illustrative helper uses a 4 MiB buffer and an authenticated IOrganizationService. Add the Microsoft.CrmSdk.CoreAssemblies package to the project and adapt exception handling, telemetry, and size validation to your application.
using System;
using System.Collections.Generic;
using System.IO;
using System.Text;
using Microsoft.Crm.Sdk.Messages;
using Microsoft.Xrm.Sdk;
public static Guid UploadFileColumn(
IOrganizationService service,
EntityReference target,
string fileAttributeName,
string filePath,
string mimeType)
{
var file = new FileInfo(filePath);
if (!file.Exists || file.Length == 0)
throw new InvalidOperationException("A non-empty upload file is required.");
var initialized = (InitializeFileBlocksUploadResponse)service.Execute(
new InitializeFileBlocksUploadRequest
{
Target = target,
FileAttributeName = fileAttributeName,
FileName = file.Name
});
var token = initialized.FileContinuationToken;
var blockIds = new List<string>();
var buffer = new byte[4 * 1024 * 1024];
using (var input = file.OpenRead())
{
int count;
while ((count = input.Read(buffer, 0, buffer.Length)) > 0)
{
var block = new byte[count];
Buffer.BlockCopy(buffer, 0, block, 0, count);
// A GUID in "N" format is 32 ASCII characters.
// Its Base64 representation has a consistent length.
var blockId = Convert.ToBase64String(
Encoding.ASCII.GetBytes(Guid.NewGuid().ToString("N")));
service.Execute(new UploadBlockRequest
{
BlockId = blockId,
BlockData = block,
FileContinuationToken = token
});
blockIds.Add(blockId);
}
}
var committed = (CommitFileBlocksUploadResponse)service.Execute(
new CommitFileBlocksUploadRequest
{
FileName = file.Name,
MimeType = string.IsNullOrWhiteSpace(mimeType)
? "application/octet-stream"
: mimeType,
BlockList = blockIds.ToArray(),
FileContinuationToken = token
});
return committed.FileId;
}
Example call:
var account = new EntityReference(
"account",
new Guid("11111111-2222-3333-4444-555555555555"));
Guid fileId = UploadFileColumn(
service,
account,
"new_contractfile",
@"C:\Integration\contract.pdf",
"application/pdf");
The block IDs are Base64-encoded identifiers and must have a consistent length within the upload. Preserve their original order when committing; do not sort them. For production, also validate the configured file limit, handle transient service faults appropriately, and record a correlation identifier without logging file contents or secrets.
5. Download the file in blocks
Use InitializeFileBlocksDownloadRequest to obtain the file size, continuation token, and whether chunked download is supported. Then request each block with its offset and length. Advance the offset by the number of bytes actually returned.
using System;
using System.IO;
using Microsoft.Crm.Sdk.Messages;
using Microsoft.Xrm.Sdk;
public static void DownloadFileColumn(
IOrganizationService service,
EntityReference target,
string fileAttributeName,
string destinationPath)
{
var initialized = (InitializeFileBlocksDownloadResponse)service.Execute(
new InitializeFileBlocksDownloadRequest
{
Target = target,
FileAttributeName = fileAttributeName
});
long fileSize = initialized.FileSizeInBytes;
long offset = 0;
using (var output = File.Create(destinationPath))
{
if (fileSize == 0)
return;
long blockSize = initialized.IsChunkingSupported
? 4L * 1024 * 1024
: fileSize;
while (offset < fileSize)
{
long length = Math.Min(blockSize, fileSize - offset);
var downloaded = (DownloadBlockResponse)service.Execute(
new DownloadBlockRequest
{
FileContinuationToken = initialized.FileContinuationToken,
Offset = offset,
BlockLength = length
});
if (downloaded.Data == null || downloaded.Data.Length == 0)
throw new InvalidOperationException(
"An empty block was returned before the file was complete.");
output.Write(downloaded.Data, 0, downloaded.Data.Length);
offset += downloaded.Data.Length;
}
}
}
Do not assume chunking is available in every storage configuration. Respect IsChunkingSupported; when it is false, the download must be requested as a single block. Also consider streaming the output to controlled storage and enforcing an application-level maximum before allocating or writing large files.
6. Retrieve file metadata from the row
To check whether a file is present and display its name, select the file column and its companion name attribute:
GET https://YOURORG.crm.dynamics.com/api/data/v9.2/accounts(ACCOUNT-GUID)?$select=name,new_contractfile,new_contractfile_name
Accept: application/json
OData-Version: 4.0
OData-MaxVersion: 4.0
A populated file attribute indicates that a file is associated with the row, but its value is not the binary content. Use the documented file download operation to retrieve the bytes.
7. Common implementation pitfalls
- Sending bytes in normal row JSON: use the file-column endpoint or file-block messages.
- Using the display label: API operations require the logical name, such as
new_contractfile. - Skipping size validation: check the column’s configured maximum before transfer.
- Reordering block IDs: commit the IDs in the original byte-stream order.
- Assuming chunk support: inspect the download response’s
IsChunkingSupportedvalue. - Confusing metadata with content: the row’s file ID and file name do not contain the file bytes.
- Trusting client-supplied MIME types: validate file content and apply security scanning where required.
- Ignoring failures partway through: log the operation context, handle transient faults, and define how abandoned uploads are monitored and retried.
8. Testing checklist
- Confirm the table and file-column logical names in the target environment.
- Read and enforce the configured maximum file size.
- Test a small file with the single-request Web API approach.
- Test a file requiring multiple SDK blocks.
- Download the file and compare its length or checksum with the original.
- Test an oversized file, an invalid row ID, an invalid column name, and a user without required access.
- Test the download path when chunking is not supported by the storage configuration.
Conclusion
Dataverse file columns require dedicated transfer operations rather than ordinary row CRUD. Use a single Web API request when the file and environment fit that method, or use the initialize, upload-block, and commit sequence for block transfers. For downloads, follow the continuation token, file size, offset, and chunk-support flag. These practices help make document integrations more predictable and easier to troubleshoot.
Microsoft documentation: Use file column data in Microsoft Dataverse.