Migrar a C++/WinRT desde C#

En este tema se cataloga exhaustivamente los detalles técnicos implicados en la migración del código fuente de un proyecto de C# a su equivalente en C++/WinRT.

Para obtener un caso práctico de migración de uno de los ejemplos de aplicaciones de Plataforma universal de Windows (UWP), consulte el tema complementario Migración del ejemplo del Portapapeles a C++/WinRT desde C#. Puede adquirir práctica y experiencia en portabilidad siguiendo ese tutorial y migrando usted mismo el ejemplo sobre la marcha.

Preparación y qué esperar

El caso práctico Migración del ejemplo del Portapapeles a C++/WinRT de C# muestra ejemplos de los tipos de decisiones de diseño de software que tomarás al migrar un proyecto a C++/WinRT. Por lo tanto, es una buena idea prepararse para la portabilidad mediante una comprensión sólida de cómo funciona el código existente. De este modo, obtendrá una buena visión general de la funcionalidad de la aplicación y la estructura del código y, a continuación, las decisiones que tome siempre le llevarán adelante y en la dirección correcta.

En términos de qué tipos de cambios de portabilidad se esperan, puede agruparlos en cuatro categorías.

• Portar la proyección de lenguaje. El Windows Runtime (WinRT) se proyecta en varios lenguajes de programación. Cada una de esas proyecciones de lenguaje está diseñada para resultar natural en el lenguaje de programación correspondiente. Para C#, algunos tipos de Windows Runtime se proyectan como tipos .NET. Así, por ejemplo, traducirá System.Collections.Generic.IReadOnlyList<T> de nuevo como Windows.Foundation.Collections.IVectorView<T>. Además, en C#, algunas operaciones de Windows Runtime se proyectan como características cómodas del lenguaje C#. Un ejemplo es que en C# se usa la sintaxis del += operador para registrar un delegado de control de eventos. Así que relacionará las características del lenguaje, como esa, con la operación fundamental que se está realizando (registro de eventos, en este ejemplo).
• Sintaxis del lenguaje de puerto. Muchos de estos cambios son transformaciones mecánicas simples, reemplazando un símbolo por otro. Por ejemplo, cambiar punto (.) a dos puntos (::).
• Procedimiento de lenguaje de puerto. Algunos de ellos pueden ser cambios simples y repetitivos (como de myObject.MyProperty a myObject.MyProperty()). Otros necesitan cambios más profundos (por ejemplo, migrar un procedimiento que implique el uso de System.Text.StringBuilder a uno que implique el uso de std::wostringstream).
• Tareas relacionadas con la portabilidad específicas de C++/WinRT. C# se encarga implícitamente de ciertos detalles de Windows Runtime, entre bastidores. Estos detalles se realizan explícitamente en C++/WinRT. Un ejemplo es que se usa un .idl archivo para definir las clases en tiempo de ejecución.

Después del índice basado en tareas siguiente, el resto de las secciones de este tema se estructuran según la taxonomía anterior.

Buscar contenido basado en la tarea que está realizando

Cambios que implican la proyección del lenguaje

Registro o revocación de un controlador de eventos

En C++/WinRT, tiene varias opciones sintácticas para registrar o revocar un delegado de controlador de eventos, como se describe en Controlar eventos mediante delegados en C++/WinRT. Consulte también Adaptación del método EnableClipboardContentChangedNotifications.

A veces, por ejemplo, cuando un destinatario de eventos (un objeto que controla un evento) está a punto de destruirse, querrá revocar un controlador de eventos para que el origen del evento (el objeto que genera el evento) no llame a un objeto destruido. Consulte Revocar un delegado registrado. En casos como ese, cree una variable miembro event_token para los controladores de eventos. Para obtener un ejemplo, vea Portabilidad del método EnableClipboardContentChangedNotifications.

También puedes registrar un controlador de eventos en el marcado XAML.

<Button x:Name="OpenButton" Click="OpenButton_Click" />

