Alexa.Tip – How to Host Alexa Skills in Azure

If you’re a .NET developer in the Azure cloud sphere and want to start dabbling in Alexa Skill Development, you don’t have to uproot your entire career and development process to go learn AWS, how Lambdas work, the serverless lifecycle, etc. In this post, we’ll go over just how easy it can be to build an Alexa Skill using C#, ASP.NET Core, and Azure!

The traditional setup for Alexa Skills is:
– AWS Lambda
– .NET Core Lambda project template

But we’re going to be using:
– Azure App Services
– ASP.NET Core API project template

NOTE: This is not an introduction into how Alexa skills work, or how to create your very first skill. This is meant to provide options for hosting your skills, and for how to build skills in general using .NET. If you’re BRAND new to Alexa Skill development, start by reading through their documentation (mostly using node.js, but focus on the structure of an interaction model, what intents and slots are, etc.)

For source of the entire project checkout: https://github.com/SuavePirate/Alexa.NET.WebApi

Step 1 – Create an Alexa Developer Account

If you haven’t already created an Alexa Developer account, you’ll need one in order to register and test your skill.

Simply follow, the Amazon documentation on how to do this – super simple: https://developer.amazon.com/alexa

Step 2 – Create a Skill in the Developer Console

With your Alexa developer account, create a new Skill.

Choose Custom Skill:

create_skill

Then choose the empty “Start from Scratch” template:

choose_template

Now you can manage your interaction model.

For this example, we are going to create a skill that let’s users ask for information about Animals. We’ll use a custom Intent for this, but use the built in AMAZON.Animal slot.

On the left side, go to JSON Editor and paste this interaction model. You can make adjustments as you see fit:

interactionModel.json

{
  "interactionModel": {
    "languageModel": {
      "invocationName": "animal facts",
      "intents": [
        {
          "name": "AMAZON.FallbackIntent",
          "samples": []
        },
        {
          "name": "AMAZON.CancelIntent",
          "samples": [
            "I'm all set"
          ]
        },
        {
          "name": "AMAZON.HelpIntent",
          "samples": []
        },
        {
          "name": "AMAZON.StopIntent",
          "samples": [
            "Quit",
            "Goodbye"
          ]
        },
        {
          "name": "AnimalFactIntent",
          "slots": [
            {
              "name": "Animal",
              "type": "AMAZON.Animal"
            }
          ],
          "samples": [
            "I'd like to know about {Animal}",
            "What is an {Animal}",
            "Give me information about the {Animal}",
            "Tell me about {Animal}"
          ]
        }
      ],
      "types": []
    }
  }
}

This allows our users to ask things such as “Tell me about Monkeys” and then use the animal they are asking for to send information back to them!

Step 3 – Create the ASP.NET Core API

In Visual Studio, create a new project and choose the ASP.NET Core Web Application:

aspnetcore

In the next dialog, select the API template, and be sure that HTTPS is enabled:

API_project_with_https

With your new web application, you’ll need to install the Alexa.NET Nuget Package from Tim Heuer
https://www.nuget.org/packages/Alexa.NET/1.5.5-pre

This nuget package has models for the JSON that Alexa sends to your API and a convenient fluid API design for building your responses that is similar to how the actual Alexa Java and JavaScript SDKs work.

Now that the Alexa models are available, let’s create a new API controller:

AlexaController.cs

