Migración del SDK de Aplicaciones para Windows de la aplicación de muestra PhotoLab de UWP (C++/WinRT)

Este tema es un caso práctico en el que se toma la aplicación de ejemplo de PhotoLab para UWP en C# y se migra al SDK de Aplicaciones para Windows.

Comience por clonar el repositorio de la aplicación de ejemplo de UWP y abrir la solución en Visual Studio.

Importante

Para conocer consideraciones y estrategias para abordar el proceso de migración y cómo configurar el entorno de desarrollo para la migración, consulte Estrategia general de migración. Es especialmente importante ver lo que se admite al migrar desde UWP a WinUI 3 para que pueda asegurarse de que todas las características que necesita para la aplicación se admiten antes de intentar la migración.

Instalación de herramientas para el SDK de Aplicaciones para Windows

Para configurar el equipo de desarrollo, consulte Instalación de herramientas para el SDK de Aplicaciones para Windows.

Importante

Encontrará temas de notas de la versión junto con el tema Canales de versión del SDK de Aplicaciones para Windows. Hay notas de la versión para cada canal. Asegúrese de consultar las limitaciones y los problemas conocidos en esas notas de la versión, ya que pueden afectar los resultados que se devuelven al seguir este caso práctico o a la ejecución de la aplicación migrada.

Crear un nuevo proyecto

En Visual Studio, cree un nuevo proyecto de C# a partir de la plantilla de proyecto Aplicación vacía empaquetada (WinUI 3 en escritorio). Asigne al proyecto el nombre PhotoLabWinUI, desactive Colocar solución y proyecto en el mismo directorio. Puede tener como destino la versión más reciente (no en versión preliminar) del sistema operativo cliente.

Nota:

Nos referiremos a la versión de UWP del proyecto de ejemplo (la que ha clonado desde su repositorio) como solución o proyecto de origen. Nos referiremos a la versión de SDK de Aplicaciones para Windows como solución o proyecto de destino.

El orden en el que se migrará el código.

MainPage es una parte importante y destacada de la aplicación. Pero si empezáramos por migrar eso, pronto nos daríamos cuenta de que MainPage tiene una dependencia de la vista DetailPage; y luego de que DetailPage tiene una dependencia del modelo ImageFileInfo. Por lo tanto, para este tutorial tomaremos este enfoque.

• Comenzaremos copiando los archivos de recursos.
• A continuación, migraremos el modelo ImageFileInfo.
• A continuación, migraremos la clase App (ya que necesita cambios en ella que dependan de DetailPage, MainPage y LoadedImageBrush).
• A continuación, migraremos la clase LoadedImageBrush.
• A continuación, empezaremos a migrar las vistas, empezando por DetailPage primero.
• Y terminaremos migrando la vista MainPage.

Copia de archivos de recursos

1. En su proyecto de destino en Visual Studio, en el Explorador de soluciones, haga clic con el botón derecho en la carpeta Assets y añada una nueva carpeta llamada Samples.

2. En el clon del proyecto de origen, en Explorador de archivos, busque la carpeta Windows-appsample-photo-lab>PhotoLab>Activos. Encontrará siete archivos de recursos en esa carpeta, junto con una subcarpeta denominada Muestras que contiene imágenes de ejemplo. Seleccione esos siete archivos de recursos y la subcarpeta Muestras y cópielos en el Portapapeles.

3. También en Explorador de archivos, busque ahora la carpeta correspondiente en el proyecto de destino que creó. La ruta de acceso a esa carpeta es PhotoLabWinUI>PhotoLabWinUI>Activos. Pegue en esa carpeta los archivos de recursos y la subcarpeta que acaba de copiar y acepte el mensaje para reemplazar los archivos que ya existen en el destino.

4. En el proyecto de destino de Visual Studio, en Explorador de soluciones, con la carpeta Activos expandida, verá en la carpeta Muestras el contenido de la subcarpeta Muestras (que acaba de pegar). Puede mantener el puntero del mouse sobre los archivos de recursos. Aparecerá una vista previa de miniaturas para cada una, confirmando que ha reemplazado o agregado correctamente los archivos de recursos.

Migrar el modelo ImageFileInfo

ImageFileInfo es un modelo (en el sentido de modelos, vistas y modelos de vista) que representa un archivo de imagen, como una foto.

