Skip to content

Local Development

Jump to bottom
Holger Imbery edited this page Sep 19, 2025 · 11 revisions

Local Development

Local development with dev tunnels is an optional fallback approach for initial testing and debugging. The recommended primary development approach is Azure Development using Azure Web Apps.

When to Use Local Development

Appropriate Use Cases

  • Initial code testing and rapid iteration
  • Debugging specific features in isolation
  • Learning the codebase structure
  • Offline development scenarios

Not Recommended For

  • Primary development workflow (use Azure Web Apps instead)
  • Extended testing periods (Azure provides better stability)
  • Production-like testing (Azure Web Apps match production environment)
  • Team collaboration scenarios

Recommended Development Workflow

  1. Optional local testing (this guide) - Quick initial validation
  2. Azure Web App development (recommended) - Primary development environment
  3. Production deployment - Switch Azure Web App to production mode

Prerequisites

Required Tools

Existing Azure Resources

You must have these Azure resources already configured:

  • Azure Communication Services with a phone number
  • Azure Key Vault with required secrets
  • Azure Cognitive Services (Speech)
  • Microsoft Copilot Studio agent with DirectLine secret from Web Channel Security

Note: Use the Quick Installation guide to create these resources if needed.

Setup Process

1. Clone Repository

git clone https://github.com/holgerimbery/ACSforMCS.git
cd ACSforMCS

2. Configure Azure Dev Tunnels

Azure Dev Tunnels creates a secure tunnel exposing your local service to the internet, enabling Azure Communication Services to reach your development machine.

# Authenticate with Azure Dev Tunnels
devtunnel login

# Create a tunnel (one-time setup)
devtunnel create --allow-anonymous

# Start hosting the tunnel on port 5252
devtunnel host -p 5252 --allow-anonymous

