Skip to main content
관리형 코드에서 Microsoft Game Development Kit(GDK)와 XBOX 서비스 API를 올바르게 호출하기 위해 API 래퍼를 어떻게 사용하는지 이 항목에서 확인하세요.

Microsoft Game Development Kit(GDK) API 액세스

Unity에서 Microsoft GDK API 패키지를 임포트한 후에는 XGamingRuntime 네임스페이스 아래에서 기능을 사용할 수 있습니다. 모든 Gaming Runtime API는 SDK 클래스의 정적 메서드로 제공됩니다. 모든 XBOX 서비스 API는 SDK.XBL 클래스의 정적 메서드로 제공됩니다. 다음 예시가 이를 보여줍니다.

API 커버리지와 규칙

모든 API가 패키지를 통해 제공되는 것은 아닙니다. 전체 목록은 이 항목의 뒷부분에 있는 Microsoft Game Development Kit(GDK) 및 XBOX 서비스 API 목록을 참조하세요.
규칙:
  • API 이름은 가능한 한 GDK의 대응 API와 일치합니다.
  • 예외를 사용하지 않습니다. 오류는 HRESULT로 전달됩니다.
  • 객체 지향 캡슐화 없는 플랫한 API 표면.
  • 매개변수를 설정하는 API에서는 out 매개변수를 사용합니다.
  • 비동기 메서드는 콜백을 사용합니다. 자세한 내용은 다음 섹션을 참조하세요.

비동기 프로그래밍 모델

대부분의 비동기 API는 마지막 매개변수로 콜백을 받습니다. 예시는 다음과 같습니다.
스레딩 모델에 대한 정보는 다음과 같습니다.
  • 비동기 메서드는 즉시 실행되며, 작업은 스레드 풀에서 사용 가능한 스레드에서 수행됩니다.
    • 스레드 풀은 SDK.XGameRuntimeInitialize() 호출 후 내부적으로 초기화됩니다.
    • 스레드 풀 구성 옵션은 노출되지 않습니다.
  • 결과 콜백은 디스패치(예: SDK.XTaskQueueDispatch())가 호출된 후 실행됩니다. 따라서 이상적으로는 게임의 업데이트 루프에서 _자주 호출_하는 것이 중요합니다.
  • 결과 콜백은 디스패치를 호출한 스레드에서 실행됩니다.

네이티브 API와 관리형 래퍼의 예시 차이

네이티브 API와 관리형 래퍼는 차이가 거의 없습니다. 참고로 다음 두 예시는 관리형과 네이티브 코드에서 XUserAddAsyncXblAchievementsUpdateAchievementAsync의 시그니처와 호출을 보여줍니다.

XUserAddAsync 예시

XUserAddAsync의 네이티브 시그니처는 다음과 같습니다.
XUserAddAsync의 관리형 시그니처는 다음과 같습니다.
네이티브 코드에서 XUserAddAsync의 함수를 호출하는 예시는 다음과 같습니다.
XUserAddAsync 함수를 호출하는 관리형 예시는 다음과 같습니다.
사용자가 커스텀 큐를 사용하려 하거나 API가 콜백 구현을 포함하지 않는 경우, 다음 예시는 XAsyncBlock을 만드는 방법을 보여줍니다. 또한 사용자는 큐의 적절한 디스패치와 완료를 보장해야 합니다. 자세한 내용은 XTaskQueue 라이브러리 개요를 참조하세요.

XblAchievementsUpdateAchievementAsync 예시

XblAchievementsUpdateAchievementAsync의 네이티브 시그니처는 다음과 같습니다.
XblAchievementsUpdateAchievementAsync의 관리형 시그니처는 다음과 같습니다.
네이티브 코드에서 XblAchievementsUpdateAchievementAsync 함수를 호출하는 예시는 다음과 같습니다.
XblAchievementsUpdateAchievementAsync 함수를 호출하는 관리형 예시는 다음과 같습니다.

관리형 코드에서 XBOX Services API(XSAPI) 초기화

참고로, 다음은 관리형 코드에서 XSAPI의 초기화입니다. 이는 관리형 코드에서의 XSAPI 시그니처입니다.
다음은 관리형 코드에서의 XSAPI 호출 패턴 예시입니다.

관리형 래퍼에 포함된 Microsoft Game Development Kit(GDK) API 목록

