Skip to content

Azure Development

Jump to bottom
Holger Imbery edited this page Sep 19, 2025 · 1 revision

Azure Development

Complete developer guide for building, deploying, and maintaining ACSforMCS on Azure. This guide covers the full development lifecycle from initial setup through production deployment with monitoring and environment management.

Overview

ACSforMCS is designed for Azure-first development where you develop directly on Azure Web Apps rather than locally. This approach provides:

  • Production Parity: Same environment as production
  • Real Azure Integration: Managed Identity, Key Vault, Application Insights
  • WebSocket Support: Required for real-time audio streaming
  • Environment Switching: Development ↔ Production modes
  • Built-in Monitoring: Health endpoints and comprehensive logging

Prerequisites

Required Tools

Azure Requirements

  • Azure Subscription with appropriate permissions
  • Contributor role on target Resource Group
  • Key Vault Administrator or Key Vault Secrets Officer role
  • Website Contributor role on Web App

Verification

# Verify tools
dotnet --version          # Should show 9.x.x
az --version             # Azure CLI version
pwsh --version           # PowerShell 7.x

# Verify Azure access
az login
az account show

Development Environment Setup

Option 1: New Project Setup

For projects starting from scratch:

# 1. Clone the repository
git clone https://github.com/holgerimbery/ACSforMCS.git
cd ACSforMCS

# 2. Create all Azure resources
.\scripts\create-azure-resources.ps1 -ApplicationName "myproject" -Environment "dev"

# 3. Initialize configuration
.\scripts\setup-configuration.ps1

# 4. Switch to development mode
.\scripts\switch-to-development.ps1

# 5. Deploy application
.\scripts\deploy-application.ps1

Option 2: Existing Azure Resources

If you already have Azure resources:

# 1. Clone repository
git clone https://github.com/holgerimbery/ACSforMCS.git
cd ACSforMCS

# 2. Configure with existing Key Vault
.\scripts\setup-configuration.ps1 -KeyVaultName "your-keyvault-name"

# 3. Switch to development mode
.\scripts\switch-to-development.ps1

# 4. Deploy application
.\scripts\deploy-application.ps1

Environment Management

ACSforMCS supports two distinct runtime modes optimized for different purposes:

Development Mode

Enables comprehensive debugging and monitoring capabilities:

# Switch to development mode
.\scripts\switch-to-development.ps1
.\scripts\deploy-application.ps1

Development Mode Features:

  • Swagger Documentation: Available at /swagger with API key protection
  • Health Monitoring: Multiple endpoints for system monitoring
  • Detailed Logging: Comprehensive logging for debugging
  • Real-time Metrics: Active call monitoring and system statistics
  • Configuration Validation: Endpoint to verify all settings

Monitoring Endpoints (API key required):

  • /health - Basic health status
  • /health/calls - Active call monitoring
  • /health/config - Configuration validation
  • /health/metrics - System performance metrics
  • /swagger - Interactive API documentation

Production Mode

Optimizes for performance and security:

# Switch to production mode
.\scripts\switch-to-production.ps1
.\scripts\deploy-application.ps1

Production Mode Features:

  • No Swagger: Documentation disabled for security
  • No Health Endpoints: Monitoring disabled to reduce attack surface
  • Optimized Logging: Minimal logging for maximum performance
  • Performance Tuning: Connection pooling and timeout optimizations
  • Security Hardening: Reduced endpoint exposure

Development Workflow

1. Initial Development Setup

# Verify environment status
.\scripts\show-environment.ps1

# Ensure development mode
.\scripts\switch-to-development.ps1

# Deploy latest changes
.\scripts\deploy-application.ps1

2. Code Development Cycle

Local Code Changes:

  1. Make changes to the codebase
  2. Test locally with dotnet build and dotnet test
  3. Commit changes to version control

Azure Deployment:

# Quick deployment after code changes
.\scripts\deploy-application.ps1

# Verify deployment
.\scripts\show-environment.ps1

