Descripción de las distintas versiones del SDK de WebView2

  • Artículo

El SDK de WebView2 se proporciona como versión preliminar o versión preliminar del paquete NuGet Microsoft.Web.WebView2 . Use un SDK de versión preliminar con un canal de versión preliminar de Microsoft Edge o use un SDK de versión con El entorno de ejecución de WebView2.

Prelanzamiento Los paquetes de SDK se usan durante el desarrollo si desea probar las API WebView2 más recientes, incluidas las API experimentales, antes de agregar compatibilidad con esas API al entorno de ejecución. Se recomienda el canal Canary, ya que tiene las implementaciones de las API más recientes. Cuando quiera probar y usar las API webview2 experimentales, use la siguiente combinación:

  • Una versión preliminar del SDK de WebView2.
  • Un canal de versión preliminar de Microsoft Edge en el cliente de desarrollo.

Lanzamiento Los paquetes del SDK solo contienen API estables, no API experimentales. Cuando trabaje en una versión de producción de la aplicación WebView2, use la siguiente combinación:

  • Una versión de versión del SDK de WebView2.
  • El entorno de ejecución de WebView2 en el cliente de desarrollo.

A continuación se proporcionan más detalles sobre los paquetes del SDK de versión preliminar y versión preliminar.

Fases de introducción de las API

Las nuevas API se introducen en fases como se indica a continuación:

Estado de la API Descripción
Experimental 1. En primer lugar, una API es experimental en un SDK de versión preliminar. Puede probar estas API y proporcionar comentarios. La API aún no está en un SDK de versión.
Estable en un SDK de versión preliminar 2. A continuación, la API se promueve a Estable en el SDK de versión preliminar. La API aún no está en un SDK de versión.
Estable en un SDK de versión 3. A continuación, se promueve la API estable para que se incluya en el SDK de versión. Esto suele ocurrir 1 mes después de que la API se promueva a Estable en un SDK de versión preliminar. La API también permanece en el SDK de versión preliminar.

Diagrama de fases de introducción de nuevas API

Selección del tipo de SDK que se va a usar

Para seleccionar la versión del paquete NuGet del SDK de WebView2 que usa un proyecto de Visual Studio, en Visual Studio, haga clic con el botón derecho en un proyecto, seleccione Administrar paquetes NuGet, seleccione o desactive la casilla Incluir versión preliminar , seleccione el paquete Microsoft.Web.WebView2 y, a continuación, en la lista desplegable Versión , seleccione una versión del paquete NuGet Microsoft.Web.WebView2 .

Para obtener más información, consulte Instalación o actualización del SDK de WebView2 en Configuración del entorno de desarrollo para WebView2. También puede ver la lista de paquetes del SDK Microsoft.Web.WebView2 en el sitio de NuGet.

Uso de una versión preliminar del SDK junto con un canal de versión preliminar de Microsoft Edge

Al desarrollar una aplicación Evergreen WebView2, pruebe periódicamente la aplicación con el canal de versión preliminar de Microsoft Edge más reciente, además de realizar pruebas en el entorno de ejecución de WebView2. Dado que la plataforma web está en constante evolución, las pruebas regulares son la mejor manera de garantizar que la aplicación seguirá funcionando según lo previsto.

Cuando use un paquete de SDK de versión preliminar de WebView2, use un canal de versión preliminar de Microsoft Edge en el cliente de desarrollo. Los canales de vista previa también se denominan canales Insiders . Se recomienda el canal de versión preliminar Canary en lugar de Beta o Dev, ya que Canary es el más reciente y tiene implementaciones de las API experimentales más recientes.

El paquete del SDK de versión preliminar es un superconjunto del paquete del SDK de versión. Un SDK de versión preliminar contiene firmas de método para:

  • API experimentales.
  • API estables que ya no son experimentales, pero que aún no se han incluido en un SDK de versión.
  • API estables que se han agregado a los SDK de versión.

Los canales de versión preliminar de Microsoft Edge proporcionan las implementaciones de las API WebView2 experimentales y de las API estables. Las API experimentales están sujetas a cambios en función de los comentarios. Evite usar un paquete de SDK de versión preliminar para compilar aplicaciones de producción.

Para obtener información sobre cómo apuntar temporalmente la aplicación a un canal de vista previa en lugar de usar el entorno de ejecución de WebView2 de forma predeterminada, consulte Probar las próximas API y características.

Uso de una versión de versión del SDK junto con el entorno de ejecución

Cuando use un paquete del SDK de versión de WebView2, use el entorno de ejecución De Perenne WebView2 en el cliente de desarrollo, en lugar de un canal de versión preliminar de Microsoft Edge. De forma predeterminada, una aplicación WebView2 tiene como destino el entorno de ejecución en lugar de Microsoft Edge. Por diseño, el canal estable de Microsoft Edge no admite WebView2.

El paquete del SDK de versión contiene todas las API estables de C/C++ y .NET de Win32 que están en versión de producción y no incluyen firmas de método para las API experimentales. Todas las API que se encuentran en un paquete del SDK de versión son totalmente compatibles, en un número de compilación igual o superior del entorno de ejecución de WebView2.

