Testing and debugging Cortana Skills

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

  • Use 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.

    Important

    Currently, the emulator does not support passing user profile and contextual information to you Cortana Skill.

    Tip

    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.

    Tip

    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.

    Tip

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

Tip

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

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

Note

If you found an error in another developer's Cortana Skill, ]then click on the feedback button in Cortana and report it.

Enable debugging in Cortana

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

  1. Go to the Configure Cortana page for your Cortana Skill.

    1. Under the Enable Cortana debug mode across all devices section.
      1. Run Cortana in debug mode
        • Click to enable.
  2. Invoke Cortana to test your Cortana Skill.

    1. Sign in using the same MSA that you used for Bot Framework.

      [TIP] For more information, visit the Get started page.

    2. On the top-left menu, click on the Home icon.

      Note

      The icon updates the Cortana Skills information.

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

      1. Invoke your Cortana Skill.

        Tip

        For information about invoking skills, visit the Invocation name guidelines page.

    4. The canvas displays a debug button.

      1. 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 am not able to create more than 20 Cortana Skills
I get a DownstreamDependencyFailed error
I am able to invoke my Cortana-Skill, but no one else is able
I signed into Bot Framework but do not see my Cortana Skills
SSML reads XML characters aloud
Cortana returns Forbidden error

I am not able to invoke my Cortana Skill

Check the following

  • If you just saved, then click on the Home icon on top-left menu to refresh the Cortana Skills information.

  • Verify that you enabled debugging.

    Tip

    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.

  • Ensure that your device is set to one of the allowed locales.

    Tip

    For more information, visit the Supported Cortana locales page.

  • Ensure that your microphone is configured.

    Tip

    For more information, visit the Get started page.

Cortana is spelling my invocation name incorrectly when I say it

Check the following

  • If you just saved for the first time, then updates to Cortana may be delayed up to 10 minutes before recognizing the invocation name of your Cortana Skill.

  • If you just saved, then click on the Home icon on top-left menu to refresh the Cortana Skills information.

  • Your invocation name may be poorly designed, which makes it difficult for Cortana to recognize it.

    Tip

    For more information about well-designed invocation names, visit the Invocation Guidelines page.

I am not able to create more than 20 Cortana Skills

You may associate a maximum of 20 skills to a Microsoft accounts (MSA). If you create more than 20 skills, then use an additional MSA.

I get a DownstreamDependencyFailed error

Get the error when the service endpoint you created fails to respond.

Tip

  • 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 am able to invoke my Cortana Skill, but no one else is able

Ensure that you 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.

Note

If your skill includes code that checks the skill ID in the request, then you must adjust the ID since the value is different between default, test group, and world versions of your Cortana Skill.

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 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.

Additional resources

Stack Overflow forums

Azure debugging resources

Azure Web Apps

Azure Functions

Bot Framework troubleshooting guides