Skip to main content
本文說明如何搭配 Microsoft Game Development Kit (GDK) 使用 MsQuic。MsQuic 是 Microsoft 對 IETF QUIC 通訊協定的實作。它是跨平台的、以 C 撰寫,並設計為一般用途的 QUIC 程式庫。 QUIC 最初的設計目的是取代使用「TLS over TCP」的案例,例如 HTTP。開發人員將其擴充為一般用途的 UDP 資料傳輸層,適合在單一連線上多工處理即時的不可靠資料包訊息,以及類似 TCP 的可靠資料流。此設計使其特別適合作為用戶端/伺服器傳輸層,以及即時遊戲流量資料流的基礎。 MsQuic 專為 GDK 遊戲量身打造,也適用於多種平台,包括 Windows Server、Linux 桌面與伺服器、iOS、Android 和 macOS。 MsQuic API 文件涵蓋許多重要的 MsQuic 概念,並說明如何針對 MsQuic API 介面撰寫程式碼。

QUIC 功能

  • 所有封包都經過加密,且交握會使用 TLS 1.3 進行驗證。
  • 可靠與不可靠應用程式資料的平行資料流。
  • 在第一次來回行程中交換應用程式資料 (0-RTT)。
  • 改良的壅塞控制與遺失復原。
  • 用戶端的 IP 位址或連接埠變更後仍可維持連線。
  • 無狀態負載平衡。
  • 可輕鬆擴充新功能和延伸模組。

MsQuic 實作

除了專為搭配 GDK 遊戲使用而量身打造之外,MsQuic 還有數項功能,使其有別於其他 QUIC 實作:
  • 針對用戶端和伺服器最佳化。
  • 針對最大輸送量和最小延遲最佳化。
  • 非同步 IO。
  • 支援接收端調整 (RSS)。
  • 支援 UDP 傳送和接收合併。
MsQuic 實作下列 QUIC RFC: MsQuic 實作下列 QUIC 草案延伸模組:

取得 MsQuic

Microsoft 在開放原始碼 GitHub 存放庫中裝載 MsQuic。您應該透過位於這裡的其中一個正式版本取得 MsQuic。XBOX Series X|S 主機支援是在 prerelease/1.9 中新增的,不過對於 GDK 遊戲,建議您盡可能採用最新的正式發行版本。 您可以在特定版本的 Assets 區段中,找到該版本預先建置的 MsQuic 二進位檔。特定 MsQuic 版本的所有建置類別彼此完全相容。雖然 MsQuic 也會盡量維持其版本的回溯相容性,但請參閱 MsQuic 文件和版本資訊,了解不同版本之間的相容性預期。

以 GDK 為基礎的 PC 遊戲

針對以 GDK 為基礎的 PC 遊戲,請使用 msquic_windows_x64_Release_openssl 預先建置的二進位檔。 PC 上的 GDK 遊戲會以原生 x64 Win32 應用程式的形式執行。請使用針對 x64 平台建置的 MsQuic 版本。在 PC 上,請使用以 OpenSSL 建置的 MsQuic 版本,因為它支援 GDK 所支援的所有作業系統版本。使用 Schannel 的版本僅支援 Windows 11 作業系統及更新版本。

以 GDK 為基礎的主機遊戲

針對以 GDK 為基礎的主機遊戲,請使用 msquic_gamecore_console_x64_Release_schannel 預先建置的二進位檔。 MsQuic 為 XBOX 主機上以 GDK 為基礎的遊戲提供特殊的建置類別。此類別會將 MsQuic 限制為 WINAPI_PARTITION_GAMES 下的 API,並使 MsQuic 連結 XGamePlatform.lib。若要使用此建置類別,您必須安裝 2021 年 10 月版本或更新版本的 XGDK。為以 GDK 為基礎的主機遊戲建置時,MsQuic 會使用 Schannel。

用戶端與伺服器驗證

