데스크톱 앱에서 지원되지 않는 Windows 런타임 API

  • 아티클

C# 또는 C++ 데스크톱 앱에서 대부분의 WinRT(Windows 런타임) API(Windows UWP 네임스페이스 참조)를 사용할 수 있지만 데스크톱 앱에서 지원되지 않거나 제한 사항이 있는 두 가지 주요 WinRT API 집합이 있습니다.

  • UWP(유니버설 Windows 플랫폼) 앱에서만 사용하도록 설계된 UI(사용자 인터페이스) 기능에 대한 종속성이 있는 API
  • 패키지 ID가 필요한 API(패키지 ID가 필요한 기능 참조). 이러한 API는 MSIX를 사용하여 패키징된 데스크톱 앱에서만 지원됩니다.

이 문서에서는 이러한 WinRT API 세트에 대한 세부 정보를 제공합니다. 사용할 수 있는 경우, 이 문서는 데스크톱 앱에서 지원되지 않는 API와 동일한 기능을 구현하는 대체 API를 제안합니다. WinUI 3 또는 Windows SDK에서 사용할 수 있는 WinRT COM 인터페이스를 통해 대부분의 대체 API를 사용할 수 있습니다.

참고

.NET을 사용하는 앱은 이 문서에 나열된 일부 WinRT COM 인터페이스에 대해 제공된 클래스 구현을 사용할 수 있습니다. 이러한 클래스는 WinRT COM 인터페이스를 직접 사용하는 것보다 작업하기 쉽습니다. 사용 가능한 클래스 구현에 대한 자세한 내용은 .NET 앱에서 interop API 호출을 참조하세요. 이러한 클래스에는 .NET 6 SDK 이상이 필요합니다.

이 문서는 더 많은 해결책 및 대체 방안이 확인되면 업데이트됩니다. 여기에 나열되지 않은 API에 문제가 발생하는 경우, 해당 API 이름과 구현하고자 하는 내용에 대한 세부 정보를 포함하여 microsoft-ui-xaml 리포지토리에 문제를 만드세요.

UWP 전용 UI 기능에 종속된 API

일부 WinRT API는 UWP 앱의 UI 시나리오를 위해 특별히 디자인되었습니다. 이러한 API는 스레딩 모델 및 기타 플랫폼 차이로 인해 데스크톱 앱에서 제대로 작동하지 않습니다. 이러한 API 및 종속성이 있는 다른 WinRT API는 데스크톱 앱에서 사용할 수 없습니다.

코어 지원되지 않는 클래스

이러한 WinRT 클래스는 데스크톱 앱에서 지원되지 않습니다.

클래스 대체 API
ApplicationView 아니요
CoreApplicationView WinUI 3에서 제공하는 Window 클래스를 대신 사용합니다.
CoreApplicationViewTitleBar ExtendViewIntoTitleBar 속성 대신 WinUI 3에서 제공하는 Window.ExtendsContentIntoTitleBar 속성을 사용합니다.
CoreDispatcher 대신 WinUI 3에서 제공하는 Microsoft.UI.Xaml.Window.DispatcherQueue 속성을 사용합니다.

Windows.UI.Xaml.Window.Dispatcher 및 Windows.UI.Xaml.DependencyObject.Dispatcher 속성은 데스크톱 앱에서 null을 반환합니다.
CoreWindow 또한 아래 IInitializeWithWindow를 구현하는 클래스 섹션을 참조하세요.

GetKeyState 메서드 대신 WinUI 3에서 제공하는 InputKeyboardSource.GetKeyStateForCurrentThread 메서드를 사용합니다.

PointerCursor 속성 대신 WinUI 3에서 제공하는 UIElement.ProtectedCursor 속성을 대신 사용합니다. 이 속성에 액세스하려면 UIElement의 서브클래스가 있어야 합니다.
UserActivity 대신 IUserActivitySourceHostInterop COM 인터페이스를 사용합니다(useractivityinterop.h에 있음).

데스크톱 앱에서 지원되지 않는 다른 WinRT API는 이 토픽의 뒷부분에 나오는 지원되지 않는 멤버를 참조하세요.

XxxForCurrentView 메서드가 있는 클래스