Copiar archivos de código fuente ImageFileInfo

1. En el clon del proyecto de origen, en Explorador de archivos, busque la carpeta Windows-appsample-photo-lab>PhotoLab. En esa carpeta encontrará el archivo de código fuente ImageFileInfo.cs; ese archivo contiene la implementación de ImageFileInfo. Seleccione ese archivo y cópielo en el Portapapeles.

2. En Visual Studio, haga clic con el botón derecho en el nodo del proyecto de destino y haga clic en Abrir carpeta en Explorador de archivos. Se abre la carpeta del proyecto de destino en el Explorador de archivos. Pegue en esa carpeta el archivo que acaba de copiar.

Migración del código fuente ImageFileInfo

1. Realice las siguientes búsqueda o reemplazos (mayúsculas y minúsculas de coincidencia y palabra completa) en el archivo ImageFileInfo.cs que acaba de pegar.

• namespace PhotoLab =>namespace PhotoLabWinUI
• Windows.UI.Xaml =>Microsoft.UI.Xaml

Windows.UI.Xaml es el espacio de nombres para XAML de UWP; Microsoft.UI.Xaml es el espacio de nombres para XAML de WinUI.

Nota:

El tema Asignación de API para UWP al SDK de Aplicaciones para Windows proporciona una asignación de las API de UWP a sus equivalentes de SDK de Aplicaciones para Windows. El cambio realizado anteriormente es un ejemplo de un cambio de nombre de espacio de nombres necesario durante el proceso de migración.

2. Ahora confirme que puede construir la solución de destino (pero no la ejecute todavía).

Migración de la clase App

1. En el proyecto de origen, en el elemento <Application.Resources> de App.xaml, busque las cuatro líneas siguientes. Cópielas y péguelas en el proyecto de destino.

<SolidColorBrush x:Key="RatingControlSelectedForeground" Color="White"/>
<!--  Window width adaptive breakpoints.  -->
<x:Double x:Key="MinWindowBreakpoint">0</x:Double>
<x:Double x:Key="MediumWindowBreakpoint">641</x:Double>
<x:Double x:Key="LargeWindowBreakpoint">1008</x:Double>

Nota:

Dado que el proyecto de destino usará una navegación diferente (y más sencilla) desde el proyecto de origen, no es necesario copiar más código desde el proyecto de origen App.xaml.cs.

2. En el proyecto de destino, App almacena el objeto de ventana principal en su campo privado m_window. Más adelante en el proceso de migración (cuando migramos el uso del proyecto de origen de Window.Current), será conveniente si ese campo privado es en su lugar una propiedad estática pública. Por lo tanto, reemplace el campo m_window por una propiedad Window y cambie las referencias a m_window, como se muestra a continuación.

// App.xaml.cs
public partial class App : Application
{
    ...
    protected override void OnLaunched(Microsoft.UI.Xaml.LaunchActivatedEventArgs args)
    {
        Window = new MainWindow();
        Window.Activate();
    }

    public static MainWindow Window { get; private set; }
}

3. Más adelante en el proceso de migración (cuando migramos el código que muestra un FileSavePicker), será conveniente si App expone el identificador de la ventana principal (HWND). Por lo tanto, agregue una propiedad WindowHandle e inicialícela en el método OnLaunched, como se muestra a continuación.

// App.xaml.cs
public partial class App : Application
{
    ...
    protected override void OnLaunched(Microsoft.UI.Xaml.LaunchActivatedEventArgs args)
    {
        Window = new MainWindow();
        Window.Activate();
        WindowHandle = WinRT.Interop.WindowNative.GetWindowHandle(Window);
    }

    public static IntPtr WindowHandle { get; private set; }
}

Migración del modelo LoadedImageBrush

LoadedImageBrush es una especialización de XamlCompositionBrushBase. La aplicación de ejemplo PhotoLab usa la clase LoadedImageBrush para aplicar efectos a las fotos.

Referencia al paquete NuGet Win2D

Para admitir código en LoadedImageBrush, el proyecto de origen tiene una dependencia en Win2D. Por lo tanto, también necesitaremos una dependencia de Win2D en nuestro proyecto de destino.

