Skip to content

Home

Build Status NuGet Downloads

AlexaVoxCraft is a modular C# .NET library for building Amazon Alexa skills using modern .NET practices. It provides comprehensive support for Alexa skill development with CQRS patterns, visual interfaces, and AWS Lambda hosting.

Key Features

  • 🎯 MediatR Integration: CQRS-style request handling with compile-time source-generated DI registration
  • 🎨 APL Support: Complete Alexa Presentation Language implementation for rich visual interfaces
  • ⚡ Lambda Hosting: Optimized AWS Lambda runtime with custom serialization and ReadyToRun publishing
  • 📊 Session Management: Robust session attribute handling and game state persistence
  • 🔧 Pipeline Behaviors: Request/response interceptors for cross-cutting concerns like logging and validation
  • 🧪 Testing Support: Comprehensive testing utilities with AutoFixture integration and property-based testing

Installation

# Minimal Lambda hosting and MediatR integration
dotnet add package AlexaVoxCraft.MinimalLambda
dotnet add package AlexaVoxCraft.MediatR

# APL visual interface support
dotnet add package AlexaVoxCraft.Model.Apl

# Structured logging for Alexa skills
dotnet add package AlexaVoxCraft.Logging

# OpenTelemetry observability (optional)
dotnet add package AlexaVoxCraft.Observability

Requirements

⚠️ SDK Version Required: To use source-generated dependency injection with interceptors, you must use at least version 8.0.400 of the .NET SDK. This ships with Visual Studio 2022 version 17.11 or higher.

# Check your SDK version
dotnet --version
# Should show 8.0.400 or higher

Quick Start - Building a Trivia Skill

All code examples in this documentation demonstrate building a trivia game skill. Here's a complete implementation:

// Program.cs
using AlexaVoxCraft.Lambda.Abstractions;
using AlexaVoxCraft.MediatR.DI;
using AlexaVoxCraft.MinimalLambda;
using AlexaVoxCraft.MinimalLambda.Extensions;
using AlexaVoxCraft.Model.Apl;
using AlexaVoxCraft.Model.Response;
using Amazon.Lambda.Core;
using LayeredCraft.Logging.CompactJsonFormatter;
using MinimalLambda.Builder;
using Serilog;

APLSupport.Add();

Log.Logger = new LoggerConfiguration()
    .WriteTo.Console(new CompactJsonFormatter())
    .CreateLogger();

var builder = LambdaApplication.CreateBuilder();

// Handlers are automatically discovered and registered at compile time
builder.Services.AddSkillMediator(builder.Configuration);

// AlexaVoxCraft Minimal Lambda host
builder.Services.AddAlexaSkillHost<TriviaSkillHandler, APLSkillRequest, SkillResponse>();

await using var app = builder.Build();
app.MapHandler(AlexaHandler.Invoke<APLSkillRequest, SkillResponse>);
return await app.RunAsync();

// Lambda handler bridges MediatR to the MinimalLambda host
public class TriviaSkillHandler : ILambdaHandler<APLSkillRequest, SkillResponse>
{
    private readonly ISkillMediator _mediator;

    public TriviaSkillHandler(ISkillMediator mediator) => _mediator = mediator;

    public Task<SkillResponse> HandleAsync(APLSkillRequest request, ILambdaContext context, CancellationToken cancellationToken) =>
        _mediator.Send(request, cancellationToken);
}

// Request Handler
public class LaunchRequestHandler : IRequestHandler<LaunchRequest>
{
    public bool CanHandle(IHandlerInput handlerInput) =>
        handlerInput.RequestEnvelope.Request is LaunchRequest;

    public async Task<SkillResponse> Handle(IHandlerInput input, CancellationToken cancellationToken)
    {
        return await input.ResponseBuilder
            .Speak("Welcome to Trivia Challenge! Ready to test your knowledge?")
            .Reprompt("Say yes to start playing, or help for instructions.")
            .WithSimpleCard("Trivia Challenge", "Welcome to Trivia Challenge!")
            .GetResponse(cancellationToken);
    }
}

Available Components

📝 Note: All component documentation uses trivia skill examples to demonstrate features and patterns.

Request Handling

Modern request handling patterns with trivia game examples:

  • MediatR integration for CQRS
  • Compile-time source-generated handler registration
  • Type-safe request/response processing
  • Exception handling pipeline
  • Request validation and routing

Source Generation

Compile-time dependency injection with C# interceptors:

  • Zero runtime reflection - faster Lambda cold starts
  • Automatic handler discovery at compile time
  • Customizable registration with attributes
  • Execution ordering for pipeline behaviors
  • Type-safe validation during build

APL Integration

Rich visual interface support for trivia questions with:

  • Fluent document builder API
  • Multi-slide presentations
  • Interactive components
  • Voice/touch synchronization
  • Custom layout management

Lambda Hosting

Optimized AWS Lambda runtime for trivia skills with:

  • Custom serialization for Alexa models
  • ReadyToRun publishing for faster cold starts
  • Self-contained deployment options
  • Environment-specific configuration
  • Comprehensive logging integration

Session Management

Robust game state management with:

  • Session attribute persistence
  • Game state tracking
  • User data management
  • Multi-turn conversation support
  • DynamoDB integration patterns

Pipeline Behaviors

Cross-cutting concerns for skill management with:

  • Request/response interceptors
  • Logging and telemetry
  • User authentication and authorization
  • Error handling and recovery
  • Performance monitoring

OpenTelemetry Observability

Comprehensive observability for production skills with:

  • Standards-compliant OpenTelemetry instrumentation
  • Request processing spans with semantic attributes
  • Performance metrics and cold start tracking
  • Privacy-safe session correlation
  • Zero-configuration, opt-in telemetry

Documentation

  • Examples - Complete trivia skill implementation with real-world patterns

Real-World Example

Our documentation is built around a complete, production-ready trivia skill that demonstrates:

  • Game Logic: Question management, scoring, and leaderboards
  • Visual Interface: APL documents with interactive slides
  • Data Persistence: DynamoDB integration for user and game data
  • Deployment: AWS Lambda with CDK infrastructure

See the Examples section for the complete implementation.

Runtime Requirements

  • .NET 8.0, .NET 9.0, or .NET 10.0
  • .NET SDK 8.0.400+ for source generation (VS 2022 17.11+)
  • AWS Lambda Runtime (provided.al2023)
  • Amazon Alexa Developer Account
  • AWS CLI configured with appropriate permissions

Architecture Patterns

AlexaVoxCraft follows these architectural patterns:

  1. CQRS with MediatR: Separate command and query responsibilities
  2. Pipeline Pattern: Composable request/response processing
  3. Builder Pattern: Fluent APIs for APL documents and responses
  4. Repository Pattern: Data access abstraction for session and user data
  5. Dependency Injection: Service registration and lifetime management

Contributing

See the main README for contribution guidelines.

License

This project is licensed under the MIT License.