Azure Document Intelligence SDK Acceptance Criteria (.NET)

SDK: Azure.AI.DocumentIntelligenceRepository: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/documentintelligence/Azure.AI.DocumentIntelligenceNuGet Package: https://www.nuget.org/packages/Azure.AI.DocumentIntelligencePurpose: Skill testing acceptance criteria for validating generated code correctness

---

1. Imports

1.1 ✅ CORRECT: Client Imports

using Azure.AI.DocumentIntelligence;
using Azure.Identity;
using Azure;

1.2 ✅ CORRECT: Model Imports (all in main namespace)

using Azure.AI.DocumentIntelligence;
// AnalyzeResult, DocumentPage, DocumentField, etc. are in main namespace

1.3 ❌ INCORRECT: Wrong import paths

// WRONG - using old Form Recognizer namespace
using Azure.AI.FormRecognizer;
using Azure.AI.FormRecognizer.DocumentAnalysis;

// WRONG - DocumentIntelligenceClient doesn't have sub-namespaces for models
using Azure.AI.DocumentIntelligence.Models;

---

2. Authentication

2.1 ✅ CORRECT: DefaultAzureCredential (Recommended)

string endpoint = Environment.GetEnvironmentVariable("DOCUMENT_INTELLIGENCE_ENDPOINT")
    ?? throw new InvalidOperationException("DOCUMENT_INTELLIGENCE_ENDPOINT not set");

var client = new DocumentIntelligenceClient(new Uri(endpoint), new DefaultAzureCredential());

2.2 ✅ CORRECT: API Key Credential

string endpoint = Environment.GetEnvironmentVariable("DOCUMENT_INTELLIGENCE_ENDPOINT")
    ?? throw new InvalidOperationException("DOCUMENT_INTELLIGENCE_ENDPOINT not set");
string apiKey = Environment.GetEnvironmentVariable("DOCUMENT_INTELLIGENCE_API_KEY")
    ?? throw new InvalidOperationException("DOCUMENT_INTELLIGENCE_API_KEY not set");

var client = new DocumentIntelligenceClient(new Uri(endpoint), new AzureKeyCredential(apiKey));

2.3 ❌ INCORRECT: Hardcoded credentials

// WRONG - hardcoded endpoint and key
var client = new DocumentIntelligenceClient(
    new Uri("https://my-resource.cognitiveservices.azure.com"),
    new AzureKeyCredential("my-api-key"));

---

3. Document Analysis with Prebuilt Models

3.1 ✅ CORRECT: Analyze Layout from URI

Uri documentUri = new Uri("https://example.com/document.pdf");

Operation<AnalyzeResult> operation = await client.AnalyzeDocumentAsync(
    WaitUntil.Completed,
    "prebuilt-layout",
    documentUri);

AnalyzeResult result = operation.Value;

foreach (DocumentPage page in result.Pages)
{
    Console.WriteLine($"Page {page.PageNumber} has {page.Lines.Count} lines and {page.Words.Count} words");
}

3.2 ✅ CORRECT: Analyze Invoice from URI

Uri invoiceUri = new Uri("https://example.com/invoice.pdf");

Operation<AnalyzeResult> operation = await client.AnalyzeDocumentAsync(
    WaitUntil.Completed,
    "prebuilt-invoice",
    invoiceUri);

AnalyzeResult result = operation.Value;

for (int i = 0; i < result.Documents.Count; i++)
{
    AnalyzedDocument document = result.Documents[i];
    
    if (document.Fields.TryGetValue("VendorName", out DocumentField vendorField)
        && vendorField.FieldType == DocumentFieldType.String)
    {
        Console.WriteLine($"Vendor: {vendorField.ValueString}");
    }
    
    if (document.Fields.TryGetValue("InvoiceTotal", out DocumentField totalField)
        && totalField.FieldType == DocumentFieldType.Currency)
    {
        CurrencyValue total = totalField.ValueCurrency;
        Console.WriteLine($"Total: {total.CurrencySymbol}{total.Amount}");
    }
}

3.3 ✅ CORRECT: Analyze from Binary Data (File)