다음 Microsoft Game Development Kit(GDK) API가 GDK Unity 패키지의 관리형 래퍼에 포함되어 있습니다. Microsoft Game Development Kit(GDK) API에 대한 자세한 내용은 System API 레퍼런스를 참조하세요.
  • XAccessibility
    • XClosedCaptionGetProperties
    • XClosedCaptionSetEnabled
    • XHighContrastGetMode
    • XSpeechToTextSendString
    • XSpeechToTextSetPositionHint
    • XSpeechToTextBeginHypothesisString
    • XSpeechToTextUpdateHypothesisString
    • XSpeechToTextFinalizeHypothesisString
    • XSpeechToTextCancelHypothesisString
  • XAppCapture
    • XAppBroadcastGetStatus
    • XAppBroadcastIsAppBroadcasting
    • XAppBroadcastShowUI
    • XAppBroadcastRegisterIsAppBroadcastingChanged
    • XAppCaptureCloseLocalStream
    • XAppCaptureCloseScreenshotStream
    • XAppCaptureEnableRecord
    • XAppCaptureDisableRecord
    • XAppBroadcastUnregisterIsAppBroadcastingChanged
    • XAppCaptureMetadataAddStringEvent
    • XAppCaptureMetadataAddInt32Event
    • XAppCaptureMetadataAddDoubleEvent
    • XAppCaptureMetadataStartStringState
    • XAppCaptureMetadataStartInt32State
    • XAppCaptureMetadataStartDoubleState
    • XAppCaptureMetadataStopState
    • XAppCaptureMetadataStopAllStates
    • XAppCaptureMetadataRemainingStorageBytesAvailable
    • XAppCaptureOpenScreenshotStream
    • XAppCaptureReadScreenshotStream
    • XAppCaptureRecordDiagnosticClip
    • XAppCaptureTakeDiagnosticScreenshot
    • XAppCaptureTakeScreenshot
    • XAppCaptureRegisterMetadataPurged
    • XAppCaptureUnRegisterMetadataPurged
    • XAppCaptureReadLocalStream
    • XAppCaptureRecordTimespan
    • XAppCaptureGetVideoCaptureSettings
  • XAsync
    • XAsyncGetStatus
    • XAsyncGetResultSize
    • XAsyncCancel
    • XAsyncRun
  • XDisplay
    • XDisplayTryEnableHdrMode
    • XDisplayAcquireTimeoutDeferral
    • XDisplayCloseTimeoutDeferralHandle
  • XError
    • XErrorSetCallback
    • XErrorSetOptions
  • XGameEvent
    • XGameEventWrite
  • XGame
    • XGameGetXboxTitleId
    • XLaunchNewGame
    • XLaunchRestartOnCrash
  • XGameInvite
    • XGameInviteRegisterForEvent
    • XGameInviteUnregisterForEvent
  • XGameProtocol
    • XGameProtocolRegisterForActivation
    • XGameProtocolUnregisterForActivation
  • XGameRuntimeFeature
    • XGameRuntimeIsFeatureAvailable
  • XGameRuntimeInit
    • XGameRuntimeInitialize
    • XGameRuntimeUninitialize
  • XGameSave
    • XGameSaveInitializeProvider
    • XGameSaveInitializeProviderAsync
    • XGameSaveInitializeProviderResult
    • XGameSaveCloseProvider
    • XGameSaveGetRemainingQuota
    • XGameSaveGetRemainingQuotaAsync
    • XGameSaveGetRemainingQuotaResult
    • XGameSaveDeleteContainer
    • XGameSaveDeleteContainerAsync
    • XGameSaveDeleteContainerResult
    • XGameSaveCreateContainer
    • XGameSaveCloseContainer
    • XGameSaveGetContainerInfo
    • XGameSaveEnumerateContainerInfo
    • XGameSaveEnumerateContainerInfoByName
    • XGameSaveEnumerateBlobInfo
    • XGameSaveEnumerateBlobInfoByName
    • XGameSaveReadBlobData
    • XGameSaveReadBlobDataAsync
    • XGameSaveReadBlobDataResult
    • XGameSaveCreateUpdate
    • XGameSaveCloseUpdateHandle
    • XGameSaveSubmitBlobWrite
    • XGameSaveSubmitBlobDelete
    • XGameSaveSubmitUpdate
    • XGameSaveSubmitUpdateAsync
    • XGameSaveSubmitUpdateResult
  • XGameSaveFiles
    • XGameSaveFilesGetFolderWithUiAsync
    • XGameSaveFilesGetFolderWithUiResult
    • XGameSaveFilesGetRemainingQuota
  • XGameStreaming
    • XGameStreamingInitialize
    • XGameStreamingUninitialize
    • XGameStreamingIsStreaming
    • XGameStreamingGetClientCount
    • XGameStreamingGetClients
    • XGameStreamingGetConnectionState
    • XGameStreamingRegisterConnectionStateChanged
    • XGameStreamingUnregisterConnectionStateChanged
    • XGameStreamingHideTouchControls
    • XGameStreamingHideTouchControlsOnClient
    • XGameStreamingShowTouchControlLayout
    • XGameStreamingShowTouchControlLayoutOnClient
    • XGameStreamingRegisterClientPropertiesChanged
    • XGameStreamingUnregisterClientPropertiesChanged
    • XGameStreamingGetStreamPhysicalDimensions
    • XGameStreamingGetStreamAddedLatency
    • XGameStreamingGetServerLocationNameSize
    • XGameStreamingGetServerLocationName
    • XGameStreamingIsTouchInputEnabled
    • XGameStreamingGetLastFrameDisplayed
    • XGameStreamingUpdateTouchControlsState
    • XGameStreamingUpdateTouchControlsStateOnClient
    • XGameStreamingShowTouchControlsWithStateUpdate
    • XGameStreamingShowTouchControlsWithStateUpdateOnClient
    • XGameStreamingGetTouchBundleVersionNameSize
    • XGameStreamingGetTouchBundleVersion
    • XGameStreamingGetClientIPAddress
    • XGameStreamingGetSessionId
    • XGameStreamingGetDisplayDetails
    • XGameStreamingSetResolution
  • XGameUI
    • XGameUIShowAchievementsAsync
    • XGameUIShowAchievementsResult
    • XGameUIShowMessageDialogAsync
    • XGameUIShowMessageDialogResult
    • XGameUIShowErrorDialogAsync
    • XGameUIShowErrorDialogResult
    • XGameUIShowTextEntryAsync
    • XGameUIShowTextEntryResultSize
    • XGameUIShowTextEntryResult
    • XGameUITextEntryClose
    • XGameUITextEntryGetExtents
    • XGameUITextEntryOpen
    • XGameUITextEntryGetState
    • XGameUITextEntryUpdatePositionHint
    • XGameUITextEntryUpdateVisibility
    • XGameUISetNotificationPositionHint
    • XGameUIShowSendGameInviteAsync
    • XGameUIShowSendGameInviteResult
    • XGameUIShowMultiplayerActivityGameInviteAsync
    • XGameUIShowMultiplayerActivityGameInviteResult
    • XGameUIShowWebAuthenticationAsync
    • XGameUIShowWebAuthenticationResult
    • XGameUIShowWebAuthenticationWithOptionsAsync
    • XGameUIShowWebAuthenticationResultSize
    • XGameUIShowPlayerProfileCardAsync
    • XGameUIShowPlayerProfileCardResult
    • XGameUIShowPlayerPickerAsync
    • XGameUIShowPlayerPickerResultCount
    • XGameUIShowPlayerPickerResult
  • XLauncher
    • XLaunchUri
  • XNetworking
    • XNetworkingGetConnectivityHint
    • XNetworkingQueryConfigurationSetting
    • XNetworkingQueryPreferredLocalUdpMultiplayerPort
    • XNetworkingQueryPreferredLocalUdpMultiplayerPortAsync
    • XNetworkingQueryPreferredLocalUdpMultiplayerPortAsyncResult
    • XNetworkingQuerySecurityInformationForUrlAsync
    • XNetworkingQuerySecurityInformationForUrlAsyncResultSize
    • XNetworkingQuerySecurityInformationForUrlAsyncResult
    • XNetworkingQuerySecurityInformationForUrlUtf16Async
    • XNetworkingQuerySecurityInformationForUrlUtf16AsyncResultSize
    • XNetworkingQuerySecurityInformationForUrlUtf16AsyncResult
    • XNetworkingQueryStatistics
    • XNetworkingRegisterConnectivityHintChanged
    • XNetworkingUnregisterConnectivityHintChanged
    • XNetworkingRegisterPreferredLocalUdpMultiplayerPortChanged
    • XNetworkingUnregisterPreferredLocalUdpMultiplayerPortChanged
    • XNetworkingVerifyServerCertificate
  • XPackage
    • XPackageGetCurrentProcessPackageIdentifier
    • XPackageIsPackagedProcess
    • XPackageGetUserLocale
    • XPackageEnumeratePackages
    • XPackageFindChunkAvailability
    • XPackageChangeChunkInstallOrder
    • XPackageInstallChunks
    • XPackageUninstallChunks
    • XPackageInstallChunksAsync
    • XPackageInstallChunksResult
    • XPackageRegisterPackageInstalled
    • XPackageUnregisterPackageInstalled
    • XPackageEnumerateFeatures
    • XPackageEnumerateChunkAvailability
    • XPackageMount
    • XPackageMountWithUiAsync
    • XPackageMountWithUiResult
    • XPackageGetMountPath
    • XPackageGetMountPathSize
    • XPackageCloseMountHandle
    • XPackageCreateInstallationMonitor
    • XPackageCloseInstallationMonitorHandle
    • XPackageGetInstallationProgress
    • XPackageUpdateInstallationMonitor
    • XPackageRegisterInstallationProgressChanged
    • XPackageUnregisterInstallationProgressChanged
    • XPackageEstimateDownloadSize
    • XPackageGetWriteStats
    • XPackageUninstallUWPInstance
    • XPackageUninstallPackage
  • XPersistentLocalStorage
    • XPersistentLocalStorageGetPathSize
    • XPersistentLocalStorageGetPath
    • XPersistentLocalStorageGetSpaceInfo
    • XPersistentLocalStoragePromptUserForSpaceAsync
    • XPersistentLocalStoragePromptUserForSpaceResult
  • XSpeechSynthesizer
    • XSpeechSynthesizerEnumerateInstalledVoices
    • XSpeechSynthesizerCreate
    • XSpeechSynthesizerCloseHandle
    • XSpeechSynthesizerSetDefaultVoice
    • XSpeechSynthesizerSetCustomVoice
    • XSpeechSynthesizerCreateStreamFromText
    • XSpeechSynthesizerCreateStreamFromSsml
    • XSpeechSynthesizerCloseStreamHandle
    • XSpeechSynthesizerGetStreamDataSize
    • XSpeechSynthesizerGetStreamData
  • XStore
    • XStoreCreateContext
    • XStoreCloseContextHandle
    • XStoreIsAvailabilityPurchasable
    • XStoreAcquireLicenseForPackageAsync
    • XStoreAcquireLicenseForPackageResult
    • XStoreCanAcquireLicenseForPackageAsync
    • XStoreCanAcquireLicenseForPackageResult
    • XStoreCanAcquireLicenseForStoreIdAsync
    • XStoreCanAcquireLicenseForStoreIdResult
    • XStoreCloseLicenseHandle
    • XStoreIsLicenseValid
    • XStoreQueryAddOnLicensesAsync
    • XStoreQueryAddOnLicensesResultCount
    • XStoreQueryAddOnLicensesResult
    • XStoreQueryGameLicenseAsync
    • XStoreQueryGameLicenseResult
    • XStoreQueryLicenseTokenAsync
    • XStoreQueryLicenseTokenResultSize
    • XStoreQueryLicenseTokenResult
    • XStoreRegisterGameLicenseChanged
    • XStoreUnregisterGameLicenseChanged
    • XStoreRegisterPackageLicenseLost
    • XStoreUnregisterGameLicenseChanged
    • XStoreUnregisterPackageLicenseLost
    • XStoreAcquireLicenseForDurablesAsync
    • XStoreQueryGameAndDlcPackageUpdatesAsync
    • XStoreQueryGameAndDlcPackageUpdatesResultCount
    • XStoreQueryGameAndDlcPackageUpdatesResult
    • XStoreDownloadAndInstallPackagesAsync
    • XStoreDownloadAndInstallPackagesResultCount
    • XStoreDownloadAndInstallPackagesResult
    • XStoreDownloadAndInstallPackageUpdatesAsync
    • XStoreDownloadAndInstallPackageUpdatesResult
    • XStoreDownloadPackageUpdatesAsync
    • XStoreDownloadPackageUpdatesResult
    • XStoreQueryPackageIdentifier
    • XStoreShowRedeemTokenUIAsync
    • XStoreShowRedeemTokenUIResult
    • XStoreShowRateAndReviewUIAsync
    • XStoreShowRateAndReviewUIResult
    • XStoreShowPurchaseUIAsync
    • XStoreShowPurchaseUIResult
    • XStoreQueryConsumableBalanceRemainingAsync
    • XStoreQueryConsumableBalanceRemainingResult
    • XStoreReportConsumableFulfillmentAsync
    • XStoreReportConsumableFulfillmentResult
    • XStoreGetUserCollectionsIdAsync
    • XStoreGetUserCollectionsIdResultSize
    • XStoreGetUserCollectionsIdResult
    • XStoreGetUserPurchaseIdAsync
    • XStoreGetUserPurchaseIdResultSize
    • XStoreGetUserPurchaseIdResult
    • XStoreQueryAssociatedProductsAsync
    • XStoreQueryAssociatedProductsResult
    • XStoreQueryEntitledProductsAsync
    • XStoreQueryEntitledProductsResult
    • XStoreQueryProductForCurrentGameAsync
    • XStoreQueryProductForCurrentGameResult
    • XStoreQueryProductForPackageAsync
    • XStoreQueryProductForPackageResult
    • XStoreQueryProductsAsync
    • XStoreQueryProductsResult
    • XStoreProductsQueryNextPageAsync
    • XStoreCloseProductsQueryHandle
    • XStoreAcquireLicenseForDurablesResult
    • XStoreEnumerateProductsQuery
    • XStoreProductsQueryHasMorePages
    • XStoreProductsQueryNextPageResult
    • XStoreShowAssociatedProductsUIAsync
    • XStoreShowAssociatedProductsUIResult
    • XStoreShowProductPageUIAsync
    • XStoreShowProductPageUIResult
  • XSystem
    • XSystemGetAnalyticsInfo
    • XSystemGetAppSpecificDeviceId
    • XSystemGetConsoleId
    • XSystemGetDeviceType
    • XSystemGetXboxLiveSandboxId
    • XSystemGetRuntimeInfo
    • XSystemIsHandleValid
    • XSystemHandleTrack
  • XTaskQueue
    • XTaskQueueCloseHandle
    • XTaskQueueCreate
    • XTaskQueueCreateComposite
    • XTaskQueueDispatch
    • XTaskQueueDuplicateHandle
    • XTaskQueueGetCurrentProcessTaskQueue
    • XTaskQueueGetPort
    • XTaskQueueRegisterMonitor
    • XTaskQueueRegisterWaiter
    • XTaskQueueSetCurrentProcessTaskQueue
    • XTaskQueueSubmitCallback
    • XTaskQueueSubmitDelayedCallback
    • XTaskQueueTerminate
    • XTaskQueueUnregisterMonitor
    • XTaskQueueUnregisterWaiter
  • XThread
    • XThreadIsTimeSensitive
    • XThreadSetTimeSensitive
    • XThreadAssertNotTimeSensitive
  • XUser
    • XUserDuplicateHandle
    • XUserCloseHandle
    • XUserCompare
    • XUserGetMaxUsers
    • XUserAddAsync
    • XUserAddResult
    • XUserAddByIdWithUiAsync
    • XUserAddByIdWithUiResult
    • XUserGetId
    • XUserFindUserById
    • XUserGetLocalId
    • XUserFindUserByLocalId
    • XUserGetIsGuest
    • XUserGetState
    • XUserGetGamertag
    • XUserGetGamerPictureAsync
    • XUserGetAgeGroup
    • XUserCheckPrivilege
    • XUserResolvePrivilegeWithUiAsync
    • XUserResolvePrivilegeWithUiResult
    • XUserGetTokenAndSignatureUtf16Async
    • XUserResolveIssueWithUiUtf16Async
    • XUserResolveIssueWithUiUtf16Result
    • XUserRegisterForChangeEvent
    • XUserUnregisterForChangeEvent
    • XUserCloseSignOutDeferralHandle
    • XUserFindControllerForUserWithUiAsync
    • XUserFindControllerForUserWithUiResult
    • XUserFindForDevice
    • XUserGetDefaultAudioEndpointUtf16
    • XUserGetGamerPictureResultSize
    • XUserGetGamerPictureResult
    • XUserGetSignOutDeferral
    • XUserGetTokenAndSignatureAsync
    • XUserGetTokenAndSignatureResultSize
    • XUserGetTokenAndSignatureResult
    • XUserGetTokenAndSignatureUtf16ResultSize
    • XUserGetTokenAndSignatureUtf16Result
    • XUserIsStoreUser
    • XUserRegisterForDefaultAudioEndpointUtf16Changed
    • XUserRegisterForDeviceAssociationChanged
    • XUserResolveIssueWithUiAsync
    • XUserResolveIssueWithUiResult
    • XUserUnregisterForDefaultAudioEndpointUtf16Changed
    • XUserUnregisterForDeviceAssociationChanged

관리형 래퍼에 포함된 XBOX 서비스 API 목록

다음 XBOX 서비스 API가 GDK Unity 패키지의 관리형 래퍼에 포함되어 있습니다. XBOX 서비스 API에 대한 자세한 내용은 XBOX Live API 레퍼런스를 참조하세요.

참고 API 문서

참고

PC 개발을 위한 Unity 시작하기
마지막 수정일 2026년 8월 24일