Introduction

Azure AI Document Intelligence simplifies document data extraction, with features like query fields enabling targeted data retrieval. However, using these features with the C# SDK can be tricky. This guide highlights a real-world issue, provides a corrected implementation, and shares best practices for efficient usage.

 

Use case scenario

During the cause of Azure AI Document Intelligence software engineering code tasks or review, many developers encountered an error while trying to extract fields like “FullName,” “CompanyName,” and “JobTitle” using `AnalyzeDocumentAsync`: The error might be similar to

Inner Error: The parameter urlSource or base64Source is required. This is a challenge referred to as parameter errors and SDK changes. Most problematic code are looks like below in C#:

BinaryData data = BinaryData.FromBytes(Content); var queryFields = new List { “FullName”, “CompanyName”, “JobTitle” }; var operation = await client.AnalyzeDocumentAsync( WaitUntil.Completed, modelId, data, “1-2”, queryFields: queryFields, features: new List { DocumentAnalysisFeature.QueryFields } );

One of the reasons this failed was that the developer was using `Azure.AI.DocumentIntelligence v1.0.0`, where `base64Source` and `urlSource` must be handled internally. Because the older examples using `AnalyzeDocumentContent` no longer apply and leading to errors.

 

Practical Solution

1. Using AnalyzeDocumentOptions.


2. Alternative Method using manual JSON Payload.

Using AnalyzeDocumentOptions

The correct method involves using AnalyzeDocumentOptions, which streamlines the request construction using the below steps: 

 

1. Prepare the document content:
   BinaryData data = BinaryData.FromBytes(Content);


2. reate AnalyzeDocumentOptions:
   var analyzeOptions = new AnalyzeDocumentOptions(modelId, data)
   {
   Pages = “1-2”,
   Features = { DocumentAnalysisFeature.QueryFields },
   QueryFields = { “FullName”, “CompanyName”, “JobTitle” }
   };
   

   – `modelId`: Your trained model’s ID.
   – `Pages`: Specify pages to analyze (e.g., “1-2”).
   – `Features`: Enable `QueryFields`.
   – `QueryFields`: Define which fields to extract.

3. Run the analysis:
   Operation operation = await client.AnalyzeDocumentAsync(
   WaitUntil.Completed,
   analyzeOptions
   );
   AnalyzeResult result = operation.Value;
   

    

   
   

 

The reason this works:

• The SDK manages `base64Source` automatically.


• This approach matches the latest SDK standards.


• It results in cleaner, more maintainable code.

Alternative method using manual JSON payload

For advanced use cases where more control over the request is needed, you can manually create the JSON payload. For an example:

var queriesPayload = new
{
queryFields = new[]
{
new { key = “FullName” },
new { key = “CompanyName” },
new { key = “JobTitle” }
}
};

string jsonPayload = JsonSerializer.Serialize(queriesPayload);
BinaryData requestData = BinaryData.FromString(jsonPayload);

var operation = await client.AnalyzeDocumentAsync(
WaitUntil.Completed,
modelId,
requestData,
“1-2”,
features: new List { DocumentAnalysisFeature.QueryFields }
);

 

When to use the above:

• Custom request formats


• Non-standard data source integration

 

Key points to remember

• Breaking changes exist between preview versions and v1.0.0 by checking the SDK version.


• Prefer `AnalyzeDocumentOptions` for simpler, error-free integration by using built-In classes.


• Ensure your content is wrapped in `BinaryData` or use a direct URL for correct document input:

 

Conclusion

In this article, we have seen how you can use AnalyzeDocumentOptions to significantly improves how you integrate query fields with Azure AI Document Intelligence in C#. It ensures your solution is up-to-date, readable, and more reliable. Staying aware of SDK updates and evolving best practices will help you unlock deeper insights from your documents effortlessly.

 

Reference

Official AnalyzeDocumentAsync Documentation.

Official Azure SDK documentation.

Azure Document Intelligence C# SDK support add-on query field.