En C#, el método OpenButton_Click puede ser privado y XAML todavía podrá conectarlo al evento ButtonBase.Click generado por OpenButton.

En C++/WinRT, el método OpenButton_Click debe ser público en el tipo de implementaciónsi quiere registrarlo en el marcado XAML. Si registra un controlador de eventos solo en código imperativo, no es necesario que el controlador de eventos sea público.

namespace winrt::MyProject::implementation
{
    struct MyPage : MyPageT<MyPage>
    {
        void OpenButton_Click(
            winrt::Windows::Foundation::IInspectable const& sender,
            winrt::Microsoft::UI::Xaml::RoutedEventArgs const& args);
    }
};

Como alternativa, puedes hacer que la página XAML que realiza el registro tenga acceso de amigo a tu tipo de implementación y que OpenButton_Click sea privado.

namespace winrt::MyProject::implementation
{
    struct MyPage : MyPageT<MyPage>
    {
    private:
        friend MyPageT;
        void OpenButton_Click(
            winrt::Windows::Foundation::IInspectable const& sender,
            winrt::Microsoft::UI::Xaml::RoutedEventArgs const& args);
    }
};

Un escenario final es donde el proyecto de C# que va a migrar se enlaza al controlador de eventos desde el marcado (para obtener más información sobre ese escenario, vea Functions in x:Bind).

<Button x:Name="OpenButton" Click="{x:Bind OpenButton_Click}" />

Simplemente podrías cambiar ese marcado por la versión más simple: Click="OpenButton_Click". O bien, si lo prefiere, puede mantener ese marcado tal como está. Todo lo que hay que hacer para darle soporte es declarar el gestor de eventos en IDL.

void OpenButton_Click(Object sender, Microsoft.UI.Xaml.RoutedEventArgs e);

Cambios que implican la sintaxis del lenguaje

Migración de clases y miembros

Tendrá que decidir, para cada tipo de C#, si se debe portar a un tipo de Windows Runtime o a una clase/estructura/enumeración de C++ normal. Para obtener más información y ejemplos detallados que ilustran cómo tomar esas decisiones, consulte Migración del ejemplo del Portapapeles a C++/WinRT desde C#.

Normalmente, una propiedad de C# se convierte en un método de acceso, un método mutador y un campo de respaldo. Para obtener más información y un ejemplo, consulta Porting the IsClipboardContentChangedEnabled property.

En el caso de los campos no estáticos, conviértalos en miembros de datos de su tipo de implementación.

Un campo estático de C# se convierte en un descriptor de acceso estático de C++/WinRT o una función mutadora. Para obtener más información y un ejemplo, consulta Portabilidad del constructor, Current y FEATURE_NAME.

En el caso de las funciones miembro, de nuevo, tendrá que decidir en cada caso si debe formar parte de la IDL o si es una función miembro pública o privada de su tipo de implementación. Para obtener más información y ejemplos de cómo decidir, consulta IDL para el tipo MainPage.

Migración de archivos de marcado XAML y archivos de recursos

En el caso de migrar el ejemplo del Portapapeles a C++/WinRT desde C#, pudimos usar el mismo marcado XAML (incluidos los recursos) y los archivos de recursos en el proyecto de C# y C++/WinRT. En algunos casos, las modificaciones en el marcado serán necesarias para lograrlo. Consulta Copiar el XAML y los estilos necesarios para completar la migración de MainPage.

Cambios que implican procedimientos dentro del idioma

En las secciones siguientes se detallan más detalles sobre algunos de los elementos de la tabla.

Construcción de elementos de interfaz de usuario

Estos ejemplos de código muestran la construcción de un elemento de interfaz de usuario en el código imperativo de una página XAML.

var myTextBlock = new TextBlock()
{
    Text = "Text",
    Style = (Microsoft.UI.Xaml.Style)this.Resources["MyTextBlockStyle"]
};

TextBlock myTextBlock;
myTextBlock.Text(L"Text");
myTextBlock.Style(
    winrt::unbox_value<Microsoft::UI::Xaml::Style>(
        Resources().Lookup(
            winrt::box_value(L"MyTextBlockStyle")
        )
    )
);

