Testing and debugging Cortana skills

The following options are available to test and debug your Cortana skill.

  • Use the Bot Framework emulator to test and debug your skill while you are developing it. The emulator interacts with your bot, and displays the messages exchanged.

    Currently, the emulator does not support passing user profile and contextual information to your Cortana skill. For more information about using the emulator, visit the Debug with the emulator page.

  • Use the debugger in Visual Studio Code to walk through your code as it runs in the console window.

    For more information, visit the Debug a Bot Service bot page.

  • Use the Chat window in the Bot Framework portal. Typically, you test after configuring your Cortana channel and deploying your service in order to confirm that your bot is running.

  • Enable debug in Cortana to see the message exchange between Cortana and your Cortana skill.

    For information about enabling debugging, visit the Enable debugging in Cortana section.

    For details about debugging your Cortana skill in Azure continuous publishing environment, visit the Debug an Azure Bot Service bot page.

    Tip

    Before you start debugging your Cortana skill, visit the Troubleshooting tips section and the Known Issues page.

Enable debugging in Cortana

If Cortana reports an error when running your skill, then follow the steps below to turn on debugging for Cortana. After you enable debugging, the Cortana Canvas displays all errors and message exchanges.

  1. Go to the Configure Cortana page for your Cortana skill. Under the Enable Cortana debug mode across all devices section, click Run Cortana in debug mode to enable.

  2. Invoke Cortana to test your Cortana skill. Make sure you're signed in using the same MSA that you used for the Bot Framework.

    For more information, visit the Get started page.

    a. On the top-left menu, click on the Home icon. (This will update the Cortana skills information.)

    b. On the bottom-right corner, click on the microphone icon.

    c. Invoke your Cortana skill by speaking.

    d. The canvas displays a debug button.

    e. Click to see the message exchange details.

    Debugging Information

Troubleshooting tips

The following provides suggestions for solving common problems.

Issue
I am not able to invoke my Cortana skill
Cortana is spelling my invocation name incorrectly when I say it
I get a DownstreamDependencyFailed error
I signed into Bot Framework but do not see my Cortana skills
SSML reads XML characters aloud
Cortana returns a 403 Forbidden error
I am able to invoke my Cortana skill but no one else can

I am not able to invoke my Cortana skill

Check the following

  • If you just made changes and saved, click on the Home icon on top-left menu to refresh the Cortana skills information.
  • Verify that debugging is enabled. For more information, visit the Enable debugging in Cortana section.
  • Verify that you signed into Cortana using the same MSA that you used to sign into Bot Framework.
  • Ensure that you are properly invoking your skill.
  • Verify that Cortana uses the correct name when invoked. The Cortana Canvas types the name in the Type here to search box as you speak.
  • Check that your device is set to one of the allowed locales. The Supported Cortana locales page has more information.
  • Make sure that your microphone is configured. Visit the Get started page for more information.

Cortana is spelling my invocation name incorrectly when I say it

Check the following:

  • If you just saved for the first time, updates to Cortana may be delayed up to 10 minutes before recognizing the invocation name of your Cortana skill.
  • If you just made changes and saved, click on the Home icon on top-left menu to refresh the Cortana skills information.
  • Your invocation name may be difficult for Cortana to recognize. For more information about designing invocation names, visit the Invocation Guidelines page.

I get a DownstreamDependencyFailed error

You will get this error when the service endpoint you created fails to respond. Some common reasons:

  • If your service takes too long to respond, Cortana cancels the request with a time-out.
  • If the response message is not formatted correctly based on the Bot Framework schema.
  • If your service returns an http status code other than 200.

I signed into Bot Framework but do not see my Cortana skills

Ensure that you signed into Bot Framework with the same MSA that you used to configure the Cortana channel within the Azure portal.

SSML reads XML characters aloud

If Cortana reads out the XML characters of your invocation, then the XML is likely not valid. Verify that all opening tags have closing tags and vice-versa. Consider using an XML library to verify that your XML is properly formatted.

Cortana returns a 403 Forbidden error

Cortana tried to connect to your service, but received an https status code of 403 Forbidden. Verify that your service endpoint is configured to accept POST requests, not GET requests.

I am able to invoke my Cortana skill, but no one else can

Ensure that you have deployed your skill.

  • If you want to make your skill available to a group of people, such as your family and friends, use the Test Group settings option.

  • If you want everyone to have access to your skill, use the World settings option. Your skill will be reviewed by Microsoft if you choose this option.

    See Publishing Cortana skills for details on the publishing process.

    Important

    If your skill includes code that checks the skill ID in the request, then you have to remember to change the ID as you move between steps. The ID value will be different for each of the default, test group, and world versions of your Cortana skill.

Additional resources

Stack Overflow forums

Azure debugging resources

Azure Web Apps

Azure Functions

Bot Framework troubleshooting guides