[Route("api/[controller]")]
public class AlexaController : Controller
{
    /// <summary>
    /// This is the entry point for the Alexa skill
    /// </summary>
    /// <param name="input"></param>
    /// <returns></returns>
    [HttpPost]
    public SkillResponse HandleResponse([FromBody]SkillRequest input)
    {
        var requestType = input.GetRequestType();

        // return a welcome message
        if(requestType == typeof(LaunchRequest))
        {
            return ResponseBuilder.Ask("Welcome to animal facts, ask me about information on an animal", null);
        }

        // return information from an intent
        else if (requestType == typeof(IntentRequest))
        {
            // do some intent-based stuff
            var intentRequest = input.Request as IntentRequest;

            // check the name to determine what you should do
            if (intentRequest.Intent.Name.Equals("AnimalFactIntent"))
            {
                // get the slots
                var animal = intentRequest.Intent.Slots["Animal"].Value;
                if(animal == null)
                    return ResponseBuilder.Ask("You forgot to ask about an animal! Please try again.", null);

                return ResponseBuilder.Tell($"I would normally tell you facts about ${animal} but I'm not a real skill yet.");
            }
        }

        return ResponseBuilder.Ask("I didn't understand that, please try again!", null);
    }
}

This controller contains a single HTTP POST endpoint that takes in an SkillRequest. It then breaks down the request in order to respond accordingly. So if the user opens the skill which initiates the LaunchRequest, we can give them a welcome message with hints on what they can ask about. Then if they ask for information about an animal, we can handle the IntentRequest with the intent name of “AnimalFactIntent” and use the Animal slot value!

That’s all there is too it! I’d normally suggest abstracting this out of using the controller so that it is more easily testable with unit tests, but for the sake of a simple example, it will work fine.

Step 4 – Publish to Azure App Service

Now that we have our ASP.NET Core project, we need to publish it to an Azure App Service. You can do this directly in Visual Studio or in the Azure portal. For the sake of this example, we’ll do it directly in Visual Studio – assuming you have a valid Azure license and account setup.

From the Solution Explorer – right click your project and Select “Publish”.

Select the “App Service” option and click “Create”.

Then fill out the form to create a new App Service:
AzurePublish

Once your publish is done, you’ll need to ensure that HTTPS / SSL is configured correctly for your app service.

In the Azure portal, go to your new App Service, then scroll to the SSL Settings section.

Be sure that you enforce SSL (Alexa requires endpoints to use HTTPS with trusted certificates. The default App Service SSL cert is signed with Microsoft’s trusted certificate which means that Amazon will accept it).

azure_ssl.PNG

Now make sure that you can hit your App service API endpoint. I usually prefer to enable Swagger for my API using Swashbuckle for this: https://docs.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-2.1&tabs=visual-studio%2Cvisual-studio-xml

Step 5 – Register Endpoint with Alexa Skill

Now that we have our App Service with HTTPS set up, we need to go back to the Alexa Developer Console and to the skill. In the left menu, scroll down to the “Endpoint” option.

In the main view, select “HTTPS” instead of “AWS Lambda ARN”. Then enter the URL for the endpoint in your app service and choose the subdomain ssl cert option:
azure_alexa_endpoint

Once this is done, you can save, and build your skill then proceed to test it!

Step 6 – Test

In the Alexa Developer Console, go to your skill and select the “Test” tab. Here you can type or say things like “Open Animal Facts” or “Ask Animal Facts to tell me about Monkeys”.

animal skill test

Here you can also view the JSON that Alexa is sending to your skill and use that to test against your skill directly using something like Swagger or Postman.

Here’s an example JSON input you could use to test:

{
    "version": "1.0",
    "session": {
        "new": false,
        "sessionId": "...",
        "application": {
            "applicationId": "..."
        },
        "user": {
            "userId": "..."
        }
    },
    "context": {
        "AudioPlayer": {
            "playerActivity": "IDLE"
        },
        "Display": {
            "token": ""
        },
        "System": {
            "application": {
                "applicationId": "..."
            },
            "user": {
                "userId": "..."
            },
            "device": {
                "deviceId": "...",
                "supportedInterfaces": {
                    "AudioPlayer": {},
                    "Display": {
                        "templateVersion": "1.0",
                        "markupVersion": "1.0"
                    }
                }
            },
            "apiEndpoint": "https://api.amazonalexa.com",
            "apiAccessToken": "..."
        }
    },
    "request": {
        "type": "IntentRequest",
        "requestId": "...",
        "timestamp": "2018-09-04T17:07:45Z",
        "locale": "en-US",
        "intent": {
            "name": "AnimalFactIntent",
            "confirmationStatus": "NONE",
            "slots": {
                "Animal": {
                    "name": "Animal",
                    "value": "monkeys",
                    "confirmationStatus": "NONE"
                }
            }
        }
    }
}

