Microsoft 365 Community Adaptive Cards, 17 Oct 2022

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Adaptive Cards community call – October 2022

Description

The focus in this month’s community is Building Windows 11 Widgets with Adaptive Cards. What are widgets, 3rd party widget platform, development environment prerequisites and 3 steps for creating your Win32 Widget. 1) design your widget (using Adaptive Cards), 2) implement IWidgetProvider interface (methods for handling communications between widgets board and your app), and 3) register your widget (changes to APPX Manifest). Deploy your widget. Widget development does not require you to be a Windows developer, do recommend following referenced guidance. Post demo related Q&A. Resources included in blog post. This call was hosted by J.P. Roca (Microsoft) | @jpthepm. Recorded on October 13, 2022.

Stay connected
• Twitter - https://twitter.com/microsoft365dev
• Blog - https://aka.ms/m365pnp/blog
• Recurrent Invite - https://aka.ms/adaptivecardscommunitycall
• Next call – November 10th at 09:00am PT

Learn more
• Microsoft 365 Unified Sample gallery - https://aka.ms/m365/samples
• Microsoft 365 Platform Community in YouTube - https://aka.ms/m365/videos
• Microsoft 365 Platform Community - https://aka.ms/m365/community

A

A

To the Adaptive cards, October 2022 Community call I, have a very exciting call ahead of us here today. We're going to be talking about building windows, 11 widgets with adaptive cards and then we'll go ahead and go into our q, a section. We will also have a demo for the building windows. 11 widgets.

A

This has been a feature that our team has been working on for the past year. So it's it's great to see that it's it's finally available in preview and you'll be able to test it right after this call. If you, if you wish, let's go ahead and get started so the first thing is just an introduction to widgets. In case you haven't seen them before these widgets are available in Windows 11 and you can find them on the Windows 11 widgets board.

A

So in order to access the widgets board, you can click on the bottom left icon. You see right there or using the windows plus W shortcut, and these are available in Windows 11.. So what widgets are they? They are small UI containers that are associated with an app they're meant to be glancible and actionable, and they are also customizable allowing users to select different sizes for them, and also users can drag and drop widgets inside the widgets board to place them where they want.

A

They can also pin widgets so that they always show up when they open up the widgets board so about the third party widgets platform. Third party Wizards platform has been something our team has been working on for the past year, and the goal of this is to enable third-party developers to include widgets in the windows 11 widgets board. Previously this widgets board only allowed first party apps to have widgets shown, but now, with this preview release, we've enabled third-party widgets in the widgets board.

A

These widgets are powered by adaptive cards and the preview is available in the windows: app SDK 1.2 preview, 2. for those unfamiliar with the windows app SDK. This is just a software development kit that allows users to create native Windows apps, and we have all the documentation available. You can find documentation for widgets in this link. Ak dot, Ms, slash, widget, docs and later on in the presentation, we'll share another link for developer specific documentation.

A

Now, since this is a preview release, there are some prerequisites that need to be met. Keep in mind that this information is specific to this preview release. So if you are referencing this recording later on, it's possible that there's newer prerequisites or there's a newer version of the widgets platform out to get the latest information about the prerequisites that need to be met and, just in general, what capabilities are supported by the platform.

A

You can find all this info in AK dot, Ms, slash, widget, Dev docs, so this link will provide all the developer documentation needed to get started with widgets. The prerequisites right now for this preview release are a packaged, win32 app. We will have support for Progressive web apps coming later this year, also known as pwas.

A

You also need to be running on the latest Dev Channel, build of the windows. Insider preview, developer mode also needs to be turned on, and your app must reference. The Windows app SDK 1.2 preview to and as I mentioned before, steps to meet all these prerequisites how to get the latest Dev Channel build how to turn on developer mode for your device, how to reference the Windows app SDK in your app all this can be found in ak.ms, slash, widget, Dev Docs, for the steps on how to create a win32 widget.

A

