API среды выполнения Windows, не поддерживаемые в классических приложениях

Хотя в классическом приложении C# или C++ можно использовать большинство api-интерфейсов среда выполнения Windows (см. разделы имен Windows UWP) в классическом приложении C# или C++, существует два основных набора API WinRT, которые не поддерживаются в классических приложениях или имеют ограничения:

  • API-интерфейсы, зависящие от функций пользовательского интерфейса (UI), которые были разработаны для использования только в приложении универсальной платформы Windows (UWP).
  • API, для которых требуется идентификатор пакета (см. статью Функции, для которых требуется идентификатор пакета). Такие API поддерживаются только в классических приложениях, которые упаковываются с помощью MSIX.

В этой статье приведены сведения об этих двух наборах API WinRT. В этой статье описаны альтернативные API для достижения той же функциональности, что и ИНТЕРФЕЙСы API, неподдерживаемые в классических приложениях. Большинство альтернативных API доступны в WinUI 3 или через COM-интерфейсы WinRT, предоставляемые в Windows SDK.

Примечание.

Приложения с поддержкой .NET могут использовать предоставленные реализации классов для некоторых COM-интерфейсов WinRT, перечисленных в этой статье. Проще работать с этими классами, чем использовать COM-интерфейсы WinRT напрямую. Дополнительные сведения о доступных реализациях классов см. в статье Вызов API взаимодействия из приложения .NET. Обратите внимание, что для этих классов требуется пакет SDK для .NET 6 или более поздней версии.

Эта статья будет обновляться по мере определения обходных путей и вариантов замены. Если у вас возникнет проблема с API, не описанная здесь, сообщите о ней в репозитории microsoft-ui-xaml, указав имя API и сведения о реализуемой функции с помощью этого API.

API-интерфейсы, зависящие от функций пользовательского интерфейса только для UWP

Ряд API-интерфейсов WinRT был разработан специально для сценариев пользовательского интерфейса в приложениях UWP. Эти API не работают должным образом в классических приложениях из-за потоковой модели и других различий платформ. Эти API и другие API WinRT, имеющие зависимости от них, не поддерживаются для использования в классических приложениях.

Основные неподдерживаемые классы

Эти классы WinRT не поддерживаются в классических приложениях:

Класс Альтернативные API
ApplicationView нет
CoreApplicationView Используйте вместо него класс Window, предоставляемый в WinUI 3.
CoreApplicationViewTitleBar Вместо свойства ExtendViewIntoTitleBar используйте свойство Window.ExtendsContentIntoTitleBar, предоставляемое в WinUI 3.
CoreDispatcher Вместо этого используйте свойство Microsoft.UI.Xaml.Window.DispatcherQueue, предоставляемое WinUI 3.

Обратите внимание, что свойства Windows.UI.Xaml.Window.Dispatcher и Windows.UI.Xaml.DependencyObject.Dispatcher снова доступны null в классическом приложении.
CoreWindow См. также классы, реализующие IInitializeWithWindow в разделе ниже.

Вместо метода GetKeyState используйте метод InputKeyboardSource.GetKeyStateForCurrentThread, предоставляемый в WinUI 3.

Вместо свойства PointerCursor используйте свойство UIElement.ProtectedCursor, предоставляемое в WinUI 3. Для обращения к этому свойству требуется подкласс UIElement.
UserActivity Вместо него используйте COM-интерфейс IUserActivitySourceHostInteropuseractivityinterop.h).

Другие API WinRT, которые не поддерживаются в классических приложениях, см . в разделе "Неподдерживаемые участники " далее в этом разделе.

Классы с методом XxxForCurrentView

Многие классы WinRT имеют статический метод GetForCurrentView или CreateForCurrentView, например UIViewSettings.GetForCurrentView. Эти методы XxxForCurrentView имеют неявную зависимость от типа ApplicationView, который не поддерживается в классических приложениях. Так как ApplicationView не поддерживается в классических приложениях, ни один из методов XxxForCurrentView не поддерживается. Некоторые неподдерживаемые методы XxxForCurrentView не только возвращают null, но и вызывают исключения.

Примечание.

CoreInputView.GetForCurrentViewподдерживается в классических приложениях, и его можно использовать даже без CoreWindow. Этот метод можно использовать для получения объекта CoreInputView в любом потоке. Если этот поток имеет окно переднего плана, объект будет создавать события.

Следующие классы поддерживаются в классических приложениях. Но для получения экземпляра одного из них в классическом приложении используется механизм, отличный от методов GetForCurrentView или CreateForCurrentView. Для приведенных ниже классов, для которых COM-интерфейс указан в качестве альтернативного API, разработчики C# также могут использовать эти COM-интерфейсы WinRT (см. статью Вызов API взаимодействия из приложения .NET). Этот список может быть неполным.

Класс Альтернативные API
Учетные записи Параметры Pane Вместо него используйте COM-интерфейс IAccountsSettingsPaneInteropaccountssettingspaneinterop.h).
CoreDragDropManager Вместо этого используйте COM-интерфейс IDragDropManagerInteropdragdropinterop.h).
CoreTextServicesManager Этот класс сейчас поддерживается в классических приложениях только в предварительных сборках для участников программы предварительной оценки Windows.
DataTransferManager Вместо этого используйте COM-интерфейс IDataTransferManagerInteropshobjidl_core.h).
DisplayInformation Чтобы получить экземпляр DisplayInformation, используйте интерфейс IDisplayInformationStaticsInterop.