El paquete del SDK de versión contiene los siguientes componentes:

Para obtener más información sobre la actualización automática del runtime de Evergreen, consulte Distribución de la aplicación y el entorno de ejecución de WebView2.

Cadencia de versión

Las nuevas versiones del SDK de WebView2 se incluyen con la misma cadencia general que el explorador Microsoft Edge, que es aproximadamente cada cuatro semanas.

Versión mínima y número de compilación para crear una instancia de WebView2

Para que el cliente pueda crear una instancia de WebView2 y usar el conjunto de API en la versión de disponibilidad general de WebView2 (compilación 616 del SDK), el cliente debe tener WebView2 Runtime versión 86.0.616.0 o posterior. Runtime 86.0.616.0 es una versión especial, ya que es la versión de disponibilidad general.

En una máquina de desarrollo, el cliente debe tener la versión 86.0.616.0 o posterior del canal de versión preliminar de Microsoft Edge, o bien la versión 86.0.616.0 o posterior de WebView2 Runtime.

Compatibilidad directa de las API

El SDK de la versión WebView2 ha sido compatible con el reenvío desde la versión 1 (SDK de versión 1.0.622.22 en las notas de la versión archivadas del SDK de WebView2). Puede actualizar la aplicación WebView2 para usar las API más recientes de la versión más reciente del SDK. La aplicación seguirá funcionando en los clientes porque los clientes tienen automáticamente la versión más reciente de WebView2 Evergreen Runtime.

Las API webView2 de un paquete del SDK de versión son estables y compatibles con el reenvío. Una API WebView2 funciona cuando se usa un entorno de ejecución de WebView2 que tiene un número de compilación igual o superior como el número de compilación del SDK en el que se introdujo la API. El número de compilación es la tercera parte del número de versión de cuatro partes para el SDK de Webview2 y del número de versión de cuatro partes para Microsoft Edge y webView2 Runtime.

  • Cuando se usa un SDK de WebView2 que tiene un número de compilación igual o menor que el entorno de ejecución de WebView2, todas las API a las que tiene acceso en ese SDK funcionan con esa versión del runtime.

  • Cuando se usa un SDK de WebView2 que tiene un número de compilación mayor que el tiempo de ejecución de WebView2, las implementaciones de las API más recientes no están disponibles en tiempo de ejecución.

Por ejemplo, si se introduce una API en SDK 1.0. 900.0, esa API funcionaría con Runtime 94.0. 900+.0, pero no con Runtime 90.0. 700.0.

Debe coordinar la versión del SDK de WebView2 que se usa para el desarrollo y la versión en tiempo de ejecución de WebView2 instalada en las máquinas cliente. El cliente debe tener una versión del entorno de ejecución que admita todas las API más recientes que se encuentran en la versión del SDK que se usa para desarrollar la aplicación. Para obtener compatibilidad completa con las API más recientes en una versión de versión del SDK, el entorno de ejecución en el cliente debe tener un número de compilación mayor o igual que el número de compilación del SDK.

API experimentales

Para probar las nuevas características que están en desarrollo, use las API experimentales . Las API experimentales se encuentran en los SDK de versión preliminar, pero no en los SDK de versión.

Desarrollo con API experimentales y comentarios

No se garantiza que las API experimentales de un paquete de SDK de versión preliminar de WebView2 sean compatibles con el reenvío y se podrían quitar en futuras actualizaciones en tiempo de ejecución.

Para obtener compatibilidad completa con las API experimentales, use un canal de vista previa de Microsoft Edge, no webView2 Evergreen Runtime. Cuando una versión preliminar del SDK de WebView2 está disponible inicialmente, ese SDK solo funciona con Microsoft Edge Canary. Poco después, el SDK de versión preliminar también funciona con los canales Beta y Dev.

Use un SDK de versión preliminar para probar las NUEVAS API experimentales en un primer tiempo y proporcionar comentarios antes de que las API experimentales se promuevan para convertirse en API estables y compatibles con el avance.

  • No se garantiza que las API experimentales (en un SDK de versión preliminar) sean compatibles con el reenvío.
  • Las API estables que se encuentran en un SDK de versión preliminar son compatibles con el avance, incluso si aún no están incluidas en un SDK de versión.
  • Las API estables que se encuentran en un SDK de versión son compatibles con el reenvío.

Para obtener más información, consulte Compatibilidad con reenvío de API, anteriormente.

El equipo de WebView2 está buscando comentarios sobre las API experimentales de WebView2 que podrían promoverse a Estable en futuras versiones. Las API experimentales se indican como "experimentales" en la documentación de referencia del SDK de WebView2, como: "Nota: Esta es una API experimental que se incluye con nuestro SDK de versión preliminar".

Para ayudarle a evaluar las API experimentales y compartir sus comentarios, use el repositorio WebView2Feedback .

Pasar de api experimentales a API estables