It falls down to three high level steps, so the first step is to design your widget as I mentioned previously. Widgets are powered by adaptive cards, so the UI for your widget is actually an Adaptive card. The second step is implementing the iwidget provider interface and what the eye widget provider interface is is the way your app can communicate with the widgets board. It defines the methods for these communication channels and what your app should do for each of these methods and then the final step is registering your widget with the system.

A

So when you register your widget with the system, this allows your widget to be shown on the widgets board, as I mentioned, documentation available at AK dot, Ms, slash, widget, Dev docs. For this.

A

This image shows just how the three steps uh come into play. So, as you can see on the right side, we have this weather app. The first step, as I mentioned, was creating the UI for your widget using adaptive cards. So we can see right here.

A

This is the the UI we created for for our widget using adaptive cards and then, in order for your app to communicate with the widgets board, you need to implement the eye widget provider interface, which will consist of these six methods right here, create widget will be called whenever the user pins, the widget to the widgets board, delete widget happens when the user unpins the widget on action invoked handles any action.execute on the widget and then on widget context.

A

Changed is called when the user changes the size, so the widget board supports three sizes, small, medium and large, and you can have a different widget shown for for each size and I'll. Show you how to do that as part of the demo and and then activate and deactivate. These are called when the widgets board is requesting an update or when it's saying that it's not interested in an update and we'll get to more specifics in in the demo.

A

For this as well, and then for the final step, you have to register your widget by making some changes to the Apex manifest now, let's get started with the demo here. So, as I mentioned, the first step is actually creating your adaptive card for your widget UI. For this demo, I created this very simple, counting widget. If you open up our designer on adaptivecards.io designer you'll, see that we have added support for a new host app, this is called the widgets board.

A

Once you're in the widgets board host app, you can change things like the theme or the container size. Remember that the widgets board supports small, medium and large in this adaptive card that I wrote, We just have a simple counting widget, which has an action.execute on this increment button, and this action.execute will communicate with our app in order to increment this counting variable that you see right here.

A

These three text blocks were added to showcase the functionality of this host property that you see right here, so this one conditional will come into play and it'll basically say if this condition is not met, do not show this text block and what it's referencing for the condition is host.widget.size. We have that information here in our documentation.

A

This is the link for AKA dot, Ms, slash, widget, Dev docs, and you can find it in Implement, a widget provider in a win32 app, but this host.widget size checks the size of the widget and then with this one, conditional it'll show the text block if it meets the size.

A

So we can quickly test that right here we see that we are in large and if everything is working correctly, we should only see this rendering only if large, so we click preview mode and we see it working if we go ahead and change the widget size to medium and then hit preview mode again, we can see that only the medium text block is is being rendered here.

A

So this is the UI for the widget we will be using. um It's also included in the developer documentation that I mentioned. This is for the weather, widget, which is an example of another widget, and then this is the counting widget that I'm showing right here.

A

Another thing to note is that, as part of the widgets platform, there has been a new field called verb that is linked to an action, so in the code for your app when, when you're handling the action invoked method for for the widget, this verb is what will tie to the specific action. So in case you had two buttons. For example, you could assign a different verb to each action to handle different behaviors with your app.

A

So this takes care of the first step for creating your widget remember. There are three steps. The first one is designing your adaptive card. The second is implementing your iwidget provider in your app and then the last one is registering your widget with the system for the second and third steps. I would highly recommend you to go over into our documentation to see all the information that's needed. If you're looking for information on how to get the latest Windows Insider preview build, you can find that information here.

A

We outline all the prerequisites that you need for this preview release the visual studio versions, which workloads you need within visual studio and things like how to enable developer mode for your device.

A

I am not a Windows developer myself, so, but what I am good at is following instructions. So I wrote these instructions for people to be able to follow, even if they aren't Windows developers, so don't feel intimidated if you've never created a Windows app before this documentation should help you and guide you, and if you are already familiar with creating apps in Windows, then you'll already get a head start with building widgets, especially if you've used the Windows app SDK previously just going through this documentation.