Save your tunnel URL (e.g., https://abc123.devtunnels.ms) - you'll need this for configuration.

3. Configure Application Settings

Create local configuration file:

# Copy sample file
cp appsettings.json.sample appsettings.json

Configure .NET User Secrets:

# Initialize user secrets for the project
dotnet user-secrets init --project ACSforMCS.csproj

# Configure Key Vault endpoint
dotnet user-secrets set "KeyVault:Endpoint" "https://your-keyvault-name.vault.azure.net/" --project ACSforMCS.csproj

4. Configure Key Vault Secrets

Add the dev tunnel URL to your Key Vault for local development:

# Set development base URI to your dev tunnel URL
az keyvault secret set --vault-name "your-keyvault-name" --name "BaseUri-Development" --value "https://your-devtunnel-url.devtunnels.ms"

# Verify all required secrets exist
az keyvault secret list --vault-name "your-keyvault-name" --query "[].name" -o table

Required Key Vault secrets:

  • AcsConnectionString - Azure Communication Services connection string
  • DirectLineSecret - From Copilot Studio Web Channel Security
  • BaseUri-Development - Your dev tunnel URL
  • BaseUri-Production - Your Azure Web App URL
  • AgentPhoneNumber - Transfer target phone number (E.164 format)
  • CognitiveServiceEndpoint - Azure Speech Services endpoint
  • HealthCheckApiKey - API key for monitoring endpoints

5. Configure Event Grid Subscription

Configure Azure Communication Services to send call events to your local development environment:

  1. Azure Portal → Communication Services → Your ACS resource
  2. Events → Event Subscriptions → Create
  3. Event Types: Select Microsoft.Communication.IncomingCall
  4. Endpoint Type: Web Hook
  5. Endpoint: https://your-devtunnel-url.devtunnels.ms/api/incomingCall
  6. Create the subscription

Running Locally

Start the Application

# Run in Development mode
dotnet run --environment Development

The application will start and be accessible through your dev tunnel URL.

Verify Configuration

  1. Check application status:

    curl https://your-devtunnel-url.devtunnels.ms

    Should return: "Hello Azure Communication Services, here is Copilot Studio!"

  2. Access Swagger documentation:

    # Get API key
$apiKey = az keyvault secret show --vault-name "your-kv" --name "HealthCheckApiKey" --query value -o tsv

# Access Swagger UI
# Navigate to: https://your-devtunnel-url.devtunnels.ms/swagger
# Add header: X-API-Key: $apiKey

  3. Monitor health endpoints:

    # Check system health
curl -H "X-API-Key: $apiKey" https://your-devtunnel-url.devtunnels.ms/health

# Monitor active calls
curl -H "X-API-Key: $apiKey" https://your-devtunnel-url.devtunnels.ms/health/calls

Testing Integration

Test Phone Calls

  1. Place a test call to your Azure Communication Services phone number
  2. Verify call connection - Should hear initial greeting
  3. Test conversation - Speak naturally to interact with Copilot Studio agent
  4. Monitor logs - Watch console output for real-time processing information

Monitor Application Logs

The console displays comprehensive logging:

  • Call Events: Incoming calls, connections, disconnections
  • Speech Recognition: Real-time transcription results
  • Bot Communication: DirectLine API interactions
  • Response Generation: Text-to-speech conversion
  • Transfer Events: Call transfer attempts and results

Test Call Transfer

If you've configured call transfer functionality:

  1. Configure transfer topic in Copilot Studio with format:

    I'll transfer you now. TRANSFER:+1234567890:Please hold while I connect you.

  2. Trigger transfer during a call by saying phrases that match your transfer topic

  3. Monitor transfer in application logs for transfer success/failure

Debugging and Development

Visual Studio Integration

Using Visual Studio 2022:

  1. Open ACSforMCS.sln in Visual Studio
  2. Set environment to Development
  3. Configure user secrets through the project context menu
  4. Start debugging with F5

Dev Tunnel Integration:

  • Visual Studio can automatically create dev tunnels
  • Right-click project → Properties → Debug → Open debug launch profiles UI
  • Enable dev tunnels for automatic URL management

VS Code Integration

Using VS Code:

  1. Open project folder in VS Code
  2. Install C# extension
  3. Configure launch.json for debugging
  4. Use integrated terminal for dev tunnel management

Common Development Tasks

Update configuration:

# Update Key Vault secrets
az keyvault secret set --vault-name "your-kv" --name "DirectLineSecret" --value "new-secret"

# Update user secrets
dotnet user-secrets set "KeyVault:Endpoint" "https://new-keyvault.vault.azure.net/"

# Restart application to pickup changes

Test specific features:

# Test DirectLine connectivity
curl -H "Authorization: Bearer your-directline-secret" https://directline.botframework.com/v3/directline/conversations

# Test speech services
curl -H "Ocp-Apim-Subscription-Key: your-key" https://your-region.api.cognitive.microsoft.com/sts/v1.0/issuetoken

Performance Considerations

Local Development Limitations

Network Latency:

  • Dev tunnels add network latency compared to Azure deployment
  • Real-time audio streaming may have reduced quality
  • Use for functional testing, not performance validation

Resource Constraints:

  • Local machine resources limit concurrent call capacity
  • Memory and CPU usage higher than optimized Azure deployment
  • Not suitable for load testing

Connectivity Dependencies:

  • Requires stable internet connection for dev tunnel
  • Tunnel disconnections break active calls
  • Azure Web App deployment provides better reliability

Optimization Tips

Reduce Latency:

  • Use dev tunnel regions closest to your Azure resources
  • Minimize other network-intensive applications
  • Test during off-peak hours for best tunnel performance

Monitor Resource Usage:

  • Watch CPU and memory usage during calls
  • Limit concurrent test calls based on local capacity
  • Use Task Manager or Activity Monitor to track performance

Migration to Azure Development

After initial local testing, migrate to Azure Web App development:

Why Migrate to Azure

  • Production Parity: Same environment as production
  • Better Performance: Optimized Azure infrastructure
  • Integrated Monitoring: Built-in health endpoints and Application Insights
  • WebSocket Optimization: Better real-time audio streaming
  • Environment Switching: Easy Development ↔ Production mode switching
  • Team Collaboration: Shared development environment

Migration Process

  1. Stop local development:

    # Stop the local application (Ctrl+C)
# Stop dev tunnel
devtunnel stop

  2. Deploy to Azure Web App:

    # Use deployment scripts for automated setup
.\scripts\setup-configuration.ps1
.\scripts\switch-to-development.ps1
.\scripts\deploy-application.ps1

  3. Update Event Grid subscription:

    • Change webhook endpoint from dev tunnel URL to Azure Web App URL
    • Format: https://your-app-name.azurewebsites.net/api/incomingCall

  4. Update Key Vault configuration:

    # Update base URI to Azure Web App
az keyvault secret set --vault-name "your-kv" --name "BaseUri-Development" --value "https://your-app-name.azurewebsites.net"

Troubleshooting

Common Issues

Dev tunnel connectivity:

# Check tunnel status
devtunnel list

# Recreate tunnel if needed
devtunnel delete --tunnel-id your-tunnel-id
devtunnel create --allow-anonymous

Azure authentication:

# Re-authenticate if needed
az login
az account show

# Verify Key Vault access
az keyvault secret list --vault-name "your-kv"

Application configuration:

# Verify user secrets
dotnet user-secrets list --project ACSforMCS.csproj

# Clear and reset if needed
dotnet user-secrets clear --project ACSforMCS.csproj
dotnet user-secrets set "KeyVault:Endpoint" "https://your-kv.vault.azure.net/"

Call connectivity issues:

  • Verify Event Grid subscription is active and pointing to correct endpoint
  • Check that DirectLine secret is current and valid
  • Ensure Copilot Studio agent is published and responsive

Debug Resources

Application logs:

  • Monitor console output for real-time debugging
  • Look for specific error patterns in DirectLine communication
  • Check Azure Key Vault access errors

External validation:

# Test DirectLine endpoint directly
curl -H "Authorization: Bearer your-secret" https://directline.botframework.com/v3/directline/conversations

# Verify dev tunnel accessibility
curl https://your-devtunnel-url.devtunnels.ms

# Check ACS phone number status
az communication phonenumber show --phone-number "+1234567890"

Next Steps

Recommended Migration Path

  1. Complete initial testing using this local development guide
  2. Migrate to Azure Web App using Azure Development guide
  3. Configure production deployment for live usage

Additional Resources

External Documentation

Important Reminder: Local development is intended for initial testing only. Use Azure Development for your primary development workflow to ensure production parity and optimal performance.

ACSforMCS Documentation

Home

Getting Started

Advanced

Development

Quick Actions

External Links

Demo

Clone this wiki locally