string filePath = "path/to/document.pdf";
byte[] fileBytes = await File.ReadAllBytesAsync(filePath);

Operation<AnalyzeResult> operation = await client.AnalyzeDocumentAsync(
    WaitUntil.Completed,
    "prebuilt-layout",
    BinaryData.FromBytes(fileBytes));

AnalyzeResult result = operation.Value;

3.4 ❌ INCORRECT: Using old API patterns

// WRONG - using old Form Recognizer method names
var operation = await client.StartAnalyzeDocumentFromUriAsync("prebuilt-invoice", uri);

// WRONG - using deprecated model IDs
var operation = await client.AnalyzeDocumentAsync(WaitUntil.Completed, "prebuilt-invoices", uri);

---

4. Prebuilt Model IDs

4.1 ✅ CORRECT: Prebuilt Model IDs

// Layout - extract text, tables, selection marks
"prebuilt-layout"

// Read - extract text and language
"prebuilt-read"

// Invoice
"prebuilt-invoice"

// Receipt
"prebuilt-receipt"

// ID Document
"prebuilt-idDocument"

// Business Card
"prebuilt-businessCard"

// W2 Tax Form
"prebuilt-tax.us.w2"

// Health Insurance Card
"prebuilt-healthInsuranceCard.us"

4.2 ❌ INCORRECT: Wrong model IDs

// WRONG - plural form
"prebuilt-invoices"
"prebuilt-receipts"

// WRONG - old naming convention
"prebuilt-document"

---

5. Extracting Document Content

5.1 ✅ CORRECT: Extract Lines and Words

foreach (DocumentPage page in result.Pages)
{
    Console.WriteLine($"Page {page.PageNumber}:");
    
    for (int i = 0; i < page.Lines.Count; i++)
    {
        DocumentLine line = page.Lines[i];
        Console.WriteLine($"  Line {i}: '{line.Content}'");
        
        // Get bounding polygon
        Console.Write("    Bounding polygon:");
        for (int j = 0; j < line.Polygon.Count; j += 2)
        {
            Console.Write($" ({line.Polygon[j]}, {line.Polygon[j + 1]})");
        }
        Console.WriteLine();
    }
    
    foreach (DocumentWord word in page.Words)
    {
        Console.WriteLine($"  Word: '{word.Content}' (confidence: {word.Confidence})");
    }
}

5.2 ✅ CORRECT: Extract Tables

for (int i = 0; i < result.Tables.Count; i++)
{
    DocumentTable table = result.Tables[i];
    Console.WriteLine($"Table {i} has {table.RowCount} rows and {table.ColumnCount} columns");
    
    foreach (DocumentTableCell cell in table.Cells)
    {
        Console.WriteLine($"  Cell ({cell.RowIndex}, {cell.ColumnIndex}): '{cell.Content}'");
        Console.WriteLine($"    Kind: {cell.Kind}");
    }
}

5.3 ✅ CORRECT: Extract Selection Marks

foreach (DocumentPage page in result.Pages)
{
    for (int i = 0; i < page.SelectionMarks.Count; i++)
    {
        DocumentSelectionMark mark = page.SelectionMarks[i];
        Console.WriteLine($"Selection Mark {i}: {mark.State}");
        Console.WriteLine($"  Confidence: {mark.Confidence}");
    }
}

5.4 ✅ CORRECT: Extract Paragraphs

for (int i = 0; i < result.Paragraphs.Count; i++)
{
    DocumentParagraph paragraph = result.Paragraphs[i];
    Console.WriteLine($"Paragraph {i}: {paragraph.Content}");
    
    if (paragraph.Role != null)
    {
        Console.WriteLine($"  Role: {paragraph.Role}");
    }
}

---

6. Field Extraction

6.1 ✅ CORRECT: Extract Typed Fields

AnalyzedDocument document = result.Documents[0];

// String field
if (document.Fields.TryGetValue("CustomerName", out DocumentField nameField)
    && nameField.FieldType == DocumentFieldType.String)
{
    string customerName = nameField.ValueString;
    Console.WriteLine($"Customer: {customerName} (confidence: {nameField.Confidence})");
}