A

We're going to check this example project that I've built here, and this is the project that will or if you follow the documentation. You should end up with a very similar project as the one that we have here. We can see, for example, that one of the first steps is, after you create your new win32 app using visual studio. You will add some references we can check. We have those references by right clicking on our project here, manage new, get packages and checking the installed ones.

A

So we see we have the windows, implementation Library, which is one of the requirements, and we also have the windows widgets nougat and in your case this Windows widgets nougat, should say the Windows app SDK 1.2 preview too, then, once that is done in this pch.h file, we go ahead and include these lines. All these steps show you exactly what needs to be changed to what needs to be added into your project in order to get a widgets working.

A

Now. Here's where we get into details about the iwidget provider interface that I mentioned before so remember this I widget provider interface. It's the second out of the third steps to actually get your widget working and it's what handles the communication between the widgets board and your app. The widgets board is also known as the widget host and your app is known as the widget provider. So here we Show an example: implementation of this widgets provider and just to double check that we've done everything correctly. We can check in our widget provider.h file.

A

We also guide you to how to create this file in this first step right here, but if we check our widget provider.h file right here, we can see that we've declared the six methods that I mentioned before. So these are create widget, delete, widget on action, invoked on widget context, changed, activate and deactivate.

A

We can also see that we have our Json for the counting widget that I showed in the first step right here, following along with the documentation, we show the steps that are required to just be able to track the widgets on the widgets board and also um being able to reference specific widgets.

A

We have the Json string that I I showed here as part of the widget UI.

A

um If you're familiar with using adaptive cards, you can create other types of widgets, such as the weather, widget that was shown previously or on the widgets board, or just anything that works with your app really. What a third-party widget is is another entry point into your app anything that your app has access to. The widget will also have access to and it'll provide users with a way to access your app without actually needing to be inside the app and right from the Wizards board.

A

So here we see the step for the actual Json string that that we included in this sample that we have on the documentation. We have a weather, widget template and we also have the counting widget template as part of this demo. I will only be showing the counting widget.

A

The next step is to implement the iwidget provider methods. These are the six methods that will communicate the provider or your app with the widget host or the widgets board.

A

We can see example, implementations for these methods for create and delete on action, invoked on widget context, changed and activate the activate, we'll quickly, navigate into our project and check our widget provider.cpp file. And we see that we have exactly the same code that we had in the documentation right here, and this is what we will be using as part of the demo.

A

Continually on you can see that there's another method update widget. So what this method will do is handle things like actions on the widget, so anytime, your user does something like click on the increment button. For example right here, the widget UI needs to be updated in some way. In our case, what will be updated is Discount variable anytime, the user clicks on the increment button. Our app has logic to increment discount variable by one, and we can double check that by navigating here.

A

So we see that we're incrementing this this value of the count variable by the previous value that was stored in in the state for the widget. We call update options.template to update the template for the widget. In case there was a template change. uh What the template refers to is just the UI. It's this section right here, the card payload and then the data is the data payload that you see right here and once this update method is called the final thing. It'll do it'll actually send these update parameters to the widget board.

A

We head back to documentation, and this step shows you how to actually make the Constructor for your widget, which will initialize the list of enabled widgets.

A

This means that when the widget board is open and you have the widgets showing up the widgets that relate to your app will get initialized in this way and you can track it with these properties.

A

And follow through here we show you how to implement the main method as well for your widget. This is all boilerplate code and you can copy it right. As you see it here, one important step to actually registering your widget that we will use later is creating this guid. So the the system uses this guid to register your widget, and this is required for the widget to show up on the widgets board. If we go into our code, I can show you how to do that real quickly inside our main.cpp method.

A

We see- we've already created one right here, but I'll go ahead and create another one. You can do this by simply going to Tools in visual studio and then hitting create guid.

A

