Overlays are now Widgets

Overlays vs. Widgets

In [4.1.2003.11001.0] or later the terms "UI Extension" and "Overlay" were largely removed from the API to clarify naming between developer and users experiences. In most places "UI Extensions" and "Overlays" are simply referred to as "Widgets."

Note: Due to pre-existing work done in Windows that cannot be easily changed, the App Extension Name in your app manifest must remain "microsoft.gameBarUIExtension". Details on terms that persist are below.

Game Bar SDK Class Changes

The following class have changed in name. A simple search and replace of each is sufficient to update them.

Old	New
XboxGameBarUIExtension	XboxGameBarWidget
XboxGameBarUIExtensionActivatedEventArgs	XboxGameBarWidgetActivatedEventArgs
XboxGameBarUIExtensionControl	XboxGameBarWidgetControl
XboxGameBarUIExtensionWindowState	XboxGameBarWidgetWindowState

See Xbox Game Bar Widget API Overview for more information.

App Manifest Changes

Your app extension properties should define a <GameBarWidget> instead of a <GameBarUIExtension>".

<uap3:AppExtension Name="microsoft.gameBarUIExtension" ...>
    <uap3:Properties>
    <!-- <GameBarUIExtension> is no longer valid -->
        <GameBarWidget Type="...">
        ...
        </GameBarWidget>
    ...
    </uap3:Properties>
</uap3:AppExtension>

See changes to your project for more information.

Add Proxy/Stub Registration

You should update your application manifest to include the latest naming, as well as add the new line with IXboxGameBarWidgetAuthHost.

  <Extensions>
    ...
        <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.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.IXboxGameBarWidgetPrivate" InterfaceId="22ABA97F-FB0F-4439-9BDD-2C67B2D5AA8F" />
    ...
  </Extensions>

See add proxy stub registration for more information.

App Activation

The value of the activation protocol string has changed from "ms-gamebaruiextension" to "ms-gamebaruiwidget".

C#

protected override void OnActivated(IActivatedEventArgs args)
{
    XboxGameBarWidgetActivatedEventArgs widgetArgs = null;
    if (args.Kind == ActivationKind.Protocol)
    {
        var protocolArgs = args as IProtocolActivatedEventArgs;
        string protocolString = protocolArgs.Uri.AbsoluteUri;
        // replace "ms-gamebaruiextension" with "ms-gamebarwidget"
        // if (protocolString.StartsWith("ms-gamebaruiextension"))
        if (protocolString.StartsWith("ms-gamebarwidget"))
        { ... }
    }
    ...
}

C++

void App::OnActivated(IActivatedEventArgs const& e)
{
    XboxGameBarWidgetActivatedEventArgs widgetArgs{ nullptr };
    if (e.Kind() == ActivationKind::Protocol)
    {
        auto protocolArgs = e.try_as<IProtocolActivatedEventArgs>();
        if (protocolArgs)
        {
            const wchar_t* scheme = protocolArgs.Uri().SchemeName().c_str();
            // replace "ms-gamebaruiextension" with "ms-gamebarwidget"
            // if (0 != wcsstr(scheme, L"ms-gamebaruiextension"))
            if (0 != wcsstr(scheme, L"ms-gamebarwidget"))
            { ... }
        }
    }
    ...
}

Terms that persist

Although "UI Extension" and "Overlay" terms were removed, the term App Extension still exists. Game Bar widgets build on top of the Windows App Extension feature. Game Bar widgets are Windows UWP App Extensions.

App Manifest

In your application manifest the uap3:AppExtension is still defined as "microsoft.gameBarUIExtension".

    <uap3:Extension Category="windows.appExtension">
        <uap3:AppExtension Name="microsoft.gameBarUIExtension"
                           Id="WidgetSettings"
                           ...
                           >

See app activation for more detail.

Method Parameters

As defined in your app manifest, the Id is still referred to as the "App Extension Id" of your widget. This is apparent in XboxGameBarWidgetActivatedEventArgs.AppExtensionId, XboxGameBar.AppExtensionId, and throughout XboxGameBarWidgetControl. Just as before, the full identity of your widget is called "widget Id" (formerly "extension Id"), and is made up of your App Package Family Name, App Identity, and App Extension Id. See XboxGameBarWidgetControl.