MsQuic 會自動使用與 HTTPS Web 要求相同的驗證和確認路徑來驗證您的伺服器。用戶端驗證應遵循安全用戶端/伺服器通訊的最佳做法 (NDA 主題) 中所述的最佳做法。 在 MsQuic 中,用戶端和伺服器都應使用 ConfigurationLoadCredential API 搭配適當的 QUIC_CREDENTIAL_CONFIG 來設定您的憑證。MsQuic 中預設包含的所有加密套件都被視為安全,但請務必正確設定 MsQuic 在用戶端和伺服器上驗證憑證的方式,以確保建立安全且經過驗證的通訊通道。 在伺服器上,若要使用 XSTS 權杖用戶端驗證,您應該指定 QUIC_CREDENTIAL_FLAG_REQUIRE_CLIENT_AUTHENTICATION、QUIC_CREDENTIAL_FLAG_INDICATE_CERTIFICATE_RECEIVED 和 QUIC_CREDENTIAL_FLAG_NO_CERTIFICATE_VALIDATION 旗標。指定 QUIC_CREDENTIAL_FLAG_NO_CERTIFICATE_VALIDATION 旗標時,您必須在 QUIC_CONNECTION_EVENT_PEER_CERTIFICATE_RECEIVED 事件回呼中自行驗證用戶端憑證,如安全用戶端/伺服器通訊的最佳做法 (NDA 主題) 一節中所述。 此外,在伺服器上,您應該提供具有正確根目錄的憑證,讓用戶端能夠驗證您的伺服器,就像您在 HTTPS Web 伺服器中所做的一樣。 在用戶端上,您_絕對不_應該指定 QUIC_CREDENTIAL_FLAG_NO_CERTIFICATE_VALIDATION 旗標,因為 MsQuic 用於伺服器驗證的預設行為是驗證身分最簡單且最安全的方式。相反地,對於 XSTS 權杖用戶端驗證,您應該指定 QUIC_CREDENTIAL_FLAG_CLIENT 旗標,並搭配由您的伺服器所產生的憑證,如安全用戶端/伺服器通訊的最佳做法 (NDA 主題) 一節中所述。建議您指定 QUIC_CREDENTIAL_TYPE_CERTIFICATE_CONTEXT 模式來提供用戶端憑證,並使用 CertCreateContext 等 API,直接從您的 Web 要求回應資料產生內容。

網路初始化

MsQuic 不會自動為 GDK 遊戲處理網路初始化。在遊戲啟動後以及每次繼續後,請等待網路完成初始化,再使用 MsQuicOpenVersion 或 MsQuicOpen 初始化 MsQuic。

暫停與繼續

使用 RegisterAppStateChangeNotification 註冊暫停和繼續事件。暫停時,關閉所有開啟的資料流,並關閉 MsQuic。然後在繼續時,等待網路初始化,再重新開啟 MsQuic。 若要在暫停逾時內快速關閉所有 MsQuic 資料流,請針對每個開啟的資料流,使用 QUIC_STREAM_SHUTDOWN_FLAG_ABORT 和 QUIC_STREAM_SHUTDOWN_FLAG_IMMEDIATE 旗標呼叫 StreamShutdown。此呼叫會立即觸發 QUIC_STREAM_EVENT_SHUTDOWN_COMPLETE 事件。此時,就可以安全地呼叫 StreamClose 來關閉資料流。指定連線的所有資料流都關閉後,請使用 QUIC_CONNECTION_SHUTDOWN_FLAG_SILENT 旗標呼叫 ConnectionShutdown,接著呼叫 ConnectionClose。關閉所有連線後,針對任何未處理的註冊和設定呼叫 RegistrationClose 和 ConfigurationClose,接著呼叫 MsQuicClose。

慣用連接埠

在 GDK 遊戲中,請將慣用本機 UDP 多人遊戲連接埠用於主要遊戲流量。在呼叫 ConnectionStart 之前,請在連線物件控制代碼上使用 SetParam 函式搭配 QUIC_PARAM_CONN_LOCAL_ADDRESS 設定,在 MsQuic 中設定此連接埠。 設定 QUIC_PARAM_CONN_LOCAL_ADDRESS 時,請指定 AF_UNSPEC 系列,以允許雙堆疊 IPv4 和 IPv6 通訊端。下列範例示範當 MsQuicCallTable 是從 MsQuicOpen 傳回,且 MsQuicConnectionHandle 是從 ConnectionOpen 傳回時,如何設定慣用連接埠。

記憶體考量

MsQuic 的高效能實作允許高頻寬資料在您的 GDK 遊戲之間傳輸。作為 WinSock 記憶體考量的延伸,使用 MsQuic 時,請遵循下列最佳做法,以盡量減少核心的記憶體耗用量: GDK 遊戲應將回呼中的任何執行時間降到最低。MsQuic 不會為通訊協定執行和對應用程式的上行呼叫使用個別的執行緒。因此,回呼中的任何顯著延遲都會延遲通訊協定,並增加核心所需的記憶體耗用量。遊戲需要完成的任何大量時間或工作,都必須在其自己的執行緒上進行。 GDK 遊戲應有效率地管理其傳送緩衝區,以減少核心記憶體使用量。如需詳細資訊,請參閱 MsQuic 中的傳送緩衝處理,了解 MsQuic 如何讓您的遊戲控制此行為。 強烈建議您搭配 MsQuic 使用非同步接收,以確保任何接收的資料都能有效率地傳輸到使用者模式緩衝區。在 MsQuic 中接收提供有關如何處理非同步接收的其他詳細資料。此外,請勿在 MsQuic GDK 用戶端中使用部分資料接受功能,以盡量減少耗用的核心記憶體量。

另請參閱

MsQuic MsQuic API 文件 MsQuic 版本 建置 MsQuic 文件 MsQuic Echo PlayFab 伺服器範例
Last modified on October 6, 2026