um You choose this third option and you hit copy. Then you can just paste it right there and the value that's important to us. Is this set of numbers right here. So we've already done that, so we can delete this and in order to check that we're using it correctly. If we follow the documentation here, we go ahead and package, our widget provider.

A

The steps are shown right here for how to go ahead and do that and inside our Apex manifest, so this Apex manifest is generated for you once you go ahead and do the step for packaging, your app. If you right click on it and hit view code, you can see this XML that relates to to your app.

A

You need to make some changes for this to work and if you want to see the XML format that widget supports you can head over to widget provider, manifest XML format and it'll show you the element hierarchy, things like what properties are required, um what this property is what's utilized and- and things like that, so for this one, since we created the guid, we have to make these changes first, so we first have to reference the Windows app SDK. We also need to add this dependencies field. We can double check.

A

We've done that here we have the dependencies field right here and then we continue on into the XML, that's specific to the widget provider. So head back to documentation- and we can see that right here we have this com class ID. This ID right here is the same guid that we created in our project just to make sure that we have it correctly. We can see that we have this class ID and it's the same string of numbers that was created in our main.cpp file.

A

It needs to be present in two different spots in this first com class ID, and also in this create instance, class ID. Both of these places need to have the same guid in order for the registration step to work properly.

A

All these changes that we're making inside the Apex manifest are part of the last step for registering your widget. So after we go ahead and make all these changes, our widget will be able to register with the system and then show up on the widgets board. We can continue on here and I'll just provide some brief details on the other properties that were added as I mentioned. Following this guide and all the steps included will get you to the the sample that I'm showing as part of this demo.

A

So everything here has been made easy for even people that are not familiar with Windows development. um We can see that as part of the widget provider manifest we've added this definitions tag. We include things like the title for our widget. We include the different capabilities that are supported, so in this case the weather, widget. That's provided as part of this tutorial. It's it supports small, medium and large, and that doesn't have to be the case for your widget.

A

If you only want to support small, for example, you can only declare the small capability, as it's shown right here in our demo. Our accounting widget will support all three sizes. Then you also need to include the theme resources. These are the icons and the screenshots that your widget will be using right now in this preview. Release screenshots are required, but they aren't shown inside the Wizards board just yet.

A

This will come as part of a a future release later this year, but the reason I'm noting this is because these two properties, screenshots and icons, are both required properties, so you aren't able to Omit them like, for example, the capability for medium and and large. Like you see right here, you need to include these icons and screenshots as part of your project. If we see right here, we can see that we've included the icon with the appropriate path right here.

A

It's found in our provider assets folder, which is right here, and we have the screenshots for the counting widget and some weather screenshots as well, but those aren't used as part of this demo, and then we also have support for for dark mode and light mode. This is for specifying different icons in case you would use a different icon or a different screenshot, depending on if the user has dark mode enabled or light mode enabled.

A

These are all part of the widget provider object inside the the provider manifest file, and if you follow this tutorial, you'll be able to find the code looks very very similar to this, and the widget will be able to register it all. The steps are followed correctly.

A

So after you followed the all the three steps, the first step was designing. The widget UI using adaptive cards, the Second Step, was implementing all the methods for the widget provider in the widget provider.cpp, and also declaring those methods in this header file, and then the last step was packaging up your app and registering the widget through the Apex manifest. So we made these changes in the XML to go ahead and register our widget with the system. The final step is actually deploying your app.

A

So if I go over and hover the example widget provider package I hit, deploy after it's finished, deploying I should be able to pin unpin, drag and drop and interact with my widget.

A

Okay, we see that the deployment succeeded we can head over to our widgets board either by coming to this bottom left corner or hitting the windows plus W shortcut, and you can see our counting widget is being shown on the widgets board. Initially, you won't see the widget right here. You'll actually have to go into the widget picker found in the top right corner and pin your widget by clicking on on this section right here since I recorded this demo and made the video it was already showing for me after I deployed the the provider.

A

