Changes to your project

  • Article

First Step

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.

Modify your Package Appx Manifest

Open your Package.appxmanifest:

  1. Right click Package.appxmanifest
  2. Select "Open With..."
  3. Select XML Text Editor

Update XML Schemas

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

Customize Extensions Element

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.

Attribute Definitions

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.

Update App Extension Properties

Now add static configuration for your widget using App Extension properties.

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

Optional Properties

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>

Remove Start Menu Entry

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 Registration

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>