C# custom engine integration for PC: get started

Use this topic if you are preparing your game for publishing to the Microsoft Store on PC, and your game uses a C# based engine that does not have built in support for the GDK.

Creating a product in Partner Center
Integrating the GDK into C# games
Testing XBOX services in your game
Publishing

.NET toolchain topics

The following topics cover the .NET toolchain that this guide depends on:

Getting started with XBOX GDK.NET Describes how to get started writing XBOX games, tools, and services in C# with XBOX GDK.NET, the .NET projection of the GDK flat C API.
NativeAOT for gaming Describes the benefits, trade-offs, and best practices for using .NET NativeAOT in games built with the GDK, including what a console title must do to ship.

Creating a product in Partner Center

Before you can publish a game to the Microsoft Store, you need to create your XBOX services-enabled product in Partner Center. For more information about Partner Center, see Setting up an app or game in Partner Center, for Managed Partners.

Integrating the GDK into C# games

To integrate the GDK into a C# game, the game needs 3 things:

An "API layer" that provides C# friendly functions for the native implementation.
An "Interop layer" that handles the interop between the managed layer (your C# engine) and the unmanaged layer (the GRTS/XSAPI runtime DLLs).
The dynamic-link libraries that actually contain the runtime implementation of the functions.

XBOX GDK.NET provides the first two layers for you. It is a source-only .NET projection of the GDK flat C API that exposes the Gaming Runtime, XBOX services, and PlayFab as ordinary modern C#, so your engine calls Task-based methods and typed exceptions instead of hand-written P/Invoke. The third layer, the runtime implementation, ships with the GDK itself and is copied next to your executable at build time.

For a full description of the projection, what it covers, and the C# idioms it exposes, see Getting started with XBOX GDK.NET.

Note

The previous version of this guide built the XGamingRuntimeSDK.sln solution from the microsoft/gdk-unity-package repository. That package is deprecated. Use XBOX GDK.NET instead for new C# engine integrations.

Adding requirements for Gaming Runtime Services and XBOX Services API to your project

The following steps outline the changes you need to make to your project to ensure it has all the requirements for using the Gaming Runtime Services (GRTS) and XBOX Services API (XSAPI).

Clone or download a .zip of the XBOX GDK.NET repository from https://github.com/microsoft/XBOX-GDK-dotnet.
Build the projection. Building requires only a current .NET SDK, with no GDK install:
```
dotnet restore
dotnet build -c Release
```
Open your C# game project.
Set your project to target win-x64.
Add a reference to the GDK.Net project or to the GDK.Net.dll assembly that you built in the previous step.

Choose the target framework that matches your engine. net8.0 and net10.0 are the primary targets and are NativeAOT-safe; netstandard2.0 exists for MonoGame and Mono reach.

Opt in to the native modules your title uses. XBOX services and PlayFab are separate native modules, so you select them at packaging time with MSBuild properties. eng/packaging/GdkRedist.targets copies the modules you asked for next to the executable on every build.

Opt-in property	Native modules
(always)	`xgameruntime.thunks.dll`
`<GdkNetIncludeXboxLive>`	`Microsoft.Xbox.Services.C.Thunks.dll`, `libHttpClient.dll`
`<GdkNetIncludePlayFab>`	`PlayFabCore.dll`, `PlayFabServices.dll`, `PlayFabGameSave.dll`, `libHttpClient.dll`
`<GdkNetIncludePlayFabMultiplayer>`	`PlayFabMultiplayer.dll`
`<GdkNetIncludePlayFabParty>`	`Party.dll`, `PartyXboxLive.dll`

Note: If your engine supports any sort of run-in-editor functionality that uses a different .exe when running, you'll need to make sure that the .exe references these DLLs as well. If the DLLs aren't referenced by the .exe, XBOX services will not work when using your run-in-editor functionality.

Create a MicrosoftGame.config file and make sure it is copied to the same destination as the .exe during builds.

Note: If your engine supports any sort of run-in-editor functionality that uses a different .exe when running, you'll need to make sure MicrosoftGame.config is copied to the same directory as that .exe as well. If MicrosoftGame.config isn't present in the same directory as the .exe, XBOX services will not work when using your run-in-editor functionality.

For starting development, you can use a config with default values like the following example. Values for Identity->Name, Executable->Name, and Executable->Alias would all be replaced with the name of your executable.

<?xml version="1.0" encoding="utf-8"?>
<Game configVersion="1">

<Identity Name="Direct3DGame1_test"
            Publisher="CN=Publisher"
            Version="1.0.0.0"/>

<ExecutableList>
    <Executable Name="Direct3DGame1_test.exe"
                Id="Game"
                Alias="Direct3DGame1_test.exe"/>
</ExecutableList>

<ShellVisuals DefaultDisplayName="Direct3DGame1_test"
                PublisherDisplayName="PublisherName"
                Square480x480Logo="LargeLogo.png"
                Square150x150Logo="GraphicsLogo.png"
                Square44x44Logo="SmallLogo.png"
                Description="Direct3DGame1_test"
                ForegroundText="light"
                BackgroundColor="#000040"
                SplashScreenImage="SplashScreen.png"
                StoreLogo="StoreLogo.png"/>
</Game>

Update MicrosoftGame.config

The MicrosoftGame.config file created in the previous step has default values that allow early development on PC and XBOX without the need for further configuration until you start to use features in the Gaming Runtime, Microsoft Store, and title identity. In order to use XBOX services functionality you need to update your project's MicrosoftGame.config with your Partner Center project identity details. You'll also need to list VC14 as a known dependency, which is required by Microsoft.Xbox.Services.C.Thunks.dll.

Go to the Partner Center dashboard.
Select your game from the list of products.
Select the Game setup tab, and then select Identity details.
Select Show Details to expand the Identity details section.
Use the following values from the table in the Identity details section, and then copy those values from Partner Center into the corresponding element and field in MicrosoftGame.config.
Add a KnownDependency element for VC14 in DesktopRegistration->DependencyList.

Name in Partner Center	MicrosoftGame.config
XBOX Title ID	TitleId
Package/Identity/Name	Identity->Name
Package/Identity/Publisher	Identity->Publisher
XBOX services -> XBOX Settings -> MSAAppId	MSAAppId

For example, the following identity details in Partner Center would result in your MicrosoftGame.config looking like the sample below:

Name in Partner Center	Example value
XBOX Title ID	64353034
Package/Identity/Name	41336MicrosoftATG.Achievements2017Redux
Package/Identity/Publisher	CN=A4954634-DF4B-47C7-AB70-D3215D246AF1
XBOX services -> XBOX Settings -> MSAAppId	0000000000000000

<?xml version="1.0" encoding="utf-8"?>
<Game configVersion="1">

  <Identity Name='41336MicrosoftATG.Achievements2017Redux' Version="1.1.0.0" Publisher='CN=A4954634-DF4B-47C7-AB70-D3215D246AF1' />

  <TitleId>64353034</TitleId>
  <MSAAppId>0000000000000000</MSAAppId>

  <ExecutableList>
    <Executable Name="Achievements2017_desktop.exe"
                TargetDeviceFamily="PC"
                Id="Game"/>
  </ExecutableList>

  <ShellVisuals DefaultDisplayName="Achievements2017 Desktop Sample"
                PublisherDisplayName="XBOX Advanced Technology Group"
                StoreLogo="Assets\StoreLogo.png"
                Square150x150Logo="Assets\Logo.png"
                Square44x44Logo="Assets\SmallLogo.png"
                Square480x480Logo="Assets\LargeLogo.png"
                Description="Achievements2017"
                ForegroundText="dark"
                BackgroundColor="#000000"
                SplashScreenImage="Assets\SplashScreen.png"/>

  <DesktopRegistration>
    <DependencyList>
      <KnownDependency Name="VC14"/>
    </DependencyList>
  </DesktopRegistration>

</Game>

See MicrosoftGame.config overview for additional information on the values in MicrosoftGame.config.

Initialize the game runtime and XSAPI

The following steps show how to initialize Gaming Runtime Services and XSAPI in your game.

Add using GDK.Net; to your project's .cs file.
Add using GDK.Net.Users; to your project's .cs file if you sign users in.
Initialize the Gaming Runtime. GameRuntime is both the entry point and the lifetime owner, so hold the instance for as long as your game is running:
```
using GameRuntime runtime = GameRuntime.Initialize();
```
Add your title's SCID to the <GdkNetIncludeXboxLive> configuration and access XBOX services through the runtime instance:
```
using User user = await runtime.Users
    .AddAsync(UserAddOptions.AddDefaultUserSilently)
    .ConfigureAwait(false);

Console.WriteLine($"id 0x{user.Id:X16}, state {user.State}");
```
Replace the SCID in your configuration with a string containing your Partner Center project's SCID.

Unlike the flat C API, XBOX GDK.NET reports failures as exceptions rather than HRESULT return codes, and asynchronous operations return Task instead of requiring an XAsyncBlock and a paired "get result" call. See Getting started with XBOX GDK.NET for the complete mapping.

Uninitializing the game runtime

Gaming Runtime Services need to be uninitialized before your game exits. XSAPI does not need to be explicitly cleaned up prior to exit.

XBOX GDK.NET models the runtime as IDisposable, so disposing the GameRuntime instance uninitializes the Gaming Runtime after all other activity has completed. A using declaration does this for you at the end of the enclosing scope; call Dispose explicitly if your engine owns the lifetime:

// Uninitialize the Gaming Runtime after
// all other activity has been completed.
runtime.Dispose();

See Getting started with XBOX services APIs for a detailed overview of using XSAPI in your game. See Game Development Kit (GDK) features for overviews of implementing GDK features.

Testing XBOX services in your game

In order to test XBOX services functionality in your game such as achievements, you need to use a sandbox and test accounts with access to that sandbox.

Creating a test account

To test any XBOX services features in your game you'll need to create test accounts that have access to your development sandbox. For information about creating test accounts, see Creating test accounts.

Switching your sandbox

After you've created a test account, use the account to access your sandbox by using the following steps.

To find your sandbox ID, go to Partner Center.
Select XBOX services, and then select Gameplay Settings.

Note

Your sandbox ID is on the first tab, and it's named like "ABCDEF.0".
Open the Start menu.
Enter Microsoft GDK Command Prompts, and then select Enter on your keyboard.
Open the first command prompt.
In the command prompt, enter XblPCSandbox.exe [your sandbox ID].
After the command prompt launches several apps, sign in with your test account to the XBOX App.

If you're able to sign in successfully, you've created a test account and changed to your sandbox to begin testing.

For more information on sandboxes see XBOX services Sandboxes overview.

Publishing

In order to be ready to publish your game, you need to:

Have finished integrating your game with the GDK
Created a game package by following the steps in Getting started with packaging titles for a PC by using the MSIXVC packaging tools

If you are shipping to XBOX Series X|S or XBOX One, your title must also be NativeAOT-compiled, because consoles do not permit JIT compilation. See NativeAOT for gaming for the build configuration and the migration checklist.

After you've completed those two requirements, you're ready to publish. To submit your game, go to Partner Center and follow the instructions in the UI.

Feedback

Was this page helpful?

Last updated on 2026-09-29