Content Understanding GA SDK

.vscode/cspell.json

@@ -478,6 +478,15 @@
         "wmem"
       ]
     },
+    {
+      "filename": "**/sdk/contentunderstanding/**/*.cs",
+      "words": [
+        "upca",
+        "upce",
+        "UPCA",
+        "UPCE"
+      ]
+    },
     {
       "filename": "**/sdk/consumption/**/*",
       "words": [

sdk/contentunderstanding/Azure.AI.ContentUnderstanding/.gitignore

@@ -0,0 +1,16 @@
+# Local-only files and temporary scripts (not committed to git)
+__local_only/
+
+# User-specific configuration files (never commit appsettings.json - they may contain secrets)
+**/appsettings.json
+!**/appsettings.json.sample
+
+# EditorConfig file (SDK-specific, not committed)
+.editorconfig
+
+# Sample output directories (generated by sample execution)
+**/sample_output/
+
+# Test recordings (SessionRecords) - should not be committed
+**/SessionRecords/
+

sdk/contentunderstanding/Azure.AI.ContentUnderstanding/Azure.AI.ContentUnderstanding.sln

@@ -0,0 +1,30 @@
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio Version 17
+VisualStudioVersion = 17.0.31903.59
+MinimumVisualStudioVersion = 10.0.40219.1
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Azure.AI.ContentUnderstanding", "src\Azure.AI.ContentUnderstanding.csproj", "{28FF4005-4467-4E36-92E7-DEA27DEB1519}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Azure.Core.TestFramework", "..\..\core\Azure.Core.TestFramework\src\Azure.Core.TestFramework.csproj", "{C2E8EBF5-F05A-22ED-9231-040E2E2D8446}"
+EndProject
+Global
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|Any CPU = Debug|Any CPU
+		Release|Any CPU = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{28FF4005-4467-4E36-92E7-DEA27DEB1519}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{28FF4005-4467-4E36-92E7-DEA27DEB1519}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{28FF4005-4467-4E36-92E7-DEA27DEB1519}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{28FF4005-4467-4E36-92E7-DEA27DEB1519}.Release|Any CPU.Build.0 = Release|Any CPU
+		{C2E8EBF5-F05A-22ED-9231-040E2E2D8446}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{C2E8EBF5-F05A-22ED-9231-040E2E2D8446}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{C2E8EBF5-F05A-22ED-9231-040E2E2D8446}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{C2E8EBF5-F05A-22ED-9231-040E2E2D8446}.Release|Any CPU.Build.0 = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(SolutionProperties) = preSolution
+		HideSolutionNode = FALSE
+	EndGlobalSection
+	GlobalSection(ExtensibilityGlobals) = postSolution
+		SolutionGuid = {A97F4B90-2591-4689-B1F8-5F21FE6D6CAE}
+	EndGlobalSection
+EndGlobal

sdk/contentunderstanding/Azure.AI.ContentUnderstanding/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Release History
+
+## 1.0.0-beta.1 (Unreleased)
+
+### Features Added
+- Initial release of Azure AI Content Understanding client library for .NET
+- Added `ContentUnderstandingClient` for analyzing documents, audio, and video content
+- Added `AnalyzeResultOperation` class that extends `Operation<AnalyzeResult>` and provides access to the operation ID via the `Id` property
+
+### Breaking Changes
+
+### Bugs Fixed
+
+### Other Changes

sdk/contentunderstanding/Azure.AI.ContentUnderstanding/Directory.Build.props

@@ -0,0 +1,6 @@
+<Project ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <!--
+    Add any shared properties you want for the projects under this package directory that need to be set before the auto imported Directory.Build.props
+  -->
+  <Import Project="$([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildThisFileDirectory).., Directory.Build.props))\Directory.Build.props" />
+</Project>

sdk/contentunderstanding/Azure.AI.ContentUnderstanding/assets.json

@@ -0,0 +1,7 @@
+{
+  "AssetsRepo": "Azure/azure-sdk-assets",
+  "AssetsRepoPrefixPath": "net",
+  "TagPrefix": "net/contentunderstanding/Azure.AI.ContentUnderstanding",
+  "Tag": "net/contentunderstanding/Azure.AI.ContentUnderstanding_1764097269"
+}
+

sdk/contentunderstanding/Azure.AI.ContentUnderstanding/samples/Sample00_ConfigureDefaults.md

@@ -0,0 +1,111 @@
+# Configure model deployment defaults
+
+This sample demonstrates how to configure and retrieve default model deployment settings for your Microsoft Foundry resource. This is a **required one-time setup** before using prebuilt analyzers.
+
+## About Model Deployment Configuration
+
+Content Understanding prebuilt analyzers require specific GPT model deployments to function:
+
+- **GPT-4.1** - Used by most prebuilt analyzers (e.g., `prebuilt-invoice`, `prebuilt-receipt`, `prebuilt-idDocument`)
+- **GPT-4.1-mini** - Used by RAG analyzers (e.g., `prebuilt-documentSearch`, `prebuilt-audioSearch`, `prebuilt-videoSearch`)
+- **text-embedding-3-large** - Used for semantic search and embeddings
+
+This configuration is **per Microsoft Foundry resource** and persists across sessions. You only need to configure it once per Microsoft Foundry resource (or when you change deployment names).
+
+## Prerequisites
+
+To get started you'll need a **Microsoft Foundry resource**. See [README][README] for prerequisites and instructions.
+
+You also need to have deployed the following models in Microsoft Foundry:
+- GPT-4.1
+- GPT-4.1-mini
+- text-embedding-3-large
+
+## Creating a `ContentUnderstandingClient`
+
+The `ContentUnderstandingClient` is the main interface for interacting with the Content Understanding service. In this sample, you'll use the client to:
+- Retrieve current model deployment defaults (`GetDefaultsAsync`)
+- Update model deployment mappings (`UpdateDefaultsAsync`)
+
+To create a new `ContentUnderstandingClient` you need the endpoint and credentials from your Microsoft Foundry resource. You can authenticate using either `DefaultAzureCredential` (recommended) or an API key.
+
+### Using DefaultAzureCredential (Recommended)
+
+```C# Snippet:CreateContentUnderstandingClient
+string endpoint = "<endpoint>";
+var credential = new DefaultAzureCredential();
+var client = new ContentUnderstandingClient(new Uri(endpoint), credential);
+```
+
+### Using API Key
+
+```C# Snippet:CreateContentUnderstandingClientApiKey
+string endpoint = "<endpoint>";
+string apiKey = "<apiKey>";
+var client = new ContentUnderstandingClient(new Uri(endpoint), new AzureKeyCredential(apiKey));
+```
+
+> **⚠️ Security Warning**: API key authentication is not secure and is only recommended for testing purposes with test resources. For production, use `DefaultAzureCredential` or other secure authentication methods.
+
+## Configure Model Deployments
+
+Before you can use prebuilt analyzers, you need to map your deployed GPT models to the models required by the prebuilt analyzers:
+
+```C# Snippet:ContentUnderstandingUpdateDefaults
+// Map your deployed models to the models required by prebuilt analyzers
+var modelDeployments = new Dictionary<string, string>
+{
+    ["gpt-4.1"] = "<your-gpt-4.1-deployment-name>",
+    ["gpt-4.1-mini"] = "<your-gpt-4.1-mini-deployment-name>",
+    ["text-embedding-3-large"] = "<your-text-embedding-3-large-deployment-name>"
+};
+
+var response = await client.UpdateDefaultsAsync(modelDeployments);
+ContentUnderstandingDefaults updatedDefaults = response.Value;
+
+Console.WriteLine("Model deployments configured successfully!");
+foreach (var kvp in updatedDefaults.ModelDeployments)
+{
+    Console.WriteLine($"  {kvp.Key} → {kvp.Value}");
+}
+```
+
+## Retrieve Current Defaults
+
+You can retrieve the current default model deployment configuration:
+
+```C# Snippet:ContentUnderstandingGetDefaults
+var getResponse = await client.GetDefaultsAsync();
+ContentUnderstandingDefaults defaults = getResponse.Value;
+
+Console.WriteLine("Current model deployment mappings:");
+if (defaults.ModelDeployments != null && defaults.ModelDeployments.Count > 0)
+{
+    foreach (var kvp in defaults.ModelDeployments)
+    {
+        Console.WriteLine($"  {kvp.Key} → {kvp.Value}");
+    }
+}
+else
+{
+    Console.WriteLine("  No model deployments configured yet.");
+}
+```
+
+## Next Steps
+
+After configuring model deployments, you can use prebuilt analyzers. See:
+- [Sample 01: Analyze a document from binary data][sample01] to analyze PDF files
+- [Sample 02: Analyze a document from URL][sample02] to analyze documents from URLs
+
+## Learn More
+
+- [Content Understanding Documentation][cu-docs]
+- [Model Deployment Configuration][model-deployment-docs]
+
+[README]:  https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/contentunderstanding/Azure.AI.ContentUnderstanding/samples/README.md
+[sample01]:  https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/contentunderstanding/Azure.AI.ContentUnderstanding/samples/Sample01_AnalyzeBinary.md
+[sample02]:  https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/contentunderstanding/Azure.AI.ContentUnderstanding/samples/Sample02_AnalyzeUrl.md
+[cu-docs]: https://learn.microsoft.com/azure/ai-services/content-understanding/
+[model-deployment-docs]: https://learn.microsoft.com/azure/ai-services/content-understanding/quickstart/use-rest-api?tabs=portal%2Cdocument
+

sdk/contentunderstanding/Azure.AI.ContentUnderstanding/samples/Sample00_ConfigureDefaults/Program.cs

@@ -0,0 +1,145 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using System;
+using System.Collections.Generic;
+using System.Threading.Tasks;
+using Azure;
+using Azure.AI.ContentUnderstanding;
+using Azure.Core;
+using Azure.Identity;
+using Microsoft.Extensions.Configuration;
+
+/// <summary>
+/// This sample demonstrates how to configure and retrieve default model deployment settings for your Microsoft Foundry resource.
+///
+/// Prerequisites:
+///     - Azure subscription
+///     - Microsoft Foundry resource
+///     - .NET 8.0 SDK or later
+///     - Deployed GPT-4.1, GPT-4.1-mini, and text-embedding-3-large models in Microsoft Foundry
+///
+/// Setup:
+///     Set the following environment variables or add them to appsettings.json:
+///     - AZURE_CONTENT_UNDERSTANDING_ENDPOINT (required)
+///     - AZURE_CONTENT_UNDERSTANDING_KEY (optional - DefaultAzureCredential will be used if not set)
+///     - GPT_4_1_DEPLOYMENT (optional - required only for UpdateDefaults)
+///     - GPT_4_1_MINI_DEPLOYMENT (optional - required only for UpdateDefaults)
+///     - TEXT_EMBEDDING_3_LARGE_DEPLOYMENT (optional - required only for UpdateDefaults)
+///
+/// To run:
+///     dotnet run
+/// </summary>
+class Program
+{
+    static async Task Main(string[] args)
+    {
+        // Load configuration
+        var configuration = new ConfigurationBuilder()
+            .SetBasePath(AppContext.BaseDirectory)
+            .AddJsonFile("appsettings.json", optional: true)
+            .AddEnvironmentVariables()
+            .Build();
+
+        var endpoint = configuration["AZURE_CONTENT_UNDERSTANDING_ENDPOINT"];
+        if (string.IsNullOrEmpty(endpoint))
+        {
+            Console.Error.WriteLine("Error: AZURE_CONTENT_UNDERSTANDING_ENDPOINT is required.");
+            Console.Error.WriteLine("Please set it in environment variables or appsettings.json");
+            Environment.Exit(1);
+        }
+
+        // Trim and validate endpoint
+        endpoint = endpoint.Trim();
+        if (!Uri.TryCreate(endpoint, UriKind.Absolute, out var endpointUri))
+        {
+            Console.Error.WriteLine($"Error: Invalid endpoint URL: {endpoint}");
+            Console.Error.WriteLine("Endpoint must be a valid absolute URI (e.g., https://your-resource.services.ai.azure.com/)");
+            Environment.Exit(1);
+        }
+
+        // Create client with appropriate authentication
+        var apiKey = configuration["AZURE_CONTENT_UNDERSTANDING_KEY"];
+        ContentUnderstandingClient client;
+        if (!string.IsNullOrEmpty(apiKey))
+        {
+            client = new ContentUnderstandingClient(endpointUri, new AzureKeyCredential(apiKey));
+        }
+        else
+        {
+            var credential = new DefaultAzureCredential();
+            client = new ContentUnderstandingClient(endpointUri, credential);
+        }
+
+        try
+        {
+            // First, update defaults if deployment names are provided
+            var gpt41Deployment = configuration["GPT_4_1_DEPLOYMENT"];
+            var gpt41MiniDeployment = configuration["GPT_4_1_MINI_DEPLOYMENT"];
+            var textEmbeddingDeployment = configuration["TEXT_EMBEDDING_3_LARGE_DEPLOYMENT"];
+
+            if (!string.IsNullOrEmpty(gpt41Deployment) && !string.IsNullOrEmpty(gpt41MiniDeployment) && !string.IsNullOrEmpty(textEmbeddingDeployment))
+            {
+                Console.WriteLine("=== Updating Defaults ===");
+                // Map your deployed models to the models required by prebuilt analyzers
+                var modelDeployments = new Dictionary<string, string>
+                {
+                    ["gpt-4.1"] = gpt41Deployment,
+                    ["gpt-4.1-mini"] = gpt41MiniDeployment,
+                    ["text-embedding-3-large"] = textEmbeddingDeployment
+                };
+
+                var updateResponse = await client.UpdateDefaultsAsync(modelDeployments);
+                ContentUnderstandingDefaults updatedDefaults = updateResponse.Value;
+
+                Console.WriteLine("Model deployments configured successfully!");
+                foreach (var kvp in updatedDefaults.ModelDeployments)
+                {
+                    Console.WriteLine($"  {kvp.Key} → {kvp.Value}");
+                }
+
+                Console.WriteLine();
+            }
+            else
+            {
+                Console.WriteLine("=== Skipping UpdateDefaults ===");
+                Console.WriteLine("To update defaults, set the following in appsettings.json or environment variables:");
+                Console.WriteLine("  - GPT_4_1_DEPLOYMENT");
+                Console.WriteLine("  - GPT_4_1_MINI_DEPLOYMENT");
+                Console.WriteLine("  - TEXT_EMBEDDING_3_LARGE_DEPLOYMENT");
+                Console.WriteLine();
+            }
+
+            // Then, retrieve current defaults to verify
+            Console.WriteLine("=== Retrieving Current Defaults ===");
+            var getResponse = await client.GetDefaultsAsync();
+            ContentUnderstandingDefaults currentDefaults = getResponse.Value;
+
+            Console.WriteLine("Current model deployment mappings:");
+            if (currentDefaults.ModelDeployments != null && currentDefaults.ModelDeployments.Count > 0)
+            {
+                foreach (var kvp in currentDefaults.ModelDeployments)
+                {
+                    Console.WriteLine($"  {kvp.Key} → {kvp.Value}");
+                }
+            }
+            else
+            {
+                Console.WriteLine("  No model deployments configured yet.");
+                Console.WriteLine("  Run UpdateDefaults to configure model deployments.");
+            }
+        }
+        catch (RequestFailedException ex)
+        {
+            Console.Error.WriteLine($"Error: {ex.Message}");
+            Console.Error.WriteLine($"Status: {ex.Status}");
+            Console.Error.WriteLine($"Error Code: {ex.ErrorCode}");
+            Environment.Exit(1);
+        }
+        catch (Exception ex)
+        {
+            Console.Error.WriteLine($"Error: {ex.Message}");
+            Environment.Exit(1);
+        }
+    }
+}

sdk/contentunderstanding/Azure.AI.ContentUnderstanding/samples/Sample00_ConfigureDefaults/README.md

@@ -0,0 +1,36 @@
+# Sample00_ConfigureDefaults
+
+This sample demonstrates how to configure and retrieve default model deployment settings for your Microsoft Foundry resource.
+For detailed documentation, see [Sample00_ConfigureDefaults.md](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/contentunderstanding/Azure.AI.ContentUnderstanding/samples/Sample00_ConfigureDefaults.md).
+
+## Prerequisites
+
+- Azure subscription
+- Microsoft Foundry resource
+- .NET 8.0 SDK or later
+
+## Setup
+
+### Option 1: Use appsettings.json.sample
+
+1. Copy `appsettings.json.sample` from the parent `samples` directory:
+   ```bash
+   cp ../appsettings.json.sample appsettings.json
+   ```
+
+2. Edit `appsettings.json` and fill in your values:
+   - `AZURE_CONTENT_UNDERSTANDING_ENDPOINT` (required) - Your Microsoft Foundry resource endpoint
+   - `AZURE_CONTENT_UNDERSTANDING_KEY` (optional) - Your API key, or leave empty to use DefaultAzureCredential
+
+### Option 2: Use Environment Variables
+
+Set the following environment variables:
+
+- `AZURE_CONTENT_UNDERSTANDING_ENDPOINT` (required)
+- `AZURE_CONTENT_UNDERSTANDING_KEY` (optional - DefaultAzureCredential will be used if not set)
+
+## Run
+
+```bash
+dotnet run
+```