En la solución de destino de Visual Studio, haga clic en Herramientas>Administrador de paquetes NuGet> Administrar paquetes NuGet para la solución...>Navegar y escriba o pegue Microsoft.Graphics.Win2D. Seleccione el elemento correcto en los resultados de búsqueda, compruebe el proyecto PhotoLabWinUI y haga clic en Instalar para instalar el paquete en ese proyecto.

Copiar archivos de código fuente LoadedImageBrush

Copie LoadedImageBrush.cs desde el proyecto de origen al proyecto de destino de la misma manera que copió ImageFileInfo.cs.

Migración del código fuente LoadedImageBrush

1. Realice las siguientes búsqueda o reemplazos (mayúsculas y minúsculas de coincidencia y palabra completa) en el archivo LoadedImageBrush.cs que acaba de pegar.

• namespace PhotoLab =>namespace PhotoLabWinUI
• Windows.UI.Composition =>Microsoft.UI.Composition
• Windows.UI.Xaml =>Microsoft.UI.Xaml
• Window.Current.Compositor =>App.Window.Compositor (consulte Cambiar Windows.UI.Xaml.Window.Current a App.Window)

2. Confirme que puede compilar la solución de destino (pero no la ejecute aún).

Migración de la vista DetailPage

DetailPage es la clase que representa la página del editor de fotos, donde los efectos Win2D se alternan, establecen y encadenan juntos. Para acceder a la página del editor de fotos, seleccione una miniatura de foto en MainPage. DetailPage es un modelo (en el sentido de modelos, vistas y modelos de vista).

Copiar archivos de código fuente de DetailPage

Copie DetailPage.xaml y DetailPage.xaml.cs desde el proyecto de origen al proyecto de destino de la misma manera que copió los archivos en los pasos anteriores.

Migración del código fuente de DetailPage

1. Realice las siguientes búsqueda o reemplazos (mayúsculas y minúsculas de coincidencia y palabra completa) en el archivo DetailPage.xaml que acaba de pegar.

• PhotoLab =>PhotoLabWinUI

2. Realice las siguientes búsqueda o reemplazos (mayúsculas y minúsculas de coincidencia y palabra completa) en el archivo DetailPage.xaml.cs que acaba de pegar.

• namespace PhotoLab =>namespace PhotoLabWinUI
• Windows.UI.Colors =>Microsoft.UI.Colors
• Windows.UI.Xaml =>Microsoft.UI.Xaml

3. Para el siguiente paso, realizaremos el cambio que se explica en ContentDialog y Popup. Por lo tanto, todavía en DetailPage.xaml.cs, en el método ShowSaveDialog, inmediatamente antes de la línea ContentDialogResult result = await saveDialog.ShowAsync();, agregue este código.

if (Windows.Foundation.Metadata.ApiInformation.IsApiContractPresent("Windows.Foundation.UniversalApiContract", 8))
{
    saveDialog.XamlRoot = this.Content.XamlRoot;
}

4. Todavía en DetailPage.xaml.cs, en el método OnNavigatedTo, elimine las dos líneas de código siguientes. Solo esas dos líneas; más adelante en este caso práctico, volveremos a introducir la funcionalidad del botón Atrás que acabamos de quitar.

...
SystemNavigationManager.GetForCurrentView().AppViewBackButtonVisibility =
    AppViewBackButtonVisibility.Visible;
...
SystemNavigationManager.GetForCurrentView().AppViewBackButtonVisibility = 
    AppViewBackButtonVisibility.Collapsed;
...

5. En este paso, realizaremos el cambio que se explica en MessageDialog y Selectores. Todavía en DetailPage.xaml.cs, en el método ExportImage, inmediatamente antes de la línea var outputFile = await fileSavePicker.PickSaveFileAsync();, agregue esta línea de código.

WinRT.Interop.InitializeWithWindow.Initialize(fileSavePicker, App.WindowHandle);

MainPage tiene dependencias de DetailPage, por lo que migramos DetailPage primero. Pero DetailPage también tiene dependencias en MainPage, por lo que aún no se podrá compilar.

Migración de la vista MainPage

La página principal de cualquier aplicación representa la vista que ve primero al ejecutar la aplicación. Es la página que carga las fotos de la carpeta Muestras integrada en la aplicación de ejemplo y muestra una vista en miniatura en mosaico.

Copiar archivos de código fuente de MainPage

