Código adaptativo de versiones

Puede pensar en escribir código adaptable de forma similar a cómo piensa en crear una interfaz de usuario adaptable. Diseñe el código base para que se ejecute en la versión más baja del sistema operativo y agregue características cuando detecte que la aplicación se ejecuta en una versión superior en la que hay disponible una nueva característica.

Para obtener información general sobre ApiInformation, los contratos de API y la configuración de Visual Studio, consulte Aplicaciones adaptables a la versión.

Prerequisites

  • Un proyecto de SDK de Aplicaciones para Windows (empaquetado o desempaquetado). Consulta Inicio rápido: Creación de la primera aplicación winUI 3.
  • Familiaridad con el sistema de tipos de Windows Runtime (WinRT), ya que las comprobaciones de ApiInformation solo se aplican a los tipos del espacio de nombres Windows.*.

Comprobaciones de API en tiempo de ejecución

Use la clase Windows.Foundation.Metadata.ApiInformation en una condición de su código para comprobar si está presente la API que desea invocar. Esta condición se evalúa allí donde se ejecute tu aplicación, pero solo da como resultado true en los dispositivos en los que la API está presente y se puede llamar.

Importante

ApiInformation las comprobaciones solo funcionan para tipos de Windows Runtime en el espacio de nombres Windows.*. No detectan tipos de WinUI (Microsoft.UI.Xaml.*) porque esos tipos forman parte del paquete de marco de SDK de Aplicaciones para Windows, no del sistema operativo y no están registrados como metadatos de WinRT que ApiInformation pueden consultar. #if Las directivas de preprocesador no ayudan aquí, ya que se evalúan en tiempo de compilación en función de la plataforma de destino, no en tiempo de ejecución en función del sistema operativo o la versión del SDK en la que la aplicación se está ejecutando realmente. Para habilitar una funcionalidad de WinUI de forma condicional, compruebe la versión de SDK de Aplicaciones para Windows con la que se compiló la aplicación (consulte Aplicaciones con adaptación de versión) o encapsule la llamada en un bloque try/catch y recurra a una alternativa si falla en tiempo de ejecución.

Tip

Numerosas comprobaciones de API en tiempo de ejecución pueden afectar al rendimiento de la aplicación. Realice la comprobación una vez y almacene en caché el resultado y, a continuación, use el resultado almacenado en caché en toda la aplicación.

Opciones de código adaptable

Hay dos maneras de crear código adaptable:

  • Código de aplicación : use comprobaciones de API en tiempo de ejecución en el código subyacente. Este es el enfoque recomendado para la mayoría de los escenarios.
  • Desencadenadores de estado: use desencadenadores de estado extensibles que activan estados visuales en función de la presencia de una API. Use desencadenadores de estado cuando tenga una propiedad simple o un cambio de enumeración entre versiones del sistema operativo conectadas a un estado visual.

Ejemplo: Comprobación de un valor de enumeración

En este ejemplo se muestra cómo comprobar si hay un valor de enumeración específico antes de usarlo. Si el valor no está presente, el código vuelve a una alternativa. EnergySaverStatus y PowerManager son tipos genuinos de Windows Runtime en el espacio de nombres Windows.System.Power, por lo que ApiInformation puede consultarlos correctamente.

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.
}

Importante

Al almacenar en caché el resultado de una comprobación de API, use ese valor almacenado en caché de forma coherente en toda la aplicación. No repita la comprobación en varios lugares: compruebe una vez, almacene el resultado y haga referencia a él en todas partes.

Ejemplo: Comprobación de un método

Use IsMethodPresent para comprobar que un método específico está disponible antes de llamarlo:

DisplayRequest displayRequest = new DisplayRequest();

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

Ejemplo: Comprobación de una propiedad

Use IsPropertyPresent para comprobar que una propiedad específica está disponible antes de leerla:

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

Prácticas recomendadas

Práctica Instrucciones
Uso de cadenas estáticas Al comprobar los nombres de API con ApiInformation, utilice cadenas codificadas de forma fija en lugar de la reflexión de .NET para evitar problemas de carga de tipos durante la ejecución.
Resultados de caché Realizar cada comprobación de API una vez al inicio y almacenar el resultado para su reutilización
Mantener la versión mínima baja Establezca la versión mínima del proyecto tan baja como práctica para llegar al público más amplio y usar código adaptable para iluminar las características de las versiones más recientes del sistema operativo.
Prueba en la versión mínima Realice siempre pruebas en la versión mínima compatible del sistema operativo para verificar que los mecanismos alternativos funcionen correctamente.

Contenido relacionado

  • Last updated on