Changes to your project
The first step is defining the one or more widgets your app will support in your app manifest. Visual Studio's app manifest editor doesn't support editing these options, so you'll edit the app manifest XML in the XML editor.
Open your Package.appxmanifest
:
- Right click
Package.appxmanifest
- Select "Open With..."
- Select XML Text Editor
Add the following highlighted namespace definition at the top of your manifest if it isn't already there:
xmlns:uap3="http://schemas.microsoft.com/appx/manifest/uap/windows10/3"
IgnorableNamespaces="uap3"
The resulting markup typically looks like this:
<?xml version="1.0" encoding="utf-8"?>
<Package xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
xmlns:mp="http://schemas.microsoft.com/appx/2014/phone/manifest"
xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
xmlns:uap3="http://schemas.microsoft.com/appx/manifest/uap/windows10/3"
IgnorableNamespaces="uap uap3 mp">
Under your <Application>
element find if you already have an <Extensions>
element.
If you don't have an <Extensions>
element, create one and add the below XML.
Name
is the Widget contract with Game Bar and must be listed exactly as shown below.
Id
is how your app and Game Bar can differentiate multiple widgets exposed by your app. If you're only providing a single widget, that's fine, but you still need to provide an Id. Id
max length is 39 chars.
DisplayName
is the name we'll use to list your widget in Game Bar.
Description
is used to briefly describe the widget. Currently Game Bar does not expose this attribute.
PublicFolder
is a folder in your app package that Game Bar has access to. Today, this is only used for icons, but this may be used for additional resources or configuration files that Game Bar SDK leverages in the future.
<Application ...>
...
<Extensions>
<uap3:Extension Category="windows.appExtension">
<uap3:AppExtension Name="microsoft.gameBarUIExtension"
Id="YourUniqueIdHere"
DisplayName="Display name for your widget"
Description="Description for your widget"
PublicFolder="GameBar">
</uap3:AppExtension>
</uap3:Extension>
</Extensions>
</Application>
See uap3:AppExtension (Windows) for more information, including expected format.
Now add static configuration for your widget using App Extension
properties.
GameBarWidget
element is required as the root element under the required uap3:Properties
element. The Type
attribute on the GameBarWidget
element is required to specify the type of widget you're defining. Type
can be Standard
or Settings
.
...
<uap3:AppExtension Name="microsoft.gameBarUIExtension"
Id="YourUniqueIdHere"
DisplayName="Display name for your widget"
Description="Description for your widget"
PublicFolder="GameBar">
<uap3:Properties>
<GameBarWidget Type="Standard">
</GameBarWidget>
</uap3:Properties>
</uap3:AppExtension>
Window
Size
has you specify the initial, Min
, and Max
window size for your widget. Note: Min
and Max
can be programmatically changed by your widget at runtime. Specifying your initial size is very important as Game Bar needs to know the view chrome size required before it attempts to load your widget. See example below.
You can also set AllowForegroundTransparency
to true
to allow your widget to control transparency while Game Bar is in Foreground
mode. Without this, your transparency setting will only apply while Game Bar is in PinnedOnly
mode.
HomeMenuVisible
specifies whether you want your widget visible in the Game Bar home menu. You would only specify false here if you were creating a widget that was a secondary window to another primary widget (i.e. the user clicks a button on one of your widgets and you want to load another widget).
PinningSupported
specifies whether you allow your widget to be pinned on the screen, even when Game Bar is dismissed. This supports scenarios where gamers may want to keep your window visible while actively playing their game.
SettingsSupported
specifies whether your widget has a companion widget for settings, and causes the settings button to show on your widget's title bar. AppExtensionId
attribute must be set to the Id
of your settings widget. If you haven't already, create of type Settings
with matching Id
in your manifest. At runtime, when the user clicks the settings button, the SettingsClicked
event will be raised on the XboxGameBarWidget
object.
ActivateAfterInstall
specifies whether this widget should show after the application is first installed. Note: We recommend setting this to true for your primary widget, and false for secondary widgets (if applicable). From the users perspective opening Game Bar to a wall of newly installed widgets could be a bad experience.
FavoriteAfterInstall
specifies whether this widget should be marked as favorite (and always appear in the Home Bar) after the application is first installed. Note: We recommend setting this to true for your primary widget, and false for secondary widgets (if applicable). From the users perspective opening Game Bar to many newly marked as favorite widgets could be a bad experience.
ResizeSupported
specifies whether your widget supports vertical and/or horizontal resize by the user. Note: this doesn't prevent you from programmatically asking Game Bar to change your window size.
<Application ...>
...
<Extensions>
<uap3:Extension Category="windows.appExtension">
<uap3:AppExtension Name="microsoft.gameBarUIExtension"
Id="YourUniqueIdHere"
DisplayName="Display name for your widget"
Description="Description for your widget"
PublicFolder="GameBar\Ext1">
<uap3:Properties>
<GameBarWidget Type="Standard">
<HomeMenuVisible>true</HomeMenuVisible>
<PinningSupported>true</PinningSupported>
<SettingsSupported AppExtensionId="YourSettingsExtensionId" />
<Window>
<AllowForegroundTransparency>true</AllowForegroundTransparency>
<Size>
<Height>300</Height>
<Width>400</Width>
<MinHeight>150</MinHeight>
<MinWidth>200</MinWidth>
<MaxHeight>350</MaxHeight>
<MaxWidth>450</MaxWidth>
</Size>
<ResizeSupported>
<Horizontal>true</Horizontal>
<Vertical>true</Vertical>
</ResizeSupported>
</Window>
</GameBarWidget>
</uap3:Properties>
</uap3:AppExtension>
<uap3:AppExtension Name="microsoft.gameBarUIExtension"
Id="YourSettingsExtensionId"
DisplayName="Display name for your widget"
Description="Description for your widget"
PublicFolder="GameBar\Ext1">
<uap3:Properties>
<GameBarWidget Type="Settings">
<Window>
<Size>
<Height>300</Height>
<Width>300</Width>
</Size>
<ResizeSupported>
<Horizontal>false</Horizontal>
<Vertical>false</Vertical>
</ResizeSupported>
</Window>
</GameBarWidget>
</uap3:Properties>
</uap3:AppExtension>
</uap3:Extension>
</Extensions>
</Application>
If your application is only intended to be used as a widget you may wish to remove the start menu entry so that it cannot be launched directly outside of Game Bar. To do so modify your Application
VisualElements
to include AppListEntry="none"
<Application ...>
<uap:VisualElements
...
AppListEntry="none">
...
</Application>
See uap:VisualElements (Windows) for more information.
Add proxy/stub registrations for interoperability between your app and Game Bar. Note: We're working on getting the NuGet package to automatically take care of this step for you during AppX manifest generation, but that will come in a future SDK release.
Add the following <Extensions>
section outside and after your <Applications>
element. i.e. This is different than your <Extensions>
element inside your <Application>
element.
<Extensions>
<!-- Enlighten COM on where to find Metadata Based Marshaling (MBM) data for the Game Bar private types
<Path> is a required element (by VS) and has to point to a binary in the package, but it's not used when the class id is 00000355-0000-0000-C000-000000000046 (MBM). Due to that we just put the Microsoft.Gaming.XboxGameBar.winmd here. -->
<Extension Category="windows.activatableClass.proxyStub">
<ProxyStub ClassId="00000355-0000-0000-C000-000000000046">
<Path>Microsoft.Gaming.XboxGameBar.winmd</Path>
<Interface Name="Microsoft.Gaming.XboxGameBar.Private.IXboxGameBarAppTargetHost" InterfaceId="38CDC43C-0A0E-4B3B-BBD3-A581AE220D53" />
<Interface Name="Microsoft.Gaming.XboxGameBar.Private.IXboxGameBarAppTargetInfo" InterfaceId="D7689E93-5587-47D1-A42E-78D16B2FA807" />
<Interface Name="Microsoft.Gaming.XboxGameBar.Private.IXboxGameBarActivityHost" InterfaceId="2B113C9B-E370-49B2-A20B-83E0F5737577" />
<Interface Name="Microsoft.Gaming.XboxGameBar.Private.IXboxGameBarHotkeyManagerHost" InterfaceId="F6225A53-B34C-4833-9511-AA377B43316F" />
<Interface Name="Microsoft.Gaming.XboxGameBar.Private.IXboxGameBarWidgetAuthHost" InterfaceId="DC263529-B12F-469E-BB35-B94069F5B15A" />
<Interface Name="Microsoft.Gaming.XboxGameBar.Private.IXboxGameBarWidgetControlHost" InterfaceId="C309CAC7-8435-4082-8F37-784523747047" />
<Interface Name="Microsoft.Gaming.XboxGameBar.Private.IXboxGameBarWidgetForegroundWorkerHost" InterfaceId="DDB52B57-FA83-420C-AFDE-6FA556E18B83" />
<Interface Name="Microsoft.Gaming.XboxGameBar.Private.IXboxGameBarWidgetForegroundWorkerPrivate" InterfaceId="42BACDFC-BB28-4E71-99B4-24C034C7B7E0" />
<Interface Name="Microsoft.Gaming.XboxGameBar.Private.IXboxGameBarNavigationKeyCombo" InterfaceId="5EEA3DBF-09BB-42A5-B491-CF561E33C172" />
<Interface Name="Microsoft.Gaming.XboxGameBar.Private.IXboxGameBarWidgetActivatedEventArgsPrivate" InterfaceId="782535A7-9407-4572-BFCB-316B4086F102" />
<Interface Name="Microsoft.Gaming.XboxGameBar.Private.IXboxGameBarWidgetHost" InterfaceId="5D12BC93-212B-4B9F-9091-76B73BF56525" />
<Interface Name="Microsoft.Gaming.XboxGameBar.Private.IXboxGameBarWidgetHost2" InterfaceId="28717C8B-D8E8-47A8-AF47-A1D5263BAE9B" />
<Interface Name="Microsoft.Gaming.XboxGameBar.Private.IXboxGameBarWidgetHost3" InterfaceId="3F5A3F12-C1E4-4942-B80D-3117BC948E29" />
<Interface Name="Microsoft.Gaming.XboxGameBar.Private.IXboxGameBarWidgetHost4" InterfaceId="FA696D9E-2501-4B01-B26F-4BB85344740F" />
<Interface Name="Microsoft.Gaming.XboxGameBar.Private.IXboxGameBarWidgetHost5" InterfaceId="A6C878CC-2B08-4B94-B1C3-222C6A913F3C" />
<Interface Name="Microsoft.Gaming.XboxGameBar.Private.IXboxGameBarWidgetHost6" InterfaceId="CE6F0D73-C44F-4BBD-9652-A0FC52C37A34" />
<Interface Name="Microsoft.Gaming.XboxGameBar.Private.IXboxGameBarWidgetNotificationHost" InterfaceId="6F68D392-E4A9-46F7-A024-5275BC2FE7BA" />
<Interface Name="Microsoft.Gaming.XboxGameBar.Private.IXboxGameBarWidgetNotificationPrivate" InterfaceId="C94C8DC8-C8B5-4560-AF6E-A588B558213A" />
<Interface Name="Microsoft.Gaming.XboxGameBar.Private.IXboxGameBarWidgetPrivate" InterfaceId="22ABA97F-FB0F-4439-9BDD-2C67B2D5AA8F" />
<Interface Name="Microsoft.Gaming.XboxGameBar.Private.IXboxGameBarWidgetPrivate2" InterfaceId="B2F7DB8C-7540-48DA-9B46-4E60CE0D9DEB" />
<Interface Name="Microsoft.Gaming.XboxGameBar.Private.IXboxGameBarWidgetPrivate3" InterfaceId="4FB89FB6-7CB8-489D-8408-2269E6C733A1" />
<Interface Name="Microsoft.Gaming.XboxGameBar.Private.IXboxGameBarWidgetPrivate4" InterfaceId="5638D65A-3733-48CC-90E5-984688D62786" />
</ProxyStub>
</Extension>
</Extensions>