[Rendering] Getting Started docs lead you to a Hello World that doesn't work and doesn't tell you why

Target Platforms

UWP

SDK Version

2.7.0

Application Name

HelloWorld

Problem Description

Imagine you know nothing about Adaptive Cards are are looking to explore adding them to your app, but first you want to write a Hello World to get your bearings.

You're going to be swiftly lead here: Getting Started (UWP). And immediately follow to here: Render a Card. And before you get any further, you wonder "what JSON do I pass this? none of the snippets here include one". So you'll either have found or search for "Adaptive Cards samples" and land here: https://adaptivecards.io/samples/. You're just going getting started, so you're going to take the first card JSON you see (which is currently "Activity update"). If you're like me, you're not going to process the giant checkbox in the top right for "Use Adaptive Card Templating" because you're getting started and you don't know what that is. So you copy the data JSON and go on your merry way to paste it into your code like so:

        public MainPage()
        {
            this.InitializeComponent();

            var jsonString = @"{
                ""title"": ""publish adaptive card schema"",
                ""description"": ""now that we have defined the main rules and features of the format, we need to produce a schema and publish it to github. the schema will be the starting point of our reference documentation."",
                ""creator"": {
                    ""name"": ""matt hidinger"",
                    ""profileimage"": ""https://pbs.twimg.com/profile_images/3647943215/d7f12830b3c17a5a9e4afcc370e3a37e_400x400.jpeg""
                },
                ""createdutc"": ""2017-02-14t06:08:39z"",
                ""viewurl"": ""https://adaptivecards.io"",
                ""properties"": [
                    { ""key"": ""board"", ""value"": ""adaptive cards"" },
                    { ""key"": ""list"", ""value"": ""backlog"" },
                    { ""key"": ""assigned to"", ""value"": ""matt hidinger"" },
                    { ""key"": ""due date"", ""value"": ""not set"" }
                ]
            }";

            var renderer = new AdaptiveCardRenderer();

            var card = AdaptiveCard.FromJsonString(jsonString);

            var renderedAdaptiveCard = renderer.RenderAdaptiveCard(card.AdaptiveCard);
            if (renderedAdaptiveCard.FrameworkElement != null)
            {
                _myGrid.Children.Add(renderedAdaptiveCard.FrameworkElement);
            }
        }

I know, I know. This is wrong. It's not going to work. But bear with me.

So now try to run your app, and... nothing. Debug through and find that you get a card object, but card.AdaptiveCard is null, and so are the Errors and Warnings values on that object, also no exception is thrown (this is the primary bug). You have something that doesn't work, and zero feedback on what to do.

If the samples are going to default to templated, the getting started guidance needs to accommodate. Either by providing a default templated example (which I'm not sure Template Overview does, as it doesn't show piping in both the data and template JSON), or guiding you to finding non-templated samples to start from.

The fix here from the end user perspective is to find the checkbox on the samples page, uncheck that to get the non-templated JSON, and paste that in. No errors, renders fine, all is good. But that was non obvious from the newbie perspective.

Suggestions

1. Fix the fact that putting a bad JSON doesn't trigger any errors
2. Include a complete sample in your Getting Started that includes inline JSON
3. Highlight that there's a branching choice between templated and not-templated in the Getting Started guide
4. Have a link to a repo of a complete Hello World sample app

Other feedback on this bug form, as a first issue filer:

• The SDK Version prompt should link to details on how to get that information. If you follow the Getting Started instructions you never choose a version, you just get whatever is latest. And you need to know to know how to poke around to get that information.
• The "Card JSON" prompt below seems to imply a single JSON, but if you were dealing with a data JSON and a template JSON that seems like a non-ideal fit.

Screenshots

No response

Card JSON

{
    "title": "Publish Adaptive Card Schema",
    "description": "Now that we have defined the main rules and features of the format, we need to produce a schema and publish it to GitHub. The schema will be the starting point of our reference documentation.",
    "creator": {
        "name": "Matt Hidinger",
        "profileImage": "https://pbs.twimg.com/profile_images/3647943215/d7f12830b3c17a5a9e4afcc370e3a37e_400x400.jpeg"
    },
    "createdUtc": "2017-02-14T06:08:39Z",
    "viewUrl": "https://adaptivecards.io",
    "properties": [
        { "key": "Board", "value": "Adaptive Cards" },
        { "key": "List", "value": "Backlog" },
        { "key": "Assigned to", "value": "Matt Hidinger" },
        { "key": "Due date", "value": "Not set" }
    ]
}

Sample Code Language

C#

Sample Code

        public MainPage()
        {
            this.InitializeComponent();

            var jsonString = @"{
                ""title"": ""publish adaptive card schema"",
                ""description"": ""now that we have defined the main rules and features of the format, we need to produce a schema and publish it to github. the schema will be the starting point of our reference documentation."",
                ""creator"": {
                    ""name"": ""matt hidinger"",
                    ""profileimage"": ""https://pbs.twimg.com/profile_images/3647943215/d7f12830b3c17a5a9e4afcc370e3a37e_400x400.jpeg""
                },
                ""createdutc"": ""2017-02-14t06:08:39z"",
                ""viewurl"": ""https://adaptivecards.io"",
                ""properties"": [
                    { ""key"": ""board"", ""value"": ""adaptive cards"" },
                    { ""key"": ""list"", ""value"": ""backlog"" },
                    { ""key"": ""assigned to"", ""value"": ""matt hidinger"" },
                    { ""key"": ""due date"", ""value"": ""not set"" }
                ]
            }";

            var renderer = new AdaptiveCardRenderer();

            var card = AdaptiveCard.FromJsonString(jsonString);

            var renderedAdaptiveCard = renderer.RenderAdaptiveCard(card.AdaptiveCard);
            if (renderedAdaptiveCard.FrameworkElement != null)
            {
                _myGrid.Children.Add(renderedAdaptiveCard.FrameworkElement);
            }
        }

Start with the Getting Started (UWP), Render a Card, and Template Overview pages, then reproduce the path using AdaptiveCard.FromJsonString and the supplied sample JSON. Compare the templated and non-templated sample flows; done should be a working beginner path with clear guidance about the required JSON and the templating choice.