But what we can see is that if we change it to medium, for example, it'll respond in the same way, we have the host app set up in the Adaptive cards, only showing the text block. If it's a medium size, we change it back to large.

A

We can see that the text block has changed to only be rendered if it's in large size- and we see this count variable that previously in the designer you weren't able to increment or make any changes on, but here on the widgets board, since we've gone ahead and set our verb here here, for example, we see the the logic for this to work. We see that on action invoke remember this is called anytime. An action is taken on a widget if the action has the verb ink, which is what we included right here.

A

Our action has the verb. Ink, if that has that specific verb do this logic and what it's doing right here is incrementing this counting variable by one and then cutting the update widget with the updated counting variable. We can test that real, quick right here, I hit increment.

A

And, of course, because this is a live demo, this is not working, um but we can show the video for that. So if we go right here.

A

We can see that I was clicking on the increment button and the value was changing and this state is preserved. So if I close the widget board and reopen it, I can also increment the the counting variable. Let me just try once more to see if this works.

A

Something's going on but I that that's just part of the live demos uh we had the recording just in case for for issues like this and that's basically it so as as a reminder. This is a preview release, so there might be some some changes in the future as we make changes to to this platform in this preview, release developers can only test widgets locally on their machines.

A

By meeting the prerequisites I called out earlier, you can find all the prerequisites, all the information you need to get started in AK, dot, Ms, slash, widget, Dev, Docs and in a future release users that install apps that support widgets through the Microsoft store will also be able to see the widgets you create on their device, and this will come later on in in the year.

A

That's it for this demo and I'm sure people have some questions here, so we can go ahead and get started with the Q.

A

A section I haven't been looking at the chat, so I will go ahead and catch up with the chat here, but feel free to unmute and ask any questions you have during this time as well and Joseph is asking here in the chat just for the people on the recording that can't see this question he's asking: if do these widgets beside the fact that they use adaptive cards, have any relevance to the Microsoft Power Platform? These can only reference. Windows applications am I right, and that is correct. They can.

A

They can only be referenced through a window. A packaged, win32 app right now as part of the preview release and then support for pwas or Progressive web apps will be coming later on in the year. Stanford is asking which version of Visual Studio? Are you using uh the version I I was using is Visual Studio 2022, any version, that's 2017 or later should work, and we also have that gear in our developer. Documentation it's in the it's actually right here, so at the very top.

A

In the prerequisites section, we say that Visual Studio, 2017 or later will work for this as well. Are you able to use Visual Studio to debug the widget, not right now, so this is something that we're improving and will be part of a future release of the platform. But for this preview release there, you aren't able to do things like hot reload and and make the change to the widget.

A

You will have to make the change in the code and then update the widget in in that way by actually redeploying the the app package we're looking to improve this experience, though, as part of a future release.

A

If you go ahead and try out the tutorial and you find that you're stuck in in a section or as part of a step, we are collecting both feedback and also helping developers in the windows app SDK GitHub repo. So you can file an issue there for any issues that you're encountering or provide any feedback on the widgets platform in the windows. App SDK repo as well Brad is asking what's the ETA for version 1.6.

A

We don't have an ETA just yet, but now that we've gone ahead and shipped this platform, our team is working on version 1.6 and the the what's left for version 1.6 is parity across the different platforms.

A

So, right now the changes we have on 1.6 are made for our JavaScript render and we're looking to make those changes into our Android SDK, our iOS SDK and all the different platforms we support in order to actually be able to release version 1.6 we're hoping for for this to come either later this year or early in the upcoming year. Get everything is great, then. Would it be a chance of another one showing the new adaptive card building capabilities in powerapps Gareth? You elaborate a little more on the question.

A

I, don't think I understand that while Gareth expands on this question, um Andrea is asking: is there a community or forum for adaptive cards? That's a great question on the forum for adaptive cards is actually the Microsoft adaptive cards repo, so you can go into github.com Microsoft adaptive cards. This is our open source repository. This is where our code lives and, in our issues, tab right here. This is where developers running into issues or just any adaptive card user that has feedback or is running into any issues.