В качестве альтернативы вместо свойства LogicalDpi вы можете использовать свойство XamlRoot.RasterizationScale и прослушивать изменения в событии XamlRoot.Changed (свойство XamlRoot.RasterizationScale предоставляется в WinUI 3).

Также вместо свойства RawPixelsPerViewPixel вы можете использовать свойство XamlRoot.RasterizationScale, предоставляемое в WinUI 3.
InputPane Вместо этого используйте COM-интерфейс IInputPaneInteropinputpaneinterop.h).
PlayToManager Вместо этого используйте COM-интерфейс IPlayToManagerInteropplaytomanagerinterop.h).
Print3DManager Вместо этого используйте COM-интерфейс IPrinting3DManagerInteropprint3dmanagerinterop.h).
PrintManager Вместо этого используйте COM-интерфейс IPrintManagerInteropprintmanagerinterop.h).
RadialController Вместо этого используйте COM-интерфейс IRadialControllerInteropradialcontrollerinterop.h).
RadialControllerConfiguration Вместо этого используйте COM-интерфейс IRadialControllerConfigurationInteropradialcontrollerinterop.h).
ResourceContext См. статью Переход с MRT на MRT Core.
ResourceLoader См. статью Переход с MRT на MRT Core.
SpatialInteractionManager Вместо этого используйте COM-интерфейс ISpatialInteractionManagerInteropspatialinteractionmanagerinterop.h).
SystemMediaTransportControls Вместо этого используйте COM-интерфейс ISystemMediaTransportControlsInteropsystemmediatransportcontrolsinterop.h).
UserActivityRequestManager Вместо этого используйте COM-интерфейс ISpatialInteractionManagerInteropuseractivityinterop.h).
UIViewSettings Вместо этого используйте COM-интерфейс IUIViewSettingsInteropuiviewsettingsinterop.h).

Следующие классы не поддерживаются в классических приложениях, так как API не предоставляют альтернативу их методу GetForCurrentView или CreateForCurrentView. Этот список может быть неполным.

Класс Альтернативные API
AppCapture нет
BrightnessOverride нет
Подключение edAnimationService нет
CoreInputView нет
CoreWindowResizeManager нет
DisplayEnhancementOverride нет
EdgeGesture нет
GazeInputSourcePreview нет
HdmiDisplayInformation нет
HolographicKeyboardPlacementOverridePreview нет
KeyboardDeliveryInterceptor нет
LockApplicationHost нет
MouseDevice нет
PointerVisualizationSettings нет
ProtectionPolicyManager нет
SearchPane нет
SettingsPane нет
SystemNavigationManager нет
SystemNavigationManagerPreview нет
WebAuthenticationBroker Нет. Дополнительные сведения см. в статье WebAuthenticationBroker.AuthenticateAsync создает COMException на сайте GitHub.

Классы, реализующие IInitializeWithWindow

Определенные средства выбора, всплывающие окна, диалоговые окна и другие объекты среды выполнения Windows (WinRT) зависят от CoreWindow; обычно для вывода пользовательского интерфейса. Несмотря на то, что CoreWindow не поддерживается в настольных приложениях (см. раздел Основные неподдерживаемые классы выше), вы по-прежнему можете использовать многие из этих классов WinRT в классическом приложении, добавив небольшой код взаимодействия.

Дополнительные сведения (включая список затронутых типов) и примеры кода см. в статье Отображение объектов пользовательского интерфейса WinRT, зависящих от CoreWindow.

Неподдерживаемые элементы

В этом разделе перечислены (или описаны, если исчерпывающий список недоступен) определенные элементы классов WinRT, которые не поддерживаются в классических приложениях. Если не указано иное, другие классы поддерживаются в классических приложениях.

События

Следующие классы поддерживаются в классических приложениях, за исключением указанных событий.

Класс Неподдерживаемые события
UISettings ColorValuesChanged
Специальные возможности Параметры HighContrastChanged

Методы

Следующие классы поддерживаются в классических приложениях, за исключением указанных методов.

Класс Неподдерживаемые методы
DeviceInformationPairing PairAsync

Методы, которые используют шаблон именования Request

Большинство методов, которые следуют шаблону именования запросов, например AppCapability.RequestAccessAsync и StoreContext.RequestPurchaseAsync, не поддерживаются в классических приложениях. На внутреннем уровне эти методы используют класс Windows.UI.Popups. Для этого класса требуется, чтобы поток был объектом CoreWindow , который не поддерживается в классических приложениях.

Полный список методов, которые используют шаблон именования Request, очень длинный и в этой статье не представлен.

API, требующие наличия идентификатора пакета

Для следующих классов WinRT требуется идентификатор пакета (см. статью Функции, для которых требуется идентификатор пакета). Эти API поддерживаются только в классических приложениях, которые упаковываются (т. е. имеют удостоверение пакета во время выполнения). Этот список может быть неполным.

Кроме того, при вызове из классического приложения, не имеющего идентификатора пакета, методы AdaptiveMediaSource.CreateFromUriAsync не поддерживают форматы URI ms-appx и ms-resource.