// Date field
if (document.Fields.TryGetValue("InvoiceDate", out DocumentField dateField)
    && dateField.FieldType == DocumentFieldType.Date)
{
    DateTimeOffset invoiceDate = dateField.ValueDate.Value;
    Console.WriteLine($"Date: {invoiceDate:d}");
}

// Currency field
if (document.Fields.TryGetValue("SubTotal", out DocumentField subtotalField)
    && subtotalField.FieldType == DocumentFieldType.Currency)
{
    CurrencyValue subtotal = subtotalField.ValueCurrency;
    Console.WriteLine($"Subtotal: {subtotal.CurrencySymbol}{subtotal.Amount}");
}

6.2 ✅ CORRECT: Extract List Fields (Line Items)

if (document.Fields.TryGetValue("Items", out DocumentField itemsField)
    && itemsField.FieldType == DocumentFieldType.List)
{
    foreach (DocumentField itemField in itemsField.ValueList)
    {
        if (itemField.FieldType == DocumentFieldType.Dictionary)
        {
            IReadOnlyDictionary<string, DocumentField> item = itemField.ValueDictionary;
            
            if (item.TryGetValue("Description", out DocumentField descField))
            {
                Console.WriteLine($"  Description: {descField.ValueString}");
            }
            
            if (item.TryGetValue("Amount", out DocumentField amountField)
                && amountField.FieldType == DocumentFieldType.Currency)
            {
                Console.WriteLine($"  Amount: {amountField.ValueCurrency.Amount}");
            }
        }
    }
}

6.3 ❌ INCORRECT: Not checking field type

// WRONG - accessing value without checking type
string value = document.Fields["CustomerName"].ValueString; // May throw if not string type

---

7. Custom Models

7.1 ✅ CORRECT: Build Custom Model

var adminClient = new DocumentIntelligenceAdministrationClient(
    new Uri(endpoint), new DefaultAzureCredential());

var buildOptions = new BuildDocumentModelContent("custom-model-id", DocumentBuildMode.Template)
{
    AzureBlobSource = new AzureBlobContentSource(
        new Uri("https://storageaccount.blob.core.windows.net/training-data?sasToken"))
};

Operation<DocumentModelDetails> operation = await adminClient.BuildDocumentModelAsync(
    WaitUntil.Completed,
    buildOptions);

DocumentModelDetails model = operation.Value;
Console.WriteLine($"Model ID: {model.ModelId}");
Console.WriteLine($"Created: {model.CreatedOn}");

7.2 ✅ CORRECT: Analyze with Custom Model

Operation<AnalyzeResult> operation = await client.AnalyzeDocumentAsync(
    WaitUntil.Completed,
    "custom-model-id",
    documentUri);

AnalyzeResult result = operation.Value;

foreach (AnalyzedDocument document in result.Documents)
{
    Console.WriteLine($"Document type: {document.DocumentType}");
    
    foreach (var field in document.Fields)
    {
        Console.WriteLine($"Field '{field.Key}': {field.Value.Content}");
    }
}

7.3 ✅ CORRECT: List Models

var adminClient = new DocumentIntelligenceAdministrationClient(
    new Uri(endpoint), new DefaultAzureCredential());

AsyncPageable<DocumentModelDetails> models = adminClient.GetModelsAsync();

await foreach (DocumentModelDetails model in models)
{
    Console.WriteLine($"Model: {model.ModelId}, Created: {model.CreatedOn}");
}

7.4 ✅ CORRECT: Delete Model

await adminClient.DeleteModelAsync("custom-model-id");

---

8. Document Classification

8.1 ✅ CORRECT: Build Classifier

var buildOptions = new BuildDocumentClassifierContent("my-classifier")
{
    DocumentTypes =
    {
        ["invoice"] = new ClassifierDocumentTypeDetails()
        {
            AzureBlobSource = new AzureBlobContentSource(new Uri("https://storage.blob.core.windows.net/invoices?sas"))
        },
        ["receipt"] = new ClassifierDocumentTypeDetails()
        {
            AzureBlobSource = new AzureBlobContentSource(new Uri("https://storage.blob.core.windows.net/receipts?sas"))
        }
    }
};

