SDK de versión preliminar y de versión preliminar para WebView2

El SDK de WebView2 se proporciona como una versión preliminar o de lanzamiento del paquete NuGet Microsoft.Web.WebView2 . Se puede usar un SDK de versión preliminar con un canal de versión preliminar de Microsoft Edge o un SDK de versión preliminar con el tiempo de ejecución WebView2.

Versión preliminar Los paquetes de SDK se usarán durante el desarrollo si quieres probar las API de WebView2 más recientes, incluidas las experimentales, antes de agregar al tiempo de ejecución la compatibilidad con esas API. Se recomienda el canal Canary, porque tiene las implementaciones de las API más recientes. Cuando quiera probar y usar las API experimentales de WebView2, use la combinación siguiente:

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

Publicación Los paquetes de SDK solo contienen API estables, no experimentales. Cuando esté trabajando en una versión de producción de la aplicación WebView2, use la siguiente combinación:

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

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

Fases de la introducción de las API

Las nuevas API se introducen en fases de la siguiente manera:

Estado de la API Description
Experimental en un SDK de versión preliminar 1. En primer lugar, una API es experimental en un SDK de versión preliminar. (En ocasiones, las API omiten la fase experimental y se agregan directamente a un SDK estable en 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 incluirla en el SDK de versión. (En ocasiones, las API se promueven simultáneamente a Estable en un SDK de versión preliminar y a Estable en un SDK de versión). Esto suele ocurrir 1 mes después de que la API se promueve a Estable en un SDK de versión preliminar. La API también permanece en el SDK de la versión preliminar.

Diagrama de fases de introducción de nuevas API

Vea también:

Seleccionar el 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 y active 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, consulta Instalar o actualizar el SDK de WebView2 en Configuración del entorno de desarrollo para WebView2. También puede ver la lista de paquetes de SDK de Microsoft.Web.WebView2 en el sitio de NuGet.

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

Al desarrollar una aplicación WebView2 perenne, prueba con regularidad la aplicación en el canal de versión preliminar más reciente de Microsoft Edge, además de probarla en el tiempo de ejecución de WebView2. Dado que la plataforma web está en constante evolución, las pruebas periódicas son la mejor manera de garantizar que la aplicación seguirá funcionando según lo previsto.

Al usar 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 versión preliminar también se denominan canales de participantes de Insider . 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 SDK de versión preliminar es un superconjunto del paquete 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 experimentales de WebView2 y de las API estables. Las API experimentales están sujetas a cambios en función de los comentarios. Evite usar un paquete SDK de versión preliminar para crear 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 tiempo de ejecución de WebView2, consulte Cambiar a un canal de vista previa para probar las próximas API y características.

Vea también:

Usa una versión de lanzamiento del SDK junto con el motor de ejecución

Cuando uses un paquete SDK de versión de WebView2, usa el tiempo de ejecución Evergreen WebView2 en tu cliente de desarrollo, en lugar de un canal de vista previa de Microsoft Edge. De forma predeterminada, una aplicación WebView2 se dirige al tiempo de ejecución en lugar de Microsoft Edge. Por diseño, el canal estable de Microsoft Edge no es compatible con WebView2.

El paquete Release SDK contiene todas las API estables que están en versión de producción y no incluye firmas de métodos para las API experimentales. Todas las API que se encuentran en un paquete SDK de lanzamiento son totalmente compatibles, en un número de compilación igual o superior del tiempo de ejecución WebView2.

Vea también:

Para obtener más información acerca de la actualización automática del tiempo de ejecución Evergreen, consulta:

Cadencia de lanzamientos

Vea:

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

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

En un equipo de desarrollo, el cliente debe tener la versión 86.0.616.0 o posterior del canal de vista previa de Microsoft Edge, o bien la versión 86.0.616.0 o posterior del tiempo de ejecución de WebView2.

Compatibilidad posterior de las API

El SDK de versión de WebView2 ha sido compatible con versiones posteriores desde la versión 1 (SDK de versión 1.0.622.22, para el tiempo de ejecución 86 (19 de octubre de 2020) en las notas de la versión archivadas para el SDK de WebView2). Puedes actualizar la aplicación WebView2 para usar las API más recientes de la versión de lanzamiento más reciente del SDK. La aplicación seguirá funcionando en clientes porque los clientes tienen automáticamente el tiempo de ejecución Evergreen WebView2 más reciente.

Las API de WebView2 de un paquete SDK de versión son estables y compatibles con versiones posteriores. Una API WebView2 funciona cuando se usa un tiempo de ejecución WebView2 que tiene un número de compilación igual o superior al 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 del SDK de Webview2 y del número de versión de cuatro partes de Microsoft Edge y el tiempo de ejecución de WebView2.

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

  • Cuando usas 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 el 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 el tiempo de ejecución 90.0. 700.0.

Debes coordinar la versión del SDK de WebView2 que usas para el desarrollo y la versión del entorno de ejecución de WebView2 instalada en los equipos cliente. El cliente debe tener una versión del tiempo de ejecución que admita todas las API más recientes que se encuentran en la versión del SDK que usa para desarrollar la aplicación. Para obtener compatibilidad completa con las API más recientes en una versión de lanzamiento del SDK, el tiempo de ejecución del 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 incluyen en los SDK de versión preliminar, pero no en los SDK de versión.

Desarrollar con API experimentales y proporcionar comentarios

No se garantiza que las API experimentales de un paquete de SDK de versión preliminar de WebView2 sean compatibles con versiones posteriores y podrían eliminarse en futuras actualizaciones del entorno de ejecución.

Para obtener compatibilidad completa con las API experimentales, use un canal de versión preliminar de Microsoft Edge, no el tiempo de ejecución Evergreen WebView2. Cuando inicialmente se pone a disposición una versión preliminar del SDK de WebView2, ese SDK solo funciona con Microsoft Edge Canary. Poco después, el SDK de la versión preliminar también funcionará con los canales Beta y Dev.

Utilice un SDK de versión preliminar para probar las API experimentales nuevas de forma anticipada y proporcionar comentarios antes de que se promueva la API experimental para que se conviertan en API estables y compatibles con versiones posteriores.

  • No se garantiza que las API experimentales (en un SDK de versión preliminar) sean compatibles con versiones posteriores.
  • Las API estables que se encuentran en un SDK de versión preliminar son compatibles con versiones posteriores, incluso si aún no se incluyen en un SDK de lanzamiento.
  • Las API estables que se encuentran en un SDK de versión son compatibles con versiones posteriores.

Para obtener más información, consulte Compatibilidad directa de las API, más arriba.

El equipo de WebView2 está buscando comentarios sobre las API experimentales de WebView2 que podrían promoverse a Estable en versiones futuras. 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 .

Vea también:

Pasar de API experimentales a API estables

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

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

  • Actualiza el código de la aplicación para que use API estables en lugar de API experimentales (para COM). La API estable será compatible con correcciones de errores, pero la API experimental quedará en desuso y no estará disponible en el SDK más reciente (versión preliminar o de lanzamiento). Después de promover una API a estable, la versión experimental de dicha API es compatible con dos versiones del SDK de versión preliminar, en estado obsoleto. En versiones posteriores del SDK de versión preliminar, las API experimentales se pueden modificar, quitar o agregar.

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

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

Hacer coincidir la versión del entorno de ejecución con la versión del SDK

En el enfoque de distribución Evergreen, el tiempo de ejecución de WebView2 del cliente se actualiza automáticamente a la última versión disponible. Sin embargo, un usuario o un Administrador de TI puede optar por impedir la actualización automática del tiempo de ejecución de WebView2. El tiempo de ejecución obsoleto resultante en el cliente podría causar 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 tiempo de ejecución de WebView2 en el cliente, asegúrate de conocer el número de compilación mínimo del tiempo de ejecución de WebView2 que requiere la aplicación. Para ver u obtener las últimas versiones del entorno de ejecución WebView2, consulta Descargar el tiempo de ejecución WebView2 en la página WebView2 de Microsoft Edge en developer.microsoft.com. La versión mínima del entorno de ejecución necesaria para admitir la versión de disponibilidad general del SDK (compilación 616) es anterior al último entorno de ejecución. El último tiempo de ejecución admite todas las API que están en el SDK de la versión más reciente.

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

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

Si la aplicación usa el tiempo de ejecución Evergreen en lugar de la versión fija, debes ajustar las llamadas a API WebView2 relativamente nuevas mediante o QueryInterfacetry-catch. Hay casos extremos en los que el tiempo de ejecución Evergreen 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, porque es posible que el Administrador haya suprimido temporalmente la actualización del tiempo de ejecución WebView2 o que el cliente esté sin conexión.

Cuando desarrollas una aplicación WebView2 con una versión reciente del SDK de WebView2, si usas una API agregada recientemente, debes probar o "detectar características" si esa API está presente en el tiempo de ejecución de WebView2 instalado por el cliente. La forma en que la aplicación prueba mediante programación la compatibilidad con API depende de la plataforma de codificación:

.NET, WinUI y WinRT

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 tiempo de ejecución de WebView2 del cliente es una versión anterior que no admite esa API.

Win32 C/C++

Al solicitar la exportación CreateCoreWebView2Environment de DLL y al ejecutarse QueryInterface en cualquier CoreWebView2 objeto, compruebe si el valor devuelto es de E_NOINTERFACE. Ese valor devuelto probablemente indica que el tiempo de ejecución de 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 el tiempo de ejecución, búsquelo try_query en AppWindow.cpp. Este archivo encapsula las llamadas API de WebView2 en la función de CHECK_FAILURE macro, definida en CheckFailure.h.

Proporcionar reserva adecuada

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

Vea también

Documentación de Microsoft Edge Enterprise:

Descargas:

GitHub:

  • Last updated on