Una vez que se ha movido una API del estado Experimental a Estable, debe mover el código de la aplicación a la API estable. No se recomienda usar API experimentales o un SDK de versión preliminar para aplicaciones de producción. Siga estos procedimientos al pasar de usar las API experimentales de la aplicación al uso de API estables:

  • En el proyecto de Visual Studio, actualice la versión del paquete del SDK de WebView2 a un SDK de versión preliminar más reciente o un SDK de versión preliminar. Consulte Instalación o actualización del SDK de WebView2 en Configuración del entorno de desarrollo para WebView2.

  • Actualice el código de la aplicación para usar LAS API estables en lugar de las API experimentales (para COM). La API estable se admitirá con correcciones de errores, pero la API experimental estará en desuso y no estará disponible en el SDK más reciente (versión preliminar o versión preliminar). Una vez que una API se promueve a Estable, la versión experimental de esa API se admite para dos versiones del SDK de versión preliminar, en un estado en desuso. En versiones posteriores del SDK de versión preliminar, las API experimentales pueden modificarse, quitarse o agregarse.

  • Use siempre la detección de características para asegurarse de que la API estable se implementa en la versión del usuario del entorno de ejecución de WebView2. Consulte Detección de características para probar si el entorno de ejecución instalado admite las API agregadas recientemente, a continuación.

  • Nota solo para .NET: en un SDK de WebView2 de versión preliminar, las API estables de .NET se reservarán a las API experimentales correspondientes, si el runtime de WebView2 del usuario solo tiene la implementación de la API experimental y no tiene la implementación de API estable.

Coincidencia de la versión en tiempo de ejecución con la versión del SDK

En el enfoque de distribución Evergreen, el entorno de ejecución WebView2 del cliente se actualiza automáticamente a la versión más reciente disponible. Sin embargo, un usuario o administrador de TI podría optar por evitar la actualización automática del entorno de ejecución de WebView2. El entorno de ejecución obsoleto resultante en el cliente puede provocar problemas de compatibilidad con la aplicación WebView2 actualizada que usa nuevas API de un SDK reciente.

En caso de que se impida la actualización del entorno de ejecución de WebView2 en el cliente, asegúrese de que conoce el número mínimo de compilación del entorno de ejecución de WebView2 que requiere la aplicación. Para ver o obtener las versiones más recientes de WebView2 Runtime, consulte Descarga del entorno de ejecución de WebView2 en la página WebView2 de Microsoft Edge en developer.microsoft.com. La versión mínima necesaria en tiempo de ejecución para admitir la versión de disponibilidad general del SDK (compilación 616) es anterior a la del entorno de ejecución más reciente. El entorno de ejecución más reciente admite todas las API que se encuentran en el SDK de versión más reciente.

Para comprobar la compatibilidad entre números de compilación específicos del SDK y el canal de versión preliminar en tiempo de ejecución o Microsoft Edge, consulte Notas de la versión del SDK de WebView2.

Detección de características para probar si el entorno de ejecución instalado admite las API agregadas recientemente

Si la aplicación usa Evergreen Runtime en lugar de Fixed Version, debe encapsular las llamadas a las API webView2 relativamente nuevas mediante QueryInterface o try-catch. Hay casos perimetrales en los que evergreen runtime de un cliente no es la compilación más reciente y, por lo tanto, está por detrás del número de compilación del SDK, ya que el Administración podría haber desactivado la actualización de WebView2 Runtime o el cliente podría estar sin conexión.

Al desarrollar una aplicación WebView2 con una versión reciente del SDK de WebView2, si usa una API agregada recientemente, debe probar o "detectar características" si esa API está presente en el entorno de ejecución de WebView2 instalado del cliente. La forma en que la aplicación prueba mediante programación la compatibilidad con api depende de la plataforma de codificación.

  • Win32 C/C++. Al solicitar la exportación CreateCoreWebView2Environment de DLL y cuando se ejecuta QueryInterface en cualquier CoreWebView2 objeto, pruebe un valor devuelto de E_NOINTERFACE. Ese valor devuelto probablemente indica que el entorno de ejecución WebView2 del cliente es una versión anterior que no admite esa interfaz.

    Para obtener un ejemplo de comprobación de la existencia de API webView2 específicas en tiempo de ejecución, busque try_query en AppWindow.cpp. Este archivo encapsula las llamadas API de WebView2 en la CHECK_FAILURE función de macro, definida en CheckFailure.h.

  • .NET y WinUI. Use try/catch y compruebe si hay una No such interface supported excepción al usar métodos, propiedades y eventos que se agregaron a versiones más recientes del SDK de WebView2. Esta excepción probablemente indica que el entorno de ejecución WebView2 del cliente es una versión anterior que no admite esa API.

Si el código determina que una API no está disponible en el entorno de ejecución de WebView2 instalado del cliente, debe proporcionar una reserva correcta para la característica asociada o informar al usuario de que debe actualizar el entorno de ejecución de WebView2 para usar la característica.

Esta técnica se muestra como un procedimiento recomendado de desarrollo de WebView2, en Prueba de si las API son compatibles con el entorno de ejecución de WebView2 instalado.