diff --git a/windows-apps-src/apps-for-xbox/application-architecture.md b/windows-apps-src/apps-for-xbox/application-architecture.md new file mode 100644 index 0000000000..54849dab40 --- /dev/null +++ b/windows-apps-src/apps-for-xbox/application-architecture.md @@ -0,0 +1,80 @@ +--- +title: Xbox Media Application Architecture +description: Architure decisions you should consider while designing an Xbox media application +ms.date: 05/18/2022 +ms.topic: article +keywords: Xbox +ms.author: HiHaile +author: Hilina-H +--- +# Xbox Media Application Architecture +All Xbox apps are packaged using the [Universal Windows Platform](/windows/uwp/develop/) but this does not mean that all Xbox applications must be written in XAML and C#. This section will go through several high-level architectural decisions you will need to make before you can start writing your Xbox application. + +For general guidance on developing UWP applications for Xbox see this documentation: + +[UWP on Xbox One - UWP applications](/windows/uwp/xbox-apps/) +### App development models +In general, there are 2 recommended patterns for writing a media app for Xbox: +1. Using a website hosted in a WebView – You write a thin C# application which loads a website in a full-screen [WebView](/Windows.UI.Xaml.Controls.WebView?view=winrt-22000). Most of your app’s UI is written in web technologies like JavaScript and HTML, hosted on a server you manage. (Please note that WebView2 is not yet supported on Xbox.) +You might choose this option if: You are most comfortable working in web technologies, or you want to rapidly deploy changes to your UI without going through the app store publishing process. + +2. Using the native UWP API – Your app is built in XAML and C#, C++/Cx, or C++/WinRT, using [MediaElement](/windows/apps/design/controls/media-playback) and the [MediaPlayer API](/windows/uwp/audio-video-camera/play-audio-and-video-with-mediaplayer) to play content. +You might choose this option if: You are most comfortable working in C#, or you want better performance than you can achieve with web technologies alone. + + +### User model +Applications on Xbox can operate under one of two different user models: Single User Application (SUA) or Multi-user Application (MUA). +SUAs run in the context of a single Xbox user, storing app data on a user-by-user basis. When the user account being used on the Xbox changes, SUAs are relaunched and run in the new user’s context. + +MUAs are run in the context of a generic user account and are not relaunched when the current user account changes. The app data is shared among all users who log into the system. + +For more information, read the documentation here: +[Introduction to multi-user applications - UWP applications](/windows/uwp/xbox-apps/multi-user-applications) + +## Additional features +This section contains details on several additional features that you may want to consider using in your Xbox media application. +### Background audio +Your app can register to play audio in the background while other apps or games are running on the Xbox. + +The documentation on enabling your app to run in the background can be found here: +[Play media in the background - UWP applications](/windows/uwp/audio-video-camera/background-audio) + +You will also want to integrate with the System Media Transport Controls, which allow the user to manipulate playback in the Xbox Guide without having to re-launch your app: + +[Integrate with the System Media Transport Controls - UWP applications](/windows/uwp/audio-video-camera/integrate-with-systemmediatransportcontrols) + + +### WebView audio playback +If you are hosting your application in a WebView, you have two options when it comes to where you play the background audio: +1. You can play it using an HTML audio element within the WebView itself +2. You can use [WebView.AddWebAllowedObject](/windows.ui.xaml.controls.webview.addweballowedobject) to allow your JavaScript code to call into C#, and do the playback using the C# [MediaPlayer](/Windows.Media.Playback.MediaPlayer) API + +Approach #2 is strongly recommended because it allows your app to dispose the memory used by the WebView when it enters the background. This is much easier than trying to control your background memory usage without disposing of the WebView. + +### Light and dark mode +Users can select a preference for light and dark themes in the Xbox settings menu. Your app can check the user’s preference and render the app appropriately. For more information, see this documentation: + +[Application.RequestedTheme Property (Windows.UI.Xaml) - Windows UWP applications](/windows.ui.xaml.application.requestedtheme?view=winrt-22000) + +### DIAL protocol support (Google Assistant, etc) +The DIAL protocol allows secondary devices (like tablets and phones) to launch content on your Xbox and automatically pair with it. For more details, see this documentation: +[Windows.Media.DialProtocol Namespace - Windows UWP applications](/windows.media.dialprotocol?view=winrt-22000) + +### Media remote +If you plan to support media remote functionality and use the controls on the media remote to control media playback, you will need to integrate SMTC into your code. For more details, see this documentation. + +[SystemMediaTransportControls Class (Windows.Media) - Windows UWP applications | Microsoft Docs](/Windows.Media.SystemMediaTransportControls?view=winrt-22000) + +### Request ratings +There is an API you can call to request users to rate your application. This can help to bolster your ratings: + +[Request ratings and reviews for your app - UWP applications](/windows/uwp/monetize/request-ratings-and-reviews) + +### Globalization and localization +If you plan to ship your application in multiple languages or markets, this guidance may be helpful: + +[Globalization and localization - Windows apps](/windows/apps/design/globalizing/globalizing-portal) + +If you are building a native application in C++ or C#, you can use a resources file to make the localization process easier: + +[Localize strings in your UI and app package manifest - UWP applications](/windows/uwp/app-resources/localize-strings-ui-manifest) diff --git a/windows-apps-src/apps-for-xbox/development-opstions.md b/windows-apps-src/apps-for-xbox/development-opstions.md deleted file mode 100644 index 244b36b06f..0000000000 --- a/windows-apps-src/apps-for-xbox/development-opstions.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: Xbox Media App Development Options -description: This section describes possible architectures and development environments for building Xbox media applications -ms.date: 04/21/2022 -ms.topic: article -keywords: Xbox -ms.author: HiHaile -author: Hilina-H ---- -# Xbox Media App Development Options -### App development models -In general, there are 3 recommended patterns for writing a media app for Xbox: -1. Using a website hosted in a WebView – You write a thin C# application which loads a website in a full-screen [WebView](https://docs.microsoft.com/en-us/uwp/api/Windows.UI.Xaml.Controls.WebView?view=winrt-22000). Most of your app’s UI is written in web technologies like JavaScript and HTML, hosted on a server you manage. (Please note that WebView2 is not yet supported on Xbox.) -You might choose this option if: You are most comfortable working in web technologies, or you want to rapidly deploy changes to your UI without going through the app store publishing process. - -2. Using the native UWP API – Your app is built in XAML and C#, using [MediaElement](https://docs.microsoft.com/en-us/windows/apps/design/controls/media-playback) and the [MediaPlayer API](https://docs.microsoft.com/en-us/windows/uwp/audio-video-camera/play-audio-and-video-with-mediaplayer) to play content. -You might choose this option if: You are most comfortable working in C#, or you want better performance than you can achieve with web technologies alone. - -3. Using Media Foundation API – Your app is built in [C++/Cx](https://docs.microsoft.com/en-us/cpp/cppcx/visual-c-language-reference-c-cx?view=msvc-170) or [C++/WinRT](https://docs.microsoft.com/en-us/windows/uwp/cpp-and-winrt-apis/) using the lower-level [Microsoft Media Foundation API](https://docs.microsoft.com/en-us/windows/win32/medfound/microsoft-media-foundation-sdk)Through [DirectX](https://docs.microsoft.com/en-us/windows/win32/directx)you have full control over the rendering pipeline. This option requires the most effort. -You might choose this option if: You want peak performance and a high degree of customization around how your app presents media. -### Choosing the right version of Visual Studio - -The primary IDE used for Xbox app development is Visual Studio. You should familiarize yourself with the section in this document on App Development Models before deciding which version to install. - -If you are developing your UI using mostly web technologies hosted in a WebView, it is best to use Visual Studio 2017. It is the only version with comprehensive JavaScript debugging tools which work with the original WebView control. - -[Visual Studio Older Downloads](https://visualstudio.microsoft.com/vs/older-downloads/) - -If you are developing your UI primarily in XAML or using technologies like MediaFoundation and DirectX to build your UI from scratch, you can use any version from 2017 onwards. It is recommended that you use the latest release. - -[Download Visual Studio tools](https://visualstudio.microsoft.com/downloads/) - -NOTE: It can be tricky to fully downgrade your development environment after using a later version, so it’s recommended that you only install the version you need. - -### Installing the right components - -Once you’ve chosen a Visual Studio version, follow these instructions to get it set up: - -[Getting started with UWP app development on Xbox One - UWP application](https://docs.microsoft.com/en-us/windows/uwp/xbox-apps/getting-started) - -### Deploying your app to Xbox - -Follow these instructions to put your PC and Xbox into developer mode, and pair Visual Studio with your Xbox so that you can deploy your app to it: - -[Getting started with UWP app development on Xbox One - UWP application](https://docs.microsoft.com/en-us/windows/uwp/xbox-apps/getting-started) - -### Custom build automation - -If you want to use a different application as your main IDE, or if you want to build your own custom build tools, apps can be built using the command line: - -[Package from the command line - MSIX](https://docs.microsoft.com/en-us/windows/msix/package/manual-packaging-root) - -You can also use Azure Pipelines to set up automated builds for your application: - -[Set up automated build for your UWP app - UWP application](https://docs.microsoft.com/en-us/windows/uwp/packaging/auto-build-package-uwp-apps) - -### Manual side-loading - -If you want to side-load your application onto your Xbox manually, you will need to first generate a signed appxpackage either using the command line tools described under Custom build automation, or from Visual Studio: - -[Packaging MSIX apps - MSIX](https://docs.microsoft.com/en-us/windows/msix/package/packaging-uwp-apps) - -Then, you can use the Home tab of the Xbox Device Portal to side-load your app and its dependencies: - -[Device Portal for Xbox - UWP application](https://docs.microsoft.com/en-us/windows/uwp/xbox-apps/device-portal-xbox) - diff --git a/windows-apps-src/apps-for-xbox/development-options.md b/windows-apps-src/apps-for-xbox/development-options.md new file mode 100644 index 0000000000..93933b4781 --- /dev/null +++ b/windows-apps-src/apps-for-xbox/development-options.md @@ -0,0 +1,57 @@ +--- +title: Xbox Media App Development Options +description: This section describes possible architectures and development environments for building Xbox media applications +ms.date: 04/21/2022 +ms.topic: article +keywords: Xbox +ms.author: HiHaile +author: Hilina-H +--- +# Xbox Media App Development Options + +### Choosing the right version of Visual Studio + +The primary IDE used for Xbox app development is Visual Studio. You should familiarize yourself with the section in this document on App Development Models before deciding which version to install. + +If you are developing your UI using mostly web technologies hosted in a WebView, it is best to use Visual Studio 2017. It is the only version with comprehensive JavaScript debugging tools which work with the original WebView control. + +[Visual Studio Older Downloads](https://visualstudio.microsoft.com/vs/older-downloads/) + +If you are developing your UI primarily in XAML or using technologies like MediaFoundation and DirectX to build your UI from scratch, you can use any version from 2017 onwards. It is recommended that you use the latest release. + +[Download Visual Studio tools](https://visualstudio.microsoft.com/downloads/) + +NOTE: It can be tricky to fully downgrade your development environment after using a later version, so it’s recommended that you only install the version you need. + +### Installing the right components + +Once you’ve chosen a Visual Studio version, follow these instructions to get it set up: + +[Getting started with UWP app development on Xbox One - UWP application](/windows/uwp/xbox-apps/getting-started) + +### Deploying your app to Xbox + +Follow these instructions to put your PC and Xbox into developer mode, and pair Visual Studio with your Xbox so that you can deploy your app to it: + +[Getting started with UWP app development on Xbox One - UWP application](/windows/uwp/xbox-apps/getting-started) + +### Custom build automation + +If you want to use a different application as your main IDE, or if you want to build your own custom build tools, apps can be built using the command line: + +[Package from the command line - MSIX](/windows/msix/package/manual-packaging-root) + +You can also use Azure Pipelines to set up automated builds for your application: + +[Set up automated build for your UWP app - UWP application](/windows/uwp/packaging/auto-build-package-uwp-apps) + +### Manual side-loading + +If you want to side-load your application onto your Xbox manually, you will need to first generate a signed appxpackage either using the command line tools described under Custom build automation, or from Visual Studio: + +[Packaging MSIX apps - MSIX](/windows/msix/package/packaging-uwp-apps) + +Then, you can use the Home tab of the Xbox Device Portal to side-load your app and its dependencies: + +[Device Portal for Xbox - UWP application](/windows/uwp/xbox-apps/device-portal-xbox) +