AlexaVoxCraft.Logging 1.0.1.54

🔣 Alexa Vox Craft

Alexa Vox Craft is a modular, opinionated library for building Alexa skills in C# using .NET. It leverages System.Text.Json, MediatR patterns, and extensible components for building and maintaining robust Alexa skills with support for:

• ✅ Clean separation of concerns using MediatR
• ✅ JSON (de)serialization with full control via System.Text.Json
• ✅ APL (Alexa Presentation Language) model support and utilities
• ✅ Custom converters for object, enum, and polymorphic types
• ✅ Lambda-ready with logging, tracing, and testability in mind

What does "AlexaVoxCraft" mean?

• Alexa: Represents the integration with Amazon Alexa, the voice service powering devices like Amazon Echo.
• VoxCraft: Signifies the focus on voice-driven interactions, leveraging the VoxCraft framework.

📦 Credits:

• The core Alexa skill models (AlexaVoxCraft.Model) are based on the excellent work in timheuer/alexa-skills-dotnet.
• APL support (AlexaVoxCraft.Model.Apl) is based on stoiveyp/Alexa.NET.APL.

🏎️ Packages

Package	Build Status	NuGet	GitHub	Downloads
AlexaVoxCraft.Model			📁 Source
AlexaVoxCraft.Model.Apl			📁 Source
AlexaVoxCraft.MediatR.Lambda			📁 Source
AlexaVoxCraft.MediatR			📁 Source
AlexaVoxCraft.Logging			📁 Source

🚀 Getting Started

1. Install Required Packages

Install only the packages you need! If you're not using MediatR or APL features, you can omit those dependencies.

dotnet add package AlexaVoxCraft.Model
# Optional:
dotnet add package AlexaVoxCraft.MediatR.Lambda

2. Create a Lambda Entry Point

await LambdaHostExtensions.RunAlexaSkill<YourAlexaSkillFunction>();

3. Create Your Function Class

public sealed class YourAlexaSkillFunction : AlexaSkillFunction<SkillRequest, SkillResponse>
{
    protected override void Init(IHostBuilder builder)
    {
        builder
            .UseHandler<LambdaHandler, SkillRequest, SkillResponse>()
            .ConfigureServices((context, services) =>
            {
                services.AddSkillMediator(context.Configuration,
                    cfg => { cfg.RegisterServicesFromAssemblyContaining<Program>(); });
            });
    }
}

4. Handle Requests with MediatR

Handlers in AlexaVoxCraft are expected to implement IRequestHandler<T> and optionally implement ICanHandle to provide routing logic.

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

    public async Task<SkillResponse> Handle(IHandlerInput input, CancellationToken cancellationToken = default)
    {
        return await input.ResponseBuilder.Speak("Hello world!").WithShouldEndSession(true)
            .GetResponse(cancellationToken);
    }
}

📋 Logging & Diagnostics

AlexaVoxCraft uses Serilog for structured logging by default. You can configure logging output by adding the following to your appsettings.json:

"Serilog": {
  "Using": [ "Serilog.Sinks.Console" ],
  "WriteTo": [
    {
      "Name": "Console",
      "Args": {
      "formatter": "AlexaVoxCraft.Logging.Serialization.AlexaCompactJsonFormatter, AlexaVoxCraft.Logging"
      }
    }
  ],
  "MinimumLevel": {
    "Default": "Information",
    "Override": {
      "Microsoft": "Warning",
      "Microsoft.AspNetCore": "Warning"
    }
  }
}

ℹ️ Debugging Tip: To enable logging of raw Alexa skill requests and responses during development, add the following line under Override. This is not recommended for production environments.

"AlexaVoxCraft.MediatR.Lambda.Serialization": "Debug"

🧾 Formatter Attribution

🔧 The AlexaCompactJsonFormatter included in this library is adapted from Serilog.Formatting.Compact.CompactJsonFormatter.
This customized formatter renames reserved field names (e.g., @t, @l, @m) to AWS-safe equivalents (_t, _l, _m) to improve compatibility with CloudWatch Logs and metric filters.

Original work © Serilog Contributors, licensed under the MIT License.

🧪 Unit Testing

Sample projects show how to load Alexa requests from JSON and assert deserialized structure. Tests include validation of:

• Correct parsing of SkillRequest types
• APL component deserialization
• Proper usage of custom converters

🛠 Utilities and Helpers

• EnumHelper: Convert to/from [EnumMember]-decorated enums
• ObjectConverter: Deserialize polymorphic object values
• BasePolymorphicConverter<T>: Handle APL and directive subtypes
• AlexaLambdaSerializer: Custom ILambdaSerializer with logging support

⚠️ Error Handling

To intercept and respond to exceptions in your MediatR pipeline, implement the IExceptionHandler interface:

public sealed class MyExceptionHandler : IExceptionHandler
{
    public Task<bool> CanHandle(IHandlerInput handlerInput, Exception ex, CancellationToken cancellationToken = default)
    {
        return Task.FromResult(true); // Catch all
    }

    public Task<SkillResponse> Handle(IHandlerInput handlerInput, Exception ex, CancellationToken cancellationToken = default)
    {
        var response = handlerInput.ResponseBuilder.Speak("Something went wrong. Please try again.");
        return response.GetResponse(cancellationToken);
    }
}

No manual registration is required. Exception handlers are picked up automatically via AddSkillMediator(...).

🛁 Sample Projects

Each sample demonstrates MediatR integration, serialization support, custom directives, and Lambda bootstrapping.

🤭 Roadmap

• ✅ Full widget lifecycle support
• ✅ Advanced directive handling
• ⚖️ OpenTelemetry & logging enrichment
• 🔄 Documentation site

🤝 Contributing

PRs are welcome! Please submit issues and ideas to help make this toolkit even better.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

<table> <tbody> <tr> <td align="center" valign="top" width="14.28%"><a href="https://github.com/LayeredCraft"><img src="https://avatars.githubusercontent.com/u/1405469?v=4?s=100" width="100px;" alt="Nick Cipollina"/><br />_{<b>Nick Cipollina</b>}</a><br /><a href="#content-LayeredCraft" title="Content">🔓</a></td> </tr> </tbody> </table>

This project follows the all-contributors specification. Contributions of any kind welcome!

📜 License

MIT

This project is licensed under the MIT License. See the LICENSE file for details.

Stargazers over time