ToString()

Los tipos de C# proporcionan el método Object.ToString .

int i = 2;
var s = i.ToString(); // s is a System.String with value "2".

C++/WinRT no proporciona directamente esta instalación, pero puedes recurrir a alternativas.

int i{ 2 };
auto s{ std::to_wstring(i) }; // s is a std::wstring with value L"2".

C++/WinRT también admite winrt::to_hstring para un número limitado de tipos. Tendrás que añadir sobrecargas para cualquier tipo adicional que quieras convertir en cadena.

En el caso de convertir una enumeración en cadena, deberá proporcionar la implementación de winrt::to_hstring.

namespace winrt
{
    hstring to_hstring(StatusEnum status)
    {
        switch (status)
        {
        case StatusEnum::Success: return L"Success";
        case StatusEnum::AccessDenied: return L"AccessDenied";
        case StatusEnum::DisabledByPolicy: return L"DisabledByPolicy";
        default: return to_hstring(static_cast<int>(status));
        }
    }
}

Estas conversiones a cadena a menudo se consumen implícitamente mediante el enlace de datos.

<TextBlock>
You have <Run Text="{Binding FlowerCount}"/> flowers.
</TextBlock>
<TextBlock>
Most recent status is <Run Text="{x:Bind LatestOperation.Status}"/>.
</TextBlock>

Estas vinculaciones realizarán la conversión de la propiedad enlazada mediante winrt::to_hstring. En el caso del segundo ejemplo (StatusEnum), debe proporcionar su propia sobrecarga de winrt::to_hstring; de lo contrario, obtendrá un error del compilador.

Vea también la migración del método Footer_Click.

Construcción de cadenas

Para la creación de cadenas, C# tiene un tipo StringBuilder integrado.

Consulte también Migración del método BuildClipboardFormatsOutputString y Migración del método DisplayChangedFormats.

Ejecución de código en el subproceso principal de la interfaz de usuario

Este ejemplo se toma del ejemplo de escáner de código de barras.

Cuando quieras trabajar en el subproceso principal de la interfaz de usuario de un proyecto de C#, normalmente usas el método DispatcherQueue.TryEnqueue (o el coreDispatcher.RunAsync anterior en UWP). Este es el aspecto del patrón en C#.

private async void Watcher_Added(DeviceWatcher sender, DeviceInformation args)
{
    DispatcherQueue.TryEnqueue(() =>
    {
        // Do work on the main UI thread here.
    });
}

Es mucho más sencillo expresarlo en C++/WinRT. Observe que estamos aceptando parámetros por valor en la suposición de que queremos acceder a ellos después del primer punto de suspensión (, co_awaiten este caso). Para obtener más información, consulta Paso de parámetros.

winrt::fire_and_forget Watcher_Added(DeviceWatcher sender, winrt::DeviceInformation args)
{
    co_await DispatcherQueue();
    // Do work on the main UI thread here.
}

Si necesitas realizar el trabajo con una prioridad distinta de la predeterminada, consulta la función winrt::resume_foreground , que tiene una sobrecarga que tiene una prioridad. Para ver ejemplos de código que muestran cómo esperar una llamada a winrt::resume_foreground, consulte Programación con afinidad de subproceso en mente.

Tareas de migración específicas de C++/WinRT

Definición de las clases en tiempo de ejecución en IDL

Consulte IDL para el tipo MainPage y Consolide sus .idl archivos.

Incluya los archivos de cabecera de los espacios de nombres de Windows de C++/WinRT que necesite

En C++/WinRT, cada vez que quieras usar un tipo de un espacio de nombres de Windows, debes incluir el archivo de encabezado del espacio de nombres de Windows correspondiente para C++/WinRT. Por ejemplo, consulte Adaptación del método NotifyUser.

Boxing y unboxing