A

They can open up a new issue and ask there our team will get back to you in in this forum.

A

So Gareth is saying you can now build adaptive cards and power. Apps a demo would be awesome, Gareth, that's excellent feedback. What we can do is reach out to the Power Platform team and and see if they would be interested in joining us for the next Community call in November and sharing a a demo on this I I think this is also very interesting and I wasn't aware that this was out already, but I can work with their team to get a demo for our next Community call.

A

Thank you. Thank you for sharing that that's super interesting Andre is saying. I just got started with adaptive cards and I faced many issues. The Forum is a lifesaver for the future. Yes, um anything any questions you have on adaptive cards. Any issues you're running into this is the perfect place to to have them.

A

um We have it this way so that if other people are facing similar issues in the future, they can reference it here, and it also allows for a full transparency with our team and other things we're addressing such as the bugs we have um which bugs we're working on and allows for people to reference it in case they they run into the same issues in the future and that's that's again. That's found in our Microsoft adaptive cards, repo github.com Microsoft, slash adaptive cards, I'm curious if you'll be trying out widgets with this preview release.

A

If you are interested in in self-hosting and and testing out, developing widgets in this pre-release go ahead and and leave something in the chat and let us know- and if you have any questions, I've also left my email in the chat for for you to ask, or you can go ahead and ask those questions in the windows. App SDK Repository here says: I think that once more of us are on Windows 11 with corporate computers, these widgets will be super useful.

A

That's that's exactly correct and that's also what we're trying to achieve is allow users that have Windows 11 to to get a personalized experience with these widgets. We want these third-party widgets to be part of the the flow that the user takes to allow to do things like quick tasks and and view the content that they care about without the context loss that comes with it as Windows 11 is adopted, more I think people will start seeing the widgets even more than what they are seeing now. That's that's a great limitation, though.

A

um What what you listed there for the windows 11 on corporate devices? Yes, then that is something that once more developers are or have access to, Windows 11 they'll be able to see the widgets there because they they aren't available on Windows 10.. If your win32 app is working for Windows, 10 it'll also support widgets, given you make all the changes that I I called out in this demo. It'll support widgets on Windows 11.

A

But if you, if you, the user, is running the widget on Windows 10 machine, they won't be able to see the widget Stanford is saying I'm interested in trying it, but I'm hesitant in writing a Windows app and what I have to say with to that is. I was also very hesitant on that um I'm, not a Windows developer, myself, I'm I'm, still very new to to things with Windows development. So that's why?

A

When I was trying to create this documentation, this how-to of creating this, this widget I try to write everything in a way that allows even new users to to be able to follow these steps and end up with with a widget Andre I'll go ahead and send the links in the chat as well right after the presentation of this work and yes, the meeting is recorded, the recording will be available on YouTube as well and you'll be able to see all the slides that were shared previously as part of the recording.

A

So don't worry about that. I will also be sharing the links in the chat for people that are interested in having them there alrighty. If there are no more questions and continue on with our presentation, we just have two more slides to share. One of them. Is our resources slide? Anything with new features you need? You can go into AK dot, Ms, slash, AC roadmap. If you want to learn about templating templating is the an example of templating?

A

Is the property when that was showed as part of the demo, you can find information to add in ak.ms AC templating, all the Adaptive cards code, the repository on GitHub that issues tab is also accessible via aka.ms, slash, AC, repo and made withcards.io is a website that contains tools, samples and other adaptive cards and makes it really easy for people to just get started with adaptive cards.

A

If you're interested in our other Microsoft 365 developer, Community calls you can find those here. I will be sharing these slides in the chat as well, if you're viewing, as as part of the record demo, just go ahead and use the links shown in this slide. If you want to participate in the community cause for these other areas and that's everything I had to share today, folks, um as always feel free to reach out on on Twitter or with my Alias. If you have any any questions that you would like to ask, thank you.