Версионно адаптивный код

Вы можете подумать о написании адаптивного кода аналогично тому, как вы думаете о создании адаптивного пользовательского интерфейса. Создайте базовый код для запуска в самой низкой версии ОС, а затем добавьте функции при обнаружении того, что приложение работает в более поздней версии, где доступна новая функция.

Дополнительные сведения о ApiInformation, контрактах API и настройке Visual Studio см. в статье Приложения с адаптацией к версии.

Необходимые условия

Проверки API среды выполнения

Используйте класс Windows.Foundation.Metadata.ApiInformation в условном выражении кода, чтобы проверить наличие API, который вы хотите вызвать. Это условие вычисляется везде, где работает ваше приложение, но принимает значение true только на устройствах, где API присутствует и доступен для использования.

Important

ApiInformationПроверки работают только для типов среда выполнения Windows в пространстве имен Windows.*. Они не обнаруживают типы WinUI (Microsoft.UI.Xaml.*), так как эти типы являются частью пакета платформы Windows App SDK, а не операционной системы и не регистрируются в качестве метаданных WinRT, которые ApiInformation могут запрашивать. #if Директивы препроцессора здесь тоже не помогают — они вычисляются во время компиляции на основе целевой платформы, а не во время выполнения на основе ОС или версии SDK, под которыми фактически запущено приложение. Чтобы условно включить возможность WinUI, проверьте, для какой версии Windows App SDK было собрано ваше приложение (см. приложения с адаптацией по версии), или оберните вызов в блок try/catch и используйте резервный вариант, если во время выполнения он завершится ошибкой.

Tip

Многочисленные проверки API среды выполнения могут повлиять на производительность приложения. Выполните проверку один раз и кэшируйте результат, а затем используйте кэшированный результат во всем приложении.

Параметры адаптивного кода

Существует два способа создания адаптивного кода:

  • Код приложения — Используйте проверки API во время выполнения в коде программной части. Это рекомендуемый подход для большинства сценариев.
  • Триггеры состояния — используйте расширяемые триггеры состояния, которые активируют визуальные состояния на основе присутствия API. Используйте триггеры состояния, если между версиями ОС есть простое различие в свойстве или значении перечисления, связанное с визуальным состоянием.

Пример. Проверка значения перечисления

В этом примере показано, как проверить, содержится ли определённое значение перечисления, прежде чем использовать его. Если значение отсутствует, код использует альтернативный вариант. EnergySaverStatus и PowerManager являются подлинными типами среда выполнения Windows в пространстве имён Windows.System.Power, поэтому ApiInformation может корректно выполнять к ним запросы.

if (ApiInformation.IsEnumNamedValuePresent(
    "Windows.System.Power.EnergySaverStatus", "On"))
{
    if (PowerManager.EnergySaverStatus == EnergySaverStatus.On)
    {
        // Reduce background work to save battery.
        ReduceBackgroundActivity();
    }
}
else
{
    // Energy Saver status isn't available on this OS version; skip the check.
}

void ReduceBackgroundActivity()
{
    // Pause non-essential timers, syncs, and animations here.
}

Important

При кэшировании результата проверки API используйте это кэшированное значение последовательно во всем приложении. Не повторяйте проверку в нескольких местах — проверьте один раз, сохраните результат и используйте его везде.

Пример. Проверка метода

Используйте IsMethodPresent для проверки доступности определенного метода перед вызовом:

DisplayRequest displayRequest = new DisplayRequest();

if (ApiInformation.IsMethodPresent(
    "Windows.System.Display.DisplayRequest", "RequestActive"))
{
    displayRequest.RequestActive();
}

Пример: Проверка наличия свойства

Используйте IsPropertyPresent для проверки доступности определенного свойства перед его чтением:

if (ApiInformation.IsPropertyPresent(
    "Windows.System.Power.PowerManager", "RemainingChargePercent"))
{
    int chargePercent = PowerManager.RemainingChargePercent;
}

Лучшие практики

Практика Guidance
Использование статических строк При проверке имён API с помощью ApiInformation используйте строковые литералы, а не рефлексию .NET, чтобы избежать проблем с загрузкой типов во время выполнения.
Результаты кэширования Выполните проверку каждого API один раз при запуске и сохраните результат повторного использования
Сохранение минимальной версии Установите минимальную версию проекта настолько низкой, насколько это целесообразно, чтобы охватить максимально широкую аудиторию, и используйте адаптивный код, чтобы задействовать возможности в более новых версиях ОС
Проверка на минимальную версию Всегда тестируйте минимальную поддерживаемую версию ОС, чтобы убедиться, что резервные пути работают правильно.

Связанные материалы

  • Last updated on