Testing and Validation:

# Check application status
curl https://your-app.azurewebsites.net

# Access Swagger documentation (get API key first)
$apiKey = az keyvault secret show --vault-name "your-kv" --name "HealthCheckApiKey" --query value -o tsv
curl -H "X-API-Key: $apiKey" https://your-app.azurewebsites.net/swagger

# Monitor active calls
curl -H "X-API-Key: $apiKey" https://your-app.azurewebsites.net/health/calls

3. Environment Switching

Development to Production:

# Switch mode and deploy
.\scripts\switch-to-production.ps1
.\scripts\deploy-application.ps1

# Verify production configuration
.\scripts\show-environment.ps1

Production to Development:

# Switch back for debugging
.\scripts\switch-to-development.ps1
.\scripts\deploy-application.ps1

Monitoring and Debugging

Swagger API Documentation

In Development mode, access comprehensive API documentation:

  1. Get API Key:

    az keyvault secret show --vault-name "your-kv" --name "HealthCheckApiKey" --query value -o tsv

  2. Access Swagger:

    • URL: https://your-app.azurewebsites.net/swagger
    • Add header: X-API-Key: your-api-key

  3. Features:

    • Interactive API testing
    • Complete endpoint documentation
    • Security scheme testing
    • Real-time API exploration

Health Monitoring Endpoints

Monitor system health and performance in Development mode:

Active Call Monitoring:

curl -H "X-API-Key: your-api-key" https://your-app.azurewebsites.net/health/calls

System Metrics:

curl -H "X-API-Key: your-api-key" https://your-app.azurewebsites.net/health/metrics

Configuration Status:

curl -H "X-API-Key: your-api-key" https://your-app.azurewebsites.net/health/config

Application Insights Integration

Monitor production applications with Azure Application Insights:

  1. Enable during deployment (ARM template includes this)

  2. Access insights:

    • Azure Portal → Application Insights → Your instance
    • Monitor requests, dependencies, and custom events
    • Set up alerts for failures or performance degradation

  3. Custom telemetry:

    • Call duration tracking
    • DirectLine API response times
    • Speech recognition accuracy metrics

Log Analysis

Azure Web App Logs:

# Stream live logs
az webapp log tail --name your-app-name --resource-group your-rg

# Download log files
az webapp log download --name your-app-name --resource-group your-rg

Key Log Categories:

  • CallAutomationService: Call processing and bot communication
  • DirectLine: Bot Framework API communication
  • WebSocketMiddleware: Real-time audio streaming
  • HealthChecks: System monitoring and validation

Deployment Scripts Reference

Core Scripts

create-azure-resources.ps1 Creates all required Azure resources with validation:

# Basic usage
.\scripts\create-azure-resources.ps1 -ApplicationName "myapp"

# With custom location and environment
.\scripts\create-azure-resources.ps1 -ApplicationName "myapp" -Location "East US" -Environment "dev"

# Validate names without creating resources
.\scripts\create-azure-resources.ps1 -ApplicationName "test" -ValidateOnly

setup-configuration.ps1 Initializes application configuration:

# Auto-detect configuration
.\scripts\setup-configuration.ps1

# Specify Key Vault
.\scripts\setup-configuration.ps1 -KeyVaultName "your-kv"

# Validate existing configuration
.\scripts\setup-configuration.ps1 -ValidateOnly

# Force reconfiguration
.\scripts\setup-configuration.ps1 -Force

deploy-application.ps1 Builds and deploys the application:

# Standard deployment
.\scripts\deploy-application.ps1

# The script automatically:
# - Retrieves configuration from Key Vault
# - Builds in Release mode
# - Creates deployment package
# - Deploys to Azure Web App
# - Verifies deployment success

Environment Management Scripts

switch-to-development.ps1 Enables development features:

.\scripts\switch-to-development.ps1

# Enables:
# - Swagger documentation
# - Health monitoring endpoints
# - Detailed logging
# - API key protection for all endpoints

