> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 簡化的 GDK 目錄結構 (標頭和程式庫)

> 透過 GDKCrossPlatform 選擇採用 2025 年 10 月 GDK 的簡化目錄配置，適用於 MSBuild、CMake 和自訂組建，並將 ARM64 新增至您的 x64 遊戲。

在目前版本的 Microsoft Game Development Kit (GDK) 中，配置是以程式碼共用為核心進行最佳化，並著重於特定平台。此配置的組建整合大量仰賴將複雜性隱藏在 MSBuild 自訂平台中。新配置的重點則是簡化整合、支援日益增加的目標平台清單，以及改善對標準 MSBuild 平台和非 Microsoft 組建系統的支援。

## 舊的標頭和程式庫配置

Microsoft GDK 現有的檔案配置摘要如下。

```text theme={null}
251000\
    GRDK\
        ExtensionLibraries\
            Xbox.Services.API.C\
                ExtensionLibrary.props
                DesignTime\CommonConfiguration\Neutral\
                    Include\
                    Lib\
                    Redist\
            ...
        GameKit\
            Include\
            Lib\
                amd64\
```

**Gaming.Desktop.x64** 自訂 MSBuild 平台實作了建立 include/lib 路徑的邏輯，以各種方式組合所有這些內容。如果您使用 CMake 或自訂 make 解決方案，也必須在其中實作此邏輯。如需詳細範例，請參閱 2025 年 4 月版本的 [CMakeExample](https://github.com/microsoft/Xbox-GDK-Samples/tree/apr2025/Samples/Tools/CMakeExample)。

2025 年 10 月的 GDK 仍保留舊配置，以同時支援新舊兩種樣式。預設會同時安裝新舊配置。GDK 安裝程式現在包含僅安裝新配置的選項。未來的 GDK 將移除舊配置，以減少硬碟使用量和整體下載大小。目前移除舊配置的目標日期為 2025 年 10 月 GDK 發行後一年。

## 新的標頭和程式庫配置

在 2025 年 10 月的 GDK 版本中，新配置為標頭和程式庫提供了替代配置，讓平台整合更容易，並能隨著時間容納更多平台。

```text theme={null}
251000\
    windows\
        bin\
            arm64
            x64\
        include\
        lib\
            arm64
            x64\
        redist
```

## 搭配 MSBuild 自訂平台使用新配置

現有的 **Gaming.\*.x64** MSBuild 平台預設使用舊配置，但您可以設定 **GDKCrossPlatform** 屬性來選擇採用新配置。

```xml theme={null}
<PropertyGroup Label="Globals">
...
  <GDKCrossPlatform>true</GDKCrossPlatform>
</PropertyGroup>
```

這會將適當的 include/lib 路徑新增至專案，而不是舊配置所使用的各種複雜路徑。

在這個新的簡化整合中，不再使用延伸程式庫機制。所有內容預設都會在組建時於 include/lib 路徑中提供。

接著，專案需要連結其使用的其他程式庫。以較舊 GDK 專案範本建立的專案應包含如下的陳述式。

```xml theme={null}
<AdditionalDependencies>uuid.lib;$(Console_Libs);%(XboxExtensionsDependencies);%(AdditionalDependencies)</AdditionalDependencies>
```

在新配置中，**Console\_Libs** 屬性會列出必要的核心程式庫。

| 平台 | 核心程式庫 |
| - | - |
| Gaming.\*.x64 | xgameruntime.lib d3d12.lib dxguid.lib dxgi.lib gameinput.lib |

專案需要將其使用的延伸程式庫新增至 **AdditionalDependencies**，因為每個延伸程式庫都是「選擇性加入」的。

| 平台 | 核心程式庫 |
| - | - |
| Xbox.LibHttpClient | libHttpClient.lib |
| Xbox.XCurl.API | XCurl.lib |
| Xbox.Game.Chat.2.Cpp.API | GameChat2.lib |
| Xbox.Services.API.C (Debug) | Appnotify.lib winhttp.lib crypt32.lib Microsoft.Xbox.Services.142.C.Debug.lib |
| Xbox.Services.API.C (Release) | Appnotify.lib winhttp.lib crypt32.lib Microsoft.Xbox.Services.142.C.lib |
| PlayFab.Party.Cpp | Party.lib |
| PlayFab.PartyXboxLive.Cpp | PartyXboxLive.lib |
| PlayFab.Services.C | PlayFabCore.lib PlayFabGameSave.lib PlayFabServices.lib |
| PlayFab.Multiplayer.Cpp | PlayFabMultiplayer.lib |

專案也需要將其使用的其他 DLL 複製到配置中。您可以透過許多 DLL 程式庫整合常見的自訂建置步驟來完成，或編輯 vcxproj 或新增 props 檔案以使用 **ReferenceCopyLocalPaths** 項目群組清單。下方的 MSBuild 列出所有可能的 DLL，但個別專案只需要其中一部分。

```xml theme={null}
  <PropertyGroup>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKCoreLatest)</GDKCrossPlatformPath>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKXboxLatest)</GDKCrossPlatformPath>
  </PropertyGroup>

  <ItemGroup Condition="'$(Platform)'=='Gaming.Desktop.x64'">
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\libHttpClient.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\XCurl.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\GameChat2.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\Party.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PartyXboxLive.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabCore.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabGameSave.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabMultiplayer.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabServices.dll" />
  </ItemGroup>
```

<Note>
  `GameDKLatest` 只會由含 XBOX Extensions 的 Microsoft GDK 設定。因此，我們引進了完全支援並存安裝兩個 Microsoft GDK 版本的新環境變數：`GameDKCoreLatest` 由 Microsoft GDK 設定。
</Note>

### 使用 Directory.Build.props 檔案

若要使用新配置快速驗證現有的 GDK Gaming.\*.x64 專案，請將下列內容放入原始程式碼樹狀結構中名為 Directory.Build.props 的檔案。這會選擇採用新配置，並納入大部分或所有延伸程式庫，即使專案並未使用它們。

<Note>
  當 **GDKCrossPlatform** 設定為 true 進行組建時，MSBuild 規則不會使用 **GDKExtLibNames** 屬性。由於此屬性已存在於使用較舊 MSBuild 規則的組建中，因此在此 props 檔案中用來選擇將某些其他 DLL 加入配置。
</Note>

```xml theme={null}
<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

  <PropertyGroup>
    <GDKCrossPlatform>true</GDKCrossPlatform>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKCoreLatest)</GDKCrossPlatformPath>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKXboxLatest)</GDKCrossPlatformPath>
    <AllExtensionLibs>Appnotify.lib;winhttp.lib;crypt32.lib;libHttpClient.lib;XCurl.lib;GameChat2.lib;PlayFabCore.lib;PlayFabServices.lib;PlayFabMultiplayer.lib;Party.lib;PartyXboxLive.lib;PlayFabGameSave.lib</AllExtensionLibs>
    <AllExtensionLibs Condition="'$(Configuration)'=='Debug'">Microsoft.Xbox.Services.142.C.Debug.lib;$(AllExtensionLibs)</AllExtensionLibs>
    <AllExtensionLibs Condition="'$(Configuration)'!='Debug'">Microsoft.Xbox.Services.142.C.lib;$(AllExtensionLibs)</AllExtensionLibs>
  </PropertyGroup>

  <ItemDefinitionGroup Condition="'$(Platform)'=='Gaming.Desktop.x64'">
    <Link>
      <AdditionalDependencies>$(AllExtensionLibs);%(AdditionalDependencies)</AdditionalDependencies>
    </Link>
  </ItemDefinitionGroup>

  <!--
    Makes sure we deploy all the libs we need. We use the 'old layout' GDKExtLibNames property as a way to test
    what is requested to try to reduce the over-inclusion of unused DLLs.
  -->

  <ItemGroup Condition="'$(Platform)'=='Gaming.Desktop.x64'">
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\libHttpClient.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\XCurl.dll" />
  </ItemGroup>

  <ItemGroup Condition="'$(Platform)'=='Gaming.Desktop.x64' AND $(GDKExtLibNames.Contains('Xbox.Game.Chat.2.Cpp.API'))">
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\GameChat2.dll" />
  </ItemGroup>

  <ItemGroup Condition="'$(Platform)'=='Gaming.Desktop.x64' AND $(GDKExtLibNames.Contains('PlayFab'))">
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\Party.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PartyXboxLive.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabCore.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabGameSave.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabMultiplayer.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabServices.dll" />
  </ItemGroup>

</Project>
```

## 如何更新 x64 遊戲以新增 ARM64

若要將 ARM64 支援新增至現有的 x64 遊戲專案，請依照下列步驟操作：

1. **使用 Visual Studio 2022。** ARM64 支援需要 Visual Studio 2022。ARM64 組建不支援 Visual Studio 2019。
2. **啟用新配置。** 在專案檔中將 `GDKCrossPlatform` 設定為 `true`，以確保您的專案使用新配置。
3. **建立 ARM64 組態。** 複製現有的 x64 組態 (例如 Debug 和 Release)，以建立對應的 ARM64 組態。
4. **更新程式庫路徑。** 編輯 ARM64 組態的 VC++ 目錄，讓程式庫路徑參考 `lib\arm64` 而非 `lib\x64`。
5. **更新 XSAPI 程式庫參考。** 更新 *所有* 組態 (不只是 ARM64) 的連結陳述式，以使用 `Microsoft.Xbox.Services.143.GDK.C.lib` 而非 `Microsoft.Xbox.Services.142.GDK.C.lib`。
6. **更新 ReferenceCopyLocalPaths。** 檢查 `.vcxproj` 檔案中可能需要更新的 `ReferenceCopyLocalPaths` 用法，使其參考 `arm64` bin 資料夾而非 `x64`。

<Note>
  如果您的遊戲啟動失敗並出現錯誤 0xc000007b，表示您不小心嘗試將 x64 格式的 DLL 載入 ARM64 處理序。請檢查專案系統中可能需要更新的 `ReferenceCopyLocalPaths` 項目。
</Note>

## 搭配 MSBuild x64 平台使用新配置

您可以使用標準 **x64** 平台來為 PC 組建，而不使用 **Gaming.Desktop.x64** 平台。在舊配置中，這需要為延伸程式庫新增 `<Import Project="...\ExtensionLibrary.props">` 陳述式，詳情請參閱「搭配 Microsoft Game Development Kit (GDK) 使用 x64 平台」。

在新配置中，整合指示已大幅簡化。

```xml theme={null}
  <PropertyGroup>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKCoreLatest)</GDKCrossPlatformPath>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKXboxLatest)</GDKCrossPlatformPath>
  </PropertyGroup>
```

```xml theme={null}
<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">
  <ExecutablePath>$(GameDK)bin;$(GDKCrossPlatformPath)windows\bin\x64;$(ExecutablePath)</ExecutablePath>
  <IncludePath>$(GDKCrossPlatformPath)windows\Include;$(IncludePath);</IncludePath>
  <LibraryPath>$(GDKCrossPlatformPath)windows\lib\x64;$(LibraryPath)</LibraryPath>
</PropertyGroup>
```

```xml theme={null}
<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|x64'">
  <ExecutablePath>$(GameDK)bin;$(GDKCrossPlatformPath)windows\bin\x64;$(ExecutablePath)</ExecutablePath>
  <IncludePath>$(GDKCrossPlatformPath)windows\Include;$(IncludePath);</IncludePath>
  <LibraryPath>$(GDKCrossPlatformPath)windows\lib\x64;$(LibraryPath)</LibraryPath>
</PropertyGroup>
```

將所有必要的延伸程式庫連同原始清單一起新增至 **AdditionalDependencies**。

```xml theme={null}
<AdditionalDependencies>xgameruntime.lib;gameinput.lib;d3d12.lib;dxgi.lib;dxguid.lib;uuid.lib;kernel32.lib;user32.lib;%(AdditionalDependencies)</AdditionalDependencies>
```

選擇性加入的延伸程式庫 DLL 需要如上所述，使用自訂建置動作或使用 **ReferenceCopyLocalPaths** 項目群組，複製到二進位目錄中以形成最終配置。

其餘關於 **PreprocessorDefinitions** 以及處理含影像資產之 .mgc 檔案的指示維持不變。

## 搭配 CMake 使用新配置

當您搭配 CMake 使用 Microsoft Visual Studio 產生器並使用 **Gaming.\*.x64** 自訂 MSBuild 平台時，請使用下列程式碼啟用新配置。

```text theme={null}
set_property(TARGET ${PROJECT_NAME} PROPERTY VS_GLOBAL_GDKCrossPlatform "true")
```

在 [CMakeGDKExample](https://github.com/microsoft/Xbox-GDK-Samples/tree/apr2025/Samples/Tools/CMakeGDKExample) 中，移除 `VS_GLOBAL_GDKExtLibNames` 的使用，並以下列程式碼取代 (假設使用 CMake 3.21 或更新版本)，將所使用的延伸 DLL 複製到配置中。

```text theme={null}
add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E $<IF:$<BOOL:$<TARGET_RUNTIME_DLLS:${PROJECT_NAME}>>,copy,true>
    $<TARGET_RUNTIME_DLLS:${PROJECT_NAME}> $<TARGET_FILE_DIR:${PROJECT_NAME}>
    COMMAND_EXPAND_LISTS
    )
```

## 搭配自訂組建系統使用新配置

使用 GDK 為 Windows x64 組建需要下列項目。

```cmd theme={null}
set INCLUDE=%GameDKCoreLatest%windows\include;%INCLUDE%
set LIB=%GameDKCoreLatest%windows\lib\x64;%LIB%
set PATH=%GameDK%bin;%GameDKCoreLatest%windows\bin\x64;%PATH%
```

## 從已安裝的檔案讀取組建版本

新配置不包含 `grdk.ini` 檔案。若要透過剖析檔案來尋找版本資訊，請使用 `grdk.h`。

以下是一個 PowerShell 範例，也適用於較舊的 GDK 版本。

```powershell theme={null}
$result = Get-ChildItem -Path $env:GameDKCoreLatest -Filter "grdk.h" -Recurse
if ($result.Count -eq 0)
{
    $result = Get-ChildItem -Path $env:GRDKLatest -Filter "grdk.h" -Recurse
}
if ($result.Count -eq 0)
{
    Write-Error "##[error]Failed to find grdk.h in either GameDKCoreLatest or GRDKLatest" -ErrorAction Stop
}

$content = Get-Content -Path $result[0].FullName

if (-not ([string]$content -match '#define\s+_GRDK_EDITION\s+([0-9][0-9][0-9][0-9][0-9][0-9])')) {
    Write-Error "##[error]Failed to find edition define" -ErrorAction Stop
}

$xbld_edition = $Matches[1]

if (-not ([string]$content -match '#define\s+_GRDKVER_PRODUCTBUILDVER_FULL\s+([0-9]+\.[0-9]+\.([0-9]+)\.[0-9]+)')) {
    Write-Error "##[error]Failed to find full version define" -ErrorAction Stop
}

$xbld_full_productbuild = $Matches[1]
$xbld_build = $Matches[2]

if (-not ([string]$content -match '#define\s+_GRDK_MM_NUM\s+([0-9]{1,2})')) {
    Write-Error "##[error]Failed to find month define" -ErrorAction Stop
}

$month = $Matches[1]

if (-not ([string]$content -match '#define\s+_GRDK_FULLYY\s+([0-9]{4})')) {
    Write-Error "##[error]Failed to find full year define" -ErrorAction Stop
}

$year = $Matches[1]

Write-Output ("_xbld_name={0} {1} GRDK" -f (Get-Culture).DateTimeFormat.GetMonthName([int]$month), $year)
Write-Output ("_xbld_edition={0}" -f $xbld_edition)
Write-Output ("_xbld_full_productbuild={0}" -f $xbld_full_productbuild)
Write-Output ("_xbld_build={0}" -f $xbld_build)
```


## Related topics

- [WdCopySearchOptions](/zh-TW/reference/remoting/structs/wdcopysearchoptions.md)
- [xCurl 概觀](/zh-TW/build/console-features/networking/web-requests/intro-xcurl.md)
- [Matchmaking SDK 快速入門](/zh-TW/services/playfab/multiplayer/matchmaking/quickstart-client-sdk.md)
- [Lobby SDK 快速入門](/zh-TW/services/playfab/multiplayer/lobby/lobby-getting-started.md)
- [XMA2 編碼器工具](/zh-TW/build/console-features/audio/tools/xma2encodertool.md)