대부분의 WinRT 클래스에는 UIViewSettings.GetForCurrentView와 같은 정적 GetForCurrentView 또는 CreateForCurrentView 메서드가 있습니다. 이러한 XxxForCurrentView 메서드는 데스크톱 앱에서 지원되지 않는 ApplicationView 유형에 대해 암시적 종속성이 있습니다. ApplicationView는 데스크톱 앱에서 지원되지 않으므로 XxxForCurrentView 메서드도 지원되지 않습니다. 지원되지 않는 일부 XxxForCurrentView 메서드는 null을(를) 반환할 뿐만 아니라, 예외도 throw합니다.

참고

CoreInputView.GetForCurrentView은(는) 데스크톱 앱에서 지원되며 CoreWindow 없이도 사용할 수 있습니다. 이 메서드를 사용하여 모든 스레드에서 CoreInputView 개체를 가져올 수 있으며, 해당 스레드에 전경 창이 있으면 해당 개체가 이벤트를 생성합니다.

데스크톱 앱에서 지원되는 클래스는 다음과 같습니다. 그러나 데스크톱 앱에서 인스턴스를 검색하려면 GetForCurrentView 또는 CreateForCurrentView 메서드와 다른 메커니즘을 사용합니다. 아래에서 COM 인터페이스가 대체 API로 나열된 클래스의 경우 C# 개발자는 이러한 WinRT COM 인터페이스도 사용할 수 있습니다(.NET 앱에서 interop API 호출 참조). 이 목록은 전체를 포괄하지 않을 수 있습니다.

클래스 대체 API
AccountsSettingsPane 대신 IAccountsSettingsPaneInterop COM 인터페이스를 사용합니다(accountssettingspaneinterop.h에 있음).
CoreDragDropManager 대신 IDragDropManagerInterop COM 인터페이스를 사용합니다(dragdropinterop.h에 있음).
CoreTextServicesManager 이 클래스는 현재 Windows Insider Preview 빌드에서만 데스크톱 앱에서 지원됩니다.
DataTransferManager 대신 IDataTransferManagerInterop COM 인터페이스를 사용합니다(shobjidl_core.h에 있음).
DisplayInformation DisplayInformation의 인스턴스를 검색하려면 IDisplayInformationStaticsInterop 인터페이스를 사용하십시오.

또는 LogicalDpi 속성 대신 XamlRoot.RasterizationScale 속성을 사용하고 XamlRoot.Changed 이벤트에 대한 변경 내용을 수신할 수 있습니다(WinUI 3에서 XamlRoot.RasterizationScale 속성이 제공됨).

그리고 RawPixelsPerViewPixel 속성 대신 WinUI 3에서 제공하는 XamlRoot.RasterizationScale 속성을 사용할 수 있습니다.
InputPane 대신 IInputPaneInterop COM 인터페이스를 사용합니다(inputpaneinterop.h에 있음).
PlayToManager 대신 IPlayToManagerInterop COM 인터페이스를 사용합니다(playtomanagerinterop.h에 있음).
Print3DManager 대신 IPrinting3DManagerInterop COM 인터페이스를 사용합니다(print3dmanagerinterop.h에 있음).
PrintManager 대신 IPrintManagerInterop COM 인터페이스를 사용합니다(printmanagerinterop.h에 있음).
RadialController 대신 IRadialControllerInterop COM 인터페이스를 사용합니다(radialcontrollerinterop.h에 있음).
RadialControllerConfiguration 대신 IRadialControllerConfigurationInterop COM 인터페이스를 사용합니다(radialcontrollerinterop.h에 있음).
ResourceContext MRT에서 MRT Core로 마이그레이션을 참조하세요.
ResourceLoader MRT에서 MRT Core로 마이그레이션을 참조하세요.
SpatialInteractionManager 대신 ISpatialInteractionManagerInterop COM 인터페이스를 사용합니다(spatialinteractionmanagerinterop.h에 있음).
SystemMediaTransportControls 대신 ISystemMediaTransportControlsInterop COM 인터페이스를 사용합니다(systemmediatransportcontrolsinterop.h에 있음).
UserActivityRequestManager 대신 IUserActivityRequestManagerInterop COM 인터페이스를 사용합니다(useractivityinterop.h에 있음).
UIViewSettings 대신 IUIViewSettingsInterop COM 인터페이스를 사용합니다(uiviewsettingsinterop.h에 있음).