switch-to-production.ps1 Optimizes for production:

.\scripts\switch-to-production.ps1

# Optimizes:
# - Disables Swagger
# - Disables monitoring endpoints
# - Minimal logging
# - Performance optimizations

show-environment.ps1 Displays current environment status:

.\scripts\show-environment.ps1

# Shows:
# - Current environment mode
# - Key configuration values
# - Endpoint accessibility
# - Health status summary

Configuration Management

Azure Key Vault Integration

All sensitive configuration is stored in Azure Key Vault:

Required Secrets:

  • AcsConnectionString - Azure Communication Services
  • DirectLineSecret - Copilot Studio Web Channel Security secret
  • BaseUri-Development - Development environment URL
  • BaseUri-Production - Production environment URL
  • AgentPhoneNumber - Transfer target phone number
  • CognitiveServiceEndpoint - Speech services endpoint
  • HealthCheckApiKey - API key for monitoring endpoints

Manage Secrets:

# Set secret
az keyvault secret set --vault-name "your-kv" --name "SecretName" --value "SecretValue"

# Get secret (for debugging)
az keyvault secret show --vault-name "your-kv" --name "SecretName" --query value -o tsv

# List all secrets
az keyvault secret list --vault-name "your-kv" --query "[].name" -o table

Local Development Configuration

Uses .NET User Secrets for local development:

# View current user secrets
dotnet user-secrets list --project ACSforMCS.csproj

# Set a user secret
dotnet user-secrets set "KeyVaultName" "your-keyvault-name" --project ACSforMCS.csproj

# Clear all user secrets
dotnet user-secrets clear --project ACSforMCS.csproj

Performance Optimization

Azure App Service Configuration

Recommended SKUs:

  • Development: Basic B1 minimum for testing
  • Production: Standard S1 or higher for real workloads
  • High-Volume: Premium P1v3 or higher with auto-scaling

Optimization Settings:

# Enable Always On (Standard+ SKUs)
az webapp config set --name your-app --resource-group your-rg --always-on true

# Configure auto-scaling
az monitor autoscale create --resource-group your-rg --resource your-app --resource-type Microsoft.Web/serverfarms --name your-app-autoscale --min-count 1 --max-count 3 --count 1

# Enable Application Insights (modern approach)
az webapp config appsettings set --name your-app --resource-group your-rg --settings "APPLICATIONINSIGHTS_CONNECTION_STRING=your-connection-string"

Connection Optimization

HTTP Client Configuration:

  • Connection pooling enabled for DirectLine API
  • Optimized timeouts for real-time requirements
  • Retry policies with exponential backoff
  • Jitter to prevent thundering herd

WebSocket Optimization:

  • Persistent connections for audio streaming
  • Efficient buffer management
  • Automatic reconnection handling

Call Capacity Planning

Concurrent Call Limits:

  • Basic B1: 5-10 concurrent calls
  • Standard S1: 15-25 concurrent calls
  • Premium P1v3: 50+ concurrent calls

Monitoring Thresholds:

# Check current call load
curl -H "X-API-Key: $apiKey" https://your-app.azurewebsites.net/health/calls

# Response includes:
# - activeCalls: Current concurrent calls
# - maxRecommendedCalls: Suggested limit for current SKU
# - callCapacityUsed: Percentage of capacity in use

Security Configuration

Managed Identity Setup

Enable system-assigned managed identity for secure Azure service access:

# Enable managed identity
az webapp identity assign --name your-app --resource-group your-rg

# Get managed identity object ID
$identityId = az webapp identity show --name your-app --resource-group your-rg --query principalId -o tsv

# Grant Key Vault RBAC access (modern approach)
az role assignment create --assignee $identityId --role "Key Vault Secrets User" --scope "/subscriptions/your-sub/resourceGroups/your-rg/providers/Microsoft.KeyVault/vaults/your-kv"

RBAC Configuration

Required RBAC Roles:

