Modern applications increasingly rely on artificial intelligence to provide smart, human-like capabilities. Azure Cognitive Services offer a range of APIs, from text analysis and speech recognition to computer vision and language understanding. Integrating these services with ASP.NET Core APIs allows developers to build intelligent applications without managing complex AI infrastructure.
This article explains how to:
Choose the right Cognitive Service
Authenticate and call APIs securely
Integrate Azure Cognitive Services into ASP.NET Core APIs
Handle errors, retries, and best practices
Design production-ready solutions
1. Understanding Azure Cognitive Services
Azure Cognitive Services are a collection of AI APIs that allow you to:
Analyze images, video, and text
Recognize speech and convert text to speech
Understand natural language
Detect anomalies and provide recommendations
Common categories include
| Category | Services |
|---|
| Vision | Computer Vision, Custom Vision, Face API |
| Language | Text Analytics, Language Understanding (LUIS), Translator |
| Speech | Speech-to-Text, Text-to-Speech, Speech Translation |
| Decision | Personalizer, Anomaly Detector |
You can choose the service that suits your business scenario. For example:
Automating content moderation → Content Moderator API
Extracting sentiment from reviews → Text Analytics API
Transcribing audio meetings → Speech-to-Text API
2. Setting Up Azure Cognitive Services
2.1. Create a resource in Azure
Go to the Azure Portal.
Click Create a Resource → AI + Machine Learning → Cognitive Services.
Fill in:
Subscription: Choose your subscription
Resource group: Create or reuse
Region: Choose closest to your users
Name: Unique name for the resource
Pricing tier: Usually S0 for standard usage
Click Review + Create → Create
After deployment, note Endpoint URL and API key, which you will use in your ASP.NET Core API.
3. Adding Cognitive Services to ASP.NET Core
3.1. Create a new ASP.NET Core API project
dotnet new webapi -n CognitiveApiDemo
cd CognitiveApiDemo
3.2. Install required NuGet packages
For Text Analytics API:
dotnet add package Azure.AI.TextAnalytics
For Computer Vision API:
dotnet add package Microsoft.Azure.CognitiveServices.Vision.ComputerVision
Note: Microsoft provides Azure SDKs for most services. Choose the latest stable version.
4. Configuring API Keys and Endpoints
Use appsettings.json to store secrets in development. Do not hardcode keys in production.
{"AzureCognitiveServices": {
"TextAnalyticsKey": "YOUR_TEXT_ANALYTICS_KEY",
"TextAnalyticsEndpoint": "https://YOUR_RESOURCE_NAME.cognitiveservices.azure.com/",
"ComputerVisionKey": "YOUR_COMPUTER_VISION_KEY",
"ComputerVisionEndpoint": "https://YOUR_RESOURCE_NAME.cognitiveservices.azure.com/"}}
In Startup.cs or Program.cs (for .NET 6+), register configuration:
builder.Services.Configure<AzureCognitiveOptions>(
builder.Configuration.GetSection("AzureCognitiveServices"));
Create a strongly typed class:
public class AzureCognitiveOptions
{
public string TextAnalyticsKey { get; set; }
public string TextAnalyticsEndpoint { get; set; }
public string ComputerVisionKey { get; set; }
public string ComputerVisionEndpoint { get; set; }
}
5. Implementing Text Analytics API in ASP.NET Core
Text Analytics API can analyze sentiment, detect key phrases, and recognize language.
5.1. Create a service
using Azure;
using Azure.AI.TextAnalytics;
using Microsoft.Extensions.Options;
public class TextAnalyticsService
{
private readonly TextAnalyticsClient _client;
public TextAnalyticsService(IOptions<AzureCognitiveOptions> options)
{
var endpoint = new Uri(options.Value.TextAnalyticsEndpoint);
var credential = new AzureKeyCredential(options.Value.TextAnalyticsKey);
_client = new TextAnalyticsClient(endpoint, credential);
}
public string AnalyzeSentiment(string text)
{
var response = _client.AnalyzeSentiment(text);
return response.Value.Sentiment.ToString();
}
public IEnumerable<string> ExtractKeyPhrases(string text)
{
var response = _client.ExtractKeyPhrases(text);
return response.Value;
}
}
5.2. Register the service
builder.Services.AddSingleton<TextAnalyticsService>();
5.3. Create an API controller
[ApiController]
[Route("api/[controller]")]
public class TextAnalysisController : ControllerBase
{
private readonly TextAnalyticsService _textAnalyticsService;
public TextAnalysisController(TextAnalyticsService textAnalyticsService)
{
_textAnalyticsService = textAnalyticsService;
}
[HttpPost("sentiment")]
public IActionResult Sentiment([FromBody] string text)
{
var result = _textAnalyticsService.AnalyzeSentiment(text);
return Ok(new { Sentiment = result });
}
[HttpPost("keyphrases")]
public IActionResult KeyPhrases([FromBody] string text)
{
var result = _textAnalyticsService.ExtractKeyPhrases(text);
return Ok(result);
}
}
6. Implementing Computer Vision API
Computer Vision allows you to analyze images and extract features.
6.1. Create a service
using Microsoft.Azure.CognitiveServices.Vision.ComputerVision;
using Microsoft.Azure.CognitiveServices.Vision.ComputerVision.Models;
using Microsoft.Extensions.Options;
public class ComputerVisionService
{
private readonly ComputerVisionClient _client;
public ComputerVisionService(IOptions<AzureCognitiveOptions> options)
{
_client = new ComputerVisionClient(
new ApiKeyServiceClientCredentials(options.Value.ComputerVisionKey))
{
Endpoint = options.Value.ComputerVisionEndpoint
};
}
public async Task<ImageAnalysis> AnalyzeImageAsync(string imageUrl)
{
var features = new List<VisualFeatureTypes?> { VisualFeatureTypes.Description, VisualFeatureTypes.Tags };
return await _client.AnalyzeImageAsync(imageUrl, features);
}
}
6.2. Register the service
builder.Services.AddSingleton<ComputerVisionService>();
6.3. API Controller
[ApiController]
[Route("api/[controller]")]
public class VisionController : ControllerBase
{
private readonly ComputerVisionService _visionService;
public VisionController(ComputerVisionService visionService)
{
_visionService = visionService;
}
[HttpPost("analyze")]
public async Task<IActionResult> Analyze([FromBody] string imageUrl)
{
var result = await _visionService.AnalyzeImageAsync(imageUrl);
return Ok(new
{
Description = result.Description.Captions.FirstOrDefault()?.Text,
Tags = result.Tags.Select(t => t.Name)
});
}
}
7. Handling Authentication and Security
7.1. Never hardcode API keys
7.2. Using Key Vault in ASP.NET Core
builder.Configuration.AddAzureKeyVault(
new Uri("https://YOUR-VAULT-NAME.vault.azure.net/"),
new DefaultAzureCredential());
This allows secure key retrieval without storing secrets in code.
8. Error Handling and Retry Patterns
Azure Cognitive Services may return transient errors. Use retry logic for production-grade APIs.
using Polly;
public async Task<string> AnalyzeWithRetryAsync(string text)
{
var policy = Policy
.Handle<RequestFailedException>()
.WaitAndRetryAsync(3, attempt => TimeSpan.FromSeconds(2 * attempt));
return await policy.ExecuteAsync(() =>
{
var response = _client.AnalyzeSentiment(text);
return Task.FromResult(response.Value.Sentiment.ToString());
});
}
Using Polly helps improve resiliency in distributed systems.
9. Logging and Monitoring
Log every API call to Cognitive Services for observability.
Use Application Insights to track response times and failures.
Track usage quotas to avoid exceeding service limits.
_logger.LogInformation("Analyzing sentiment for {Text}", text);
10. Performance and Scaling Considerations
Avoid calling Cognitive Services synchronously for bulk operations.
Batch text documents where supported (AnalyzeSentimentBatch).
Use async/await to avoid blocking threads in ASP.NET Core.
Cache frequently analyzed results to reduce costs.
11. Versioning and SDK Updates
Example
var client = new TextAnalyticsClient(endpoint, credential, new TextAnalyticsClientOptions()
{
Version = TextAnalyticsClientOptions.ServiceVersion.V3_2
});
12. Real-World Best Practices
Use dependency injection for services
Handle transient failures with retries
Secure keys with Key Vault or Managed Identity
Return minimal responses to clients for performance
Centralize Cognitive Service calls to make future updates easier
Monitor service quotas to avoid throttling
Design APIs async for high throughput
13. Example Use Cases
| Use Case | Cognitive Service |
|---|
| Sentiment analysis of customer feedback | Text Analytics API |
| Tagging and describing product images | Computer Vision API |
| Translating website content | Translator API |
| Transcribing meeting recordings | Speech-to-Text API |
| Detecting anomalies in financial transactions | Anomaly Detector |
14. Testing Strategies
Unit tests: Mock TextAnalyticsClient or ComputerVisionClient
Integration tests: Use a test subscription or sandbox keys
Load tests: Ensure API scales with multiple concurrent Cognitive Service calls
15. Deployment Considerations
ASP.NET Core APIs can be deployed to Azure App Service, Kubernetes, or on-premises
Use Managed Identity when running on Azure for secure service access
Enable HTTPS for all API traffic
Apply circuit breaker patterns for dependent Cognitive Service calls
Conclusion
Integrating Azure Cognitive Services with ASP.NET Core APIs enables developers to add intelligent features without building AI models from scratch. By following production best practices:
You can build scalable, maintainable, and intelligent APIs ready for enterprise-grade scenarios.