다음 클래스는 GetForCurrentView 또는 CreateForCurrentView 메서드에 대한 대안을 제공하지 않으므로 데스크톱 앱에서 지원되지 않습니다. 이 목록은 전체를 포괄하지 않을 수 있습니다.

클래스 대체 API
AppCapture 아니요
BrightnessOverride 아니요
ConnectedAnimationService 아니요
CoreInputView 아니요
CoreWindowResizeManager 아니요
DisplayEnhancementOverride 아니요
EdgeGesture 아니요
GazeInputSourcePreview 아니요
HdmiDisplayInformation 아니요
HolographicKeyboardPlacementOverridePreview 아니요
KeyboardDeliveryInterceptor 아니요
LockApplicationHost 아니요
MouseDevice 아니요
PointerVisualizationSettings 아니요
ProtectionPolicyManager 아니요
SearchPane 아니요
SettingsPane 아니요
SystemNavigationManager 아니요
SystemNavigationManagerPreview 아니요
WebAuthenticationBroker 없음. 자세한 내용은 WebAuthenticationBroker.AuthenticateAsync throws COMException GitHub 문제를 참조하세요.

IInitializeWithWindow를 구현하는 클래스

특정 선택기, 팝업, 대화 상자 및 기타 WinRT(Windows 런타임) 개체는 CoreWindow에 따라 달라지며, 일반적으로 UI를 표시합니다. CoreWindow는 데스크톱 앱에서 지원되지 않지만(위의 Core 지원되지 않는 클래스 참조) 약간의 상호 운용 코드를 추가하여 데스크톱 앱에서 이러한 WinRT 클래스를 많이 사용할 수 있습니다.

자세한 정보(영향을 받는 형식 목록 포함) 및 코드 예제는 CoreWindow에 의존하는 WinRT UI 개체 표시를 참조하세요.

지원되지 않는 멤버

이 섹션에서는 데스크톱 앱 사용을 지원하지 않는 WinRT 클래스의 특정 멤버를 나열하거나(포괄적인 목록을 사용할 수 없는 경우) 설명합니다. 별도로 언급하지 않는 한, 이러한 멤버를 제외한 나머지 클래스는 데스크톱 앱에서 지원됩니다.

이벤트

다음 클래스는 지정된 이벤트를 제외한 후 데스크톱 앱에서 지원됩니다.

클래스 지원하지 않는 이벤트
UISettings ColorValuesChanged
AccessibilitySettings HighContrastChanged

메서드

다음 클래스는 지정된 메서드를 제외하고 데스크톱 앱에서 지원됩니다.

클래스 지원하지 않는 메서드
DeviceInformationPairing PairAsync

Request 이름 지정 패턴을 사용하는 메서드

AppCapability.RequestAccessAsync 및 StoreContext.RequestPurchaseAsync와 같이 Request 명명 패턴을 따르는 메서드는 데스크톱 앱에서 지원되지 않습니다. 내부적으로 이러한 메서드는 Windows.UI.Popups 클래스를 사용합니다. 이 클래스를 사용하려면 스레드에 데스크톱 앱에서 지원되지 않는 CoreWindow 개체가 있어야 합니다.

요청 명명 패턴을 따르는 메서드의 전체 목록은 매우 길며, 이 문서에서는 이러한 메서드의 포괄적인 목록을 제공하지 않습니다.

패키지 ID가 필요한 API

다음 WinRT 클래스는 패키지 ID가 필요합니다( 패키지 ID가 필요한 기능 참조). 이러한 API는 패키지된(즉, 런타임에 패키지 ID가 있는) 데스크톱 앱에서만 지원됩니다. 이 목록은 전체를 포괄하지 않을 수 있습니다.

또한 패키지 ID가 없는 데스크톱 앱에서 호출되는 경우 AdaptiveMediaSource.CreateFromUriAsync 메서드는 ms-appx 및 ms-resource URI 형식을 지원하지 않습니다.