C# convierte automáticamente los valores escalares en objetos. C++/WinRT requiere que llames a la función winrt::box_value explícitamente. Ambos lenguajes requieren que desempaquetes explícitamente. Consulta Boxing y unboxing con C++/WinRT.

En las tablas siguientes, usaremos estas definiciones.

C++/CX y C# generan excepciones si intenta desenboxar un puntero nulo a un tipo de valor. C++/WinRT considera esto un error de programación y se bloquea. En C++/WinRT, use la función winrt::unbox_value_or si desea controlar el caso en el que el objeto no es del tipo que pensaba que era.

Para ver un ejemplo, consulte Adaptación del método OnNavigatedTo y Adaptación del método Footer_Click.

Boxing y unboxing de una cadena

Una cadena es de alguna manera un tipo de valor y de otras maneras un tipo de referencia. C# y C++/WinRT tratan cadenas de forma diferente.

El tipo ABI HSTRING es un puntero a una cadena con recuento de referencias. Pero no se deriva de IInspectable, por lo que no es técnicamente un objeto . Además, un HSTRING nulo representa la cadena vacía. El boxing de elementos que no derivan de IInspectable se realiza encapsulándolos en un IReference<T>, y Windows Runtime proporciona una implementación estándar en forma de objeto PropertyValue (los tipos personalizados se indican como PropertyType::OtherType).

C# representa una cadena Windows Runtime como un tipo de referencia; mientras que C++/WinRT proyecta una cadena como un tipo de valor. Esto significa que una cadena nula encapsulada puede tener distintas representaciones según cómo se haya obtenido.

Boxing y unboxing básicos.

Hacer que una clase esté disponible para la extensión de marcado {Binding}

Si tiene previsto usar la extensión de marcado {Binding} para establecer un enlace de datos con su tipo de datos, consulte objeto Binding declarado mediante {Binding}.

Consumo de objetos del marcado XAML

En un proyecto de C#, puedes consumir miembros privados y elementos con nombre del marcado XAML. Pero en C++/WinRT, todas las entidades consumidas mediante la extensión de marcado XAML {x:Bind} deben exponerse públicamente en IDL.

Además, al enlazar con un Boolean se muestra true o false en C#, pero en C++/WinRT se muestra Windows.Foundation.IReference`1<Boolean>.

Para obtener más información y ejemplos de código, consulte Consumo de objetos de marcado.

Hacer que un origen de datos esté disponible para el marcado XAML

En C++/WinRT versión 2.0.190530.8 o posterior, winrt::single_threaded_observable_vector crea un vector observable que admite IObservableVector<T> e IObservableVector<IInspectable>. Para obtener un ejemplo, vea Portabilidad de la propiedad Scenarios.

Puede crear su archivo Midl (.idl) de este modo (consulte también Separación de clases en tiempo de ejecución en archivos Midl (.idl)).

namespace Bookstore
{
    runtimeclass BookSku { ... }

    runtimeclass BookstoreViewModel
    {
        Windows.Foundation.Collections.IObservableVector<BookSku> BookSkus{ get; };
    }

    runtimeclass MainPage : Microsoft.UI.Xaml.Controls.Page
    {
        MainPage();
        BookstoreViewModel MainViewModel{ get; };
    }
}

E implemente así.

// BookstoreViewModel.h
...
struct BookstoreViewModel : BookstoreViewModelT<BookstoreViewModel>
{
    BookstoreViewModel()
    {
        m_bookSkus = winrt::single_threaded_observable_vector<Bookstore::BookSku>();
        m_bookSkus.Append(winrt::make<Bookstore::implementation::BookSku>(L"To Kill A Mockingbird"));
    }
    
	Windows::Foundation::Collections::IObservableVector<Bookstore::BookSku> BookSkus();
    {
        return m_bookSkus;
    }

private:
    Windows::Foundation::Collections::IObservableVector<Bookstore::BookSku> m_bookSkus;
};
...

Para obtener más información, consulta Controles de elementos XAML; enlazar a una colección de C++/WinRT y Colecciones con C++/WinRT.