Operation<DocumentClassifierDetails> operation = await adminClient.BuildClassifierAsync(
    WaitUntil.Completed,
    buildOptions);

DocumentClassifierDetails classifier = operation.Value;
Console.WriteLine($"Classifier ID: {classifier.ClassifierId}");

8.2 ✅ CORRECT: Classify Document

Operation<AnalyzeResult> operation = await client.ClassifyDocumentAsync(
    WaitUntil.Completed,
    "my-classifier",
    documentUri);

AnalyzeResult result = operation.Value;

foreach (AnalyzedDocument document in result.Documents)
{
    Console.WriteLine($"Document type: {document.DocumentType}");
    Console.WriteLine($"Confidence: {document.Confidence}");
}

---

9. Async Patterns

9.1 ✅ CORRECT: Async Analysis

// Full async with WaitUntil.Completed
Operation<AnalyzeResult> operation = await client.AnalyzeDocumentAsync(
    WaitUntil.Completed,
    "prebuilt-invoice",
    documentUri);

AnalyzeResult result = operation.Value;

9.2 ✅ CORRECT: Polling for Long-Running Operations

// Start operation without waiting
Operation<AnalyzeResult> operation = await client.AnalyzeDocumentAsync(
    WaitUntil.Started,
    "prebuilt-layout",
    documentUri);

Console.WriteLine($"Operation ID: {operation.Id}");

// Poll for completion
await operation.WaitForCompletionAsync();

AnalyzeResult result = operation.Value;

9.3 ❌ INCORRECT: Blocking on async

// WRONG - using .Result instead of await
var result = client.AnalyzeDocumentAsync(WaitUntil.Completed, "prebuilt-layout", uri).Result;

// WRONG - using .Wait()
operation.WaitForCompletionAsync().Wait();

---

10. Error Handling

10.1 ✅ CORRECT: Handle RequestFailedException

try
{
    Operation<AnalyzeResult> operation = await client.AnalyzeDocumentAsync(
        WaitUntil.Completed,
        "prebuilt-invoice",
        documentUri);
}
catch (RequestFailedException ex) when (ex.Status == 400)
{
    Console.WriteLine($"Invalid request: {ex.Message}");
}
catch (RequestFailedException ex) when (ex.Status == 404)
{
    Console.WriteLine($"Model not found: {ex.Message}");
}
catch (RequestFailedException ex)
{
    Console.WriteLine($"Service error ({ex.Status}): {ex.Message}");
}

10.2 ❌ INCORRECT: Swallowing exceptions

// WRONG - empty catch
try
{
    var operation = await client.AnalyzeDocumentAsync(...);
}
catch { }

---

11. Best Practices

11.1 ✅ CORRECT: Reuse Client Instance

public class DocumentAnalysisService
{
    private readonly DocumentIntelligenceClient _client;
    
    public DocumentAnalysisService(string endpoint)
    {
        _client = new DocumentIntelligenceClient(
            new Uri(endpoint),
            new DefaultAzureCredential());
    }
    
    public async Task<AnalyzeResult> AnalyzeInvoiceAsync(Uri documentUri)
    {
        var operation = await _client.AnalyzeDocumentAsync(
            WaitUntil.Completed,
            "prebuilt-invoice",
            documentUri);
        return operation.Value;
    }
}

11.2 ✅ CORRECT: Check Document Confidence

foreach (AnalyzedDocument document in result.Documents)
{
    if (document.Confidence < 0.8)
    {
        Console.WriteLine($"Low confidence ({document.Confidence:P}) - manual review recommended");
    }
}

11.3 ❌ INCORRECT: Creating client per request

// WRONG - wasteful to create client for each analysis
public async Task<AnalyzeResult> AnalyzeDocument(Uri uri)
{
    var client = new DocumentIntelligenceClient(new Uri(endpoint), new DefaultAzureCredential());
    // ...
}