Copie MainPage.xaml y MainPage.xaml.cs desde el proyecto de origen al proyecto de destino de la misma manera que copió los archivos en los pasos anteriores.

Migración del código fuente de MainPage

1. Realice las siguientes búsqueda o reemplazos (mayúsculas y minúsculas de coincidencia y palabra completa) en el archivo MainPage.xaml que acaba de pegar.

• PhotoLab =>PhotoLabWinUI

2. Todavía en MainPage.xaml, busque el marcado animations:ReorderGridAnimation.Duration="400" y elimínelo.

3. Realice las siguientes búsqueda o reemplazos (mayúsculas y minúsculas de coincidencia y palabra completa) en el archivo MainPage.xaml.cs que acaba de pegar.

• namespace PhotoLab =>namespace PhotoLabWinUI
• Windows.UI.Xaml =>Microsoft.UI.Xaml

4. En este paso, realizaremos el cambio que se explica en ContentDialog y Popup. Por lo tanto, todavía en MainPage.xaml.cs, en el método GetItemsAsync, inmediatamente antes de la línea ContentDialogResult resultNotUsed = await unsupportedFilesDialog.ShowAsync();, agregue este código.

if (Windows.Foundation.Metadata.ApiInformation.IsApiContractPresent("Windows.Foundation.UniversalApiContract", 8))
{
    unsupportedFilesDialog.XamlRoot = this.Content.XamlRoot;
}

5. Todavía en MainPage.xaml.cs, en el método OnNavigatedTo, elimine la línea de código siguiente.

SystemNavigationManager.GetForCurrentView().AppViewBackButtonVisibility =
    AppViewBackButtonVisibility.Collapsed;

Más adelante en este caso práctico, volveremos a introducir la funcionalidad del botón Atrás que acabamos de quitar.

6. Confirme que puede compilar la solución de destino (pero no la ejecute aún).

Vaya a MainPage

La aplicación de ejemplo PhotoLab usa la lógica de navegación para navegar inicialmente a MainPage (y, a continuación, entre MainPage y DetailPage). Para obtener más información sobre las aplicaciones del SDK de Aplicaciones para Windows que necesitan navegación (y las que no), consulte ¿Necesito implementar la navegación de páginas?.

Por lo tanto, los cambios que realizaremos a continuación admitirán esa navegación.

1. En MainWindow.xaml, elimine el elemento <StackPanel> y reemplácelo por solo un elemento con nombre <Frame>. El resultado tiene el aspecto siguiente:

<Window ...>
    <Frame x:Name="rootFrame"/>
</Window>

2. En MainWindow.xaml.cs, elimine el método myButton_Click.

3. Todavía en MainWindow.xaml.cs, añada la siguiente línea de código al constructor.

public sealed partial class MainWindow : Window
{
    public MainWindow()
    {
        this.InitializeComponent();
        rootFrame.Navigate(typeof(MainPage));
    }
}

4. Confirme que puede compilar la solución de destino (pero no la ejecute aún).

Restauración de la funcionalidad del botón Atrás

1. En DetailPage.xaml, el elemento raíz es RelativePanel. Añada el siguiente marcado dentro de ese RelativePanel, inmediatamente después del elemento StackPanel.

<AppBarButton x:Name="BackButton" Click="BackButton_Click" Margin="0,0,12,0">
    <SymbolIcon Symbol="Back"/>
</AppBarButton>

2. En DetailPage.xaml.cs, agregue las dos líneas de código siguientes al método OnNavigatedTo, en el lugar indicado.

if (this.Frame.CanGoBack)
{
    BackButton.Visibility = Microsoft.UI.Xaml.Visibility.Visible;
}
else
{
    BackButton.Visibility = Microsoft.UI.Xaml.Visibility.Collapsed;
}

3. Todavía en DetailPage.xaml.cs, añada el siguiente controlador de eventos.

private void BackButton_Click(object sender, Microsoft.UI.Xaml.RoutedEventArgs e)
{
    Frame.GoBack();
}

Probar la aplicación migrada

Ahora construya el proyecto, y ejecute la aplicación para probarla. Seleccione una imagen, establezca un nivel de zoom, elija efectos y configúrela.

Consulte también

• SDK de Aplicaciones para Windows y versiones de Windows compatibles