Hacer que un origen de datos esté disponible para el marcado XAML (antes de C++/WinRT 2.0.190530.8)

El enlace de datos XAML requiere que una fuente de elementos implemente IIterable<IInspectable>, así como una de las siguientes combinaciones de interfaces.

• IObservableVector<IInspectable>
• IBindableVector e INotifyCollectionChanged
• IBindableVector e IBindableObservableVector
• IBindableVector por sí mismo (no responderá a los cambios)
• IVector<IInspectable>
• IBindableIterable (iterará y guardará los elementos en una colección privada)

No se puede detectar una interfaz genérica como IVector<T> en tiempo de ejecución. Cada IVector<T> tiene un identificador de interfaz diferente (IID), que es una función de T. Cualquier desarrollador puede expandir el conjunto de T arbitrariamente, por lo que claramente el código de enlace XAML nunca puede conocer el conjunto completo para el que se va a consultar. Esa restricción no es un problema para C# porque cada objeto CLR que implementa IEnumerable T< implementa automáticamente IEnumerable>. En el nivel de ABI, esto significa que cada objeto que implementa IObservableVector<T> implementa automáticamente IObservableVector<IInspectable>.

C++/WinRT no ofrece esa garantía. Si una clase en tiempo de ejecución de C++/WinRT implementa IObservableVector<T>, no podemos suponer que también se proporciona una implementación de IObservableVector<IInspectable> .

Por consiguiente, así es como deberá verse el ejemplo anterior.

...
runtimeclass BookstoreViewModel
{
    // This is really an observable vector of BookSku.
    Windows.Foundation.Collections.IObservableVector<Object> BookSkus{ get; };
}

Y la implementación.

// BookstoreViewModel.h
...
struct BookstoreViewModel : BookstoreViewModelT<BookstoreViewModel>
{
    BookstoreViewModel()
    {
        m_bookSkus = winrt::single_threaded_observable_vector<Windows::Foundation::IInspectable>();
        m_bookSkus.Append(winrt::make<Bookstore::implementation::BookSku>(L"To Kill A Mockingbird"));
    }
    
    // This is really an observable vector of BookSku.
	Windows::Foundation::Collections::IObservableVector<Windows::Foundation::IInspectable> BookSkus();
    {
        return m_bookSkus;
    }

private:
    Windows::Foundation::Collections::IObservableVector<Windows::Foundation::IInspectable> m_bookSkus;
};
...

Si necesita acceder a los objetos de m_bookSkus, tendrá que hacerles QI de nuevo a Bookstore::BookSku.

Widget MyPage::BookstoreViewModel(winrt::hstring title)
{
    for (auto&& obj : m_bookSkus)
    {
        auto bookSku = obj.as<Bookstore::BookSku>();
        if (bookSku.Title() == title) return bookSku;
    }
    return nullptr;
}

Clases derivadas

Para derivar de una clase en tiempo de ejecución, la clase base debe ser composable. C# no requiere que realice ningún paso especial para que las clases se puedan componer, pero C++/WinRT sí. Usa la palabra clave unsealed para indicar que quieres que tu clase se pueda usar como clase base.

unsealed runtimeclass BasePage : Microsoft.UI.Xaml.Controls.Page
{
    ...
}
runtimeclass DerivedPage : BasePage
{
    ...
}

En el archivo de encabezado del tipo de implementación, debe incluir el archivo de encabezado de clase base antes de incluir el encabezado generado automáticamente para la clase derivada. De lo contrario, obtendrá errores como "Uso no válido de este tipo como expresión".

// DerivedPage.h
#include "BasePage.h"       // This comes first.
#include "DerivedPage.g.h"  // Otherwise this header file will produce an error.

namespace winrt::MyNamespace::implementation
{
    struct DerivedPage : DerivedPageT<DerivedPage>
    {
        ...
    }
}

API importantes

• Espacio de nombres winrt

Temas relacionados

• tutoriales de C#
• C++/WinRT
• Enlace de datos en profundidad