# Key Vault access
az role assignment create --assignee $identityId --role "Key Vault Secrets User" --scope "/subscriptions/your-sub/resourceGroups/your-rg/providers/Microsoft.KeyVault/vaults/your-kv"

# Storage access (if needed)
az role assignment create --assignee $identityId --role "Storage Blob Data Reader" --scope "/subscriptions/your-sub/resourceGroups/your-rg"

API Security

Development Mode Security:

  • All monitoring endpoints require API key authentication
  • Swagger UI requires API key access
  • HTTPS enforcement for all communication
  • Secure headers configuration

Production Mode Security:

  • Minimal endpoint exposure
  • No debug information leakage
  • Optimized for security compliance
  • HSTS and security headers

Troubleshooting

Common Development Issues

Configuration Problems:

# Validate configuration
.\scripts\setup-configuration.ps1 -ValidateOnly

# Check environment status
.\scripts\show-environment.ps1

# Force reconfiguration
.\scripts\setup-configuration.ps1 -Force

Deployment Failures:

# Check Azure CLI authentication
az account show

# Verify resource access
az webapp list --query "[].{name:name,resourceGroup:resourceGroup}" -o table

# Check build errors
dotnet build --configuration Release

Runtime Issues:

# Check application logs
az webapp log tail --name your-app --resource-group your-rg

# Verify webhook endpoints
curl https://your-app.azurewebsites.net

# Test with API key
curl -H "X-API-Key: $apiKey" https://your-app.azurewebsites.net/health

Debug Tools

Application Insights Queries:

requests
| where timestamp > ago(1h)
| where url contains "api/"
| summarize count() by resultCode, bin(timestamp, 5m)

Log Analytics:

AppServiceConsoleLogs
| where TimeGenerated > ago(1h)
| where ResultDescription contains "CallAutomationService"
| order by TimeGenerated desc

Performance Monitoring:

# System metrics
curl -H "X-API-Key: $apiKey" https://your-app.azurewebsites.net/health/metrics

# Call statistics
curl -H "X-API-Key: $apiKey" https://your-app.azurewebsites.net/health/calls

Production Deployment

Pre-Production Checklist

Configuration Validation:

  • All Key Vault secrets configured
  • DirectLine secret from Copilot Studio Web Channel Security
  • Phone number configured in ACS with "Receive calls" capability
  • Event Grid subscription active and pointing to correct webhook endpoint
  • Managed Identity permissions set

Event Grid Configuration:

  • Subscription configured for Microsoft.Communication.IncomingCall events only
  • Webhook endpoint: https://your-app-name.azurewebsites.net/api/incomingCall
  • Retry policy: Max 2 delivery attempts, 1 minute TTL
  • Diagnostic logging enabled for troubleshooting

Performance Validation:

  • Load testing completed
  • Auto-scaling configured
  • Application Insights enabled
  • Alert rules configured

Security Validation:

  • Production mode enabled
  • HTTPS enforcement active
  • Sensitive endpoints disabled
  • Access logging configured

Production Deployment Process

# 1. Switch to production mode
.\scripts\switch-to-production.ps1

# 2. Deploy application
.\scripts\deploy-application.ps1

# 3. Verify production configuration
.\scripts\show-environment.ps1

# 4. Test phone number integration
# Call your ACS phone number to verify end-to-end functionality

Production Monitoring

Application Insights Setup:

  • Configure availability tests for key endpoints
  • Set up alert rules for failure rates and response times
  • Monitor custom metrics for call success rates

Azure Monitor Integration:

  • Resource health monitoring
  • Service-level monitoring
  • Performance counter tracking

External Monitoring:

  • Consider third-party monitoring for comprehensive coverage
  • Implement uptime monitoring from multiple geographic locations
  • Set up SMS/email alerts for critical failures

Next Steps

Support Resources

ACSforMCS Documentation

Home

Getting Started

Advanced

Development

Quick Actions

External Links

Demo

Clone this wiki locally