You can also test on a real Alexa device! Once you enabled testing, any device that is assigned to the same email address as your Alexa Developer Account will have it enabled.

And that’s it! Now get out there and build some Alexa Skills in .NET!


If you like what you see, don’t forget to follow me on twitter @Suave_Pirate, check out my GitHub, and subscribe to my blog to learn more mobile and AI developer tips and tricks!

Interested in sponsoring developer content? Message @Suave_Pirate on twitter for details.


voicify_logo
I’m the Director and Principal Architect over at Voicify. Learn how you can use the Voice Experience Platform to bring your brand into the world of voice on Alexa, Google Assistant, Cortana, chat bots, and more: https://voicify.com/


Advertisements

Add Model Validation to Your ASP.NET Core Web API

If you’re used to creating traditional Web APIs in ASP.NET, you’ve probably become accustom to using System.ComponentModel.DataAnnotations such as the [Required] or [StringLength] data attributes. Using these in your models that are parameters to your API project would return the proper 400 response code when the input didn’t match the requirement.

In ASP.NET Core 2.0, this is no longer built in right out of the box, but setting it up is super easy! So if you don’t want to abstract your model validation in your business logic layer and want to get it out of the way right away when the request comes in, check this out.

There are only two steps to doing this:

  • Create an implementation of `IActionFilter`
  • Register this Filter class in your startup

Let’s start by creating a ValidatorActionFilter class:

ValidatorActionFilter.cs

/// <summary>
/// Filter for returning a result if the given model to a controller does not pass validation
/// </summary>
public class ValidatorActionFilter : IActionFilter
{
    public void OnActionExecuting(ActionExecutingContext filterContext)
    {
        if (!filterContext.ModelState.IsValid)
        {
            filterContext.Result = new BadRequestObjectResult(filterContext.ModelState);
        }
    }

    public void OnActionExecuted(ActionExecutedContext filterContext)
    {

    }
}

What this does is check the current HttpContext.ModelState to make sure it is valid. This allows us to ensure we don’t have to make this check in each endpoint. Note, we don’t have to add anything in the OnActionExecuted method since this filter is used exclusively before the action is called.

In the OnActionExecuting call, if the model state is NOT valid, we need to return the 400 – Bad Request response as the result.

Now, let’s register this in our startup. We do this by applying it in the ConfigureServices call and specifically in the options of the AddMvc call:

Startup.cs

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc(options =>
    {
        options.Filters.Add(typeof(ValidatorActionFilter));
    });
}

And that’s it! So now your endpoints will return the proper response such as:

MyInputModel.cs

public class MyInputModel
{
    [Required]
    public string SomeRequiredValue { get; set; }
    public string SomeNotRequiredValue { get; set; }
}

MyController.cs

public class MyController : Controller
{
    public ActionResult DoSomeAction([FromBody]MyInputModel input)
    {
         return Ok("You did it"!)
    }
}

The request of:

{
    "someNotRequiredValue": "Hey"
}

Will return 400 - Bad Request - "The SomeRequiredValue field is required"

And the request of:

{
    "someRequiredValue": "Yo"
    "someNotRequiredValue": "Hey"
}

Will return 200 - Ok - "You did it!"

So go forth and validate those input models with ease!


If you like what you see, don’t forget to follow me on twitter @Suave_Pirate, check out my GitHub, and subscribe to my blog to learn more mobile developer tips and tricks!

Interested in sponsoring developer content? Message @Suave_Pirate on twitter for details.