Microsoft 365 Community Adaptive Cards, 13 Oct 2022

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Building Windows 11 Widgets with Adaptive Cards

Description

In this 25-minute developer focused demo, J.P. Roca addresses what are widgets, 3rd party widget platform, development environment prerequisites and 3 steps for creating your Win32 Widget. Steps are 1) design widget (using Adaptive Cards), 2) implement IWidgetProvider interface (methods for handling communications between widgets board and your app), and 3) register widget (changes to APPX Manifest). Deploy your new widget. Widget development does not require a Windows developer, it does require Windows App SDK 1.2 Preview 2, target machines running Windows 11, and a review of referenced guidance. This demo is taken from the October 2022 Adaptive Cards community call recorded on October 13, 2022.

Demo Presenter
• J.P. Roca (Microsoft) | @jpthepm

Supporting materials
• Documentation - Widgets overview | aka.ms/widgetdocs
• Documentation - Widget providers | aka.ms/widgetdevdocs
• Documentation - Implement a widget provider in a win32 app | https://learn.microsoft.com/windows/apps/develop/widgets/implement-widget-provider-win32
• Repo - Implement a widget provider in a win32 app | https://github.com/MicrosoftDocs/windows-dev-docs/blob/docs/hub/apps/develop/widgets/implement-widget-provider-win32.md
• Repo – Windows App SDK 1.2 Preview 2 | https://github.com/microsoft/WindowsAppSDK/releases/tag/v1.2.0-preview2
• Tool – Adaptive Cards Designer | https://adaptivecards.io/designer/
• Documentation – Widget provider package manifest XML format | https://learn.microsoft.com/windows/apps/develop/widgets/widget-provider-manifest
• Feedback – Want to contribute to Microsoft Adaptive Cards? | https://github.com/microsoft/AdaptiveCards/issues

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 - http://aka.ms/m365/community

A

Foreign we're going to be talking about building windows, 11 widgets, with adaptive cards. 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 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 too, 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, 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 iwidget 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 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 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. 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. 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 of 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 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 with it. 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 account variable by the previous value that was stored in in the state for the widget. We call update options, dot template to update the template for the widget. In case there was a template change. 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 the documentation, and this step shows you how to actually make the Constructor for your widget, which will initialize the list of enabled widgets.

A

um 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. So 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 the 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 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 needing 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.