Mover de C para C++/WinRT#

Este tópico cataloga de forma abrangente os detalhes técnicos envolvidos na portabilidade do código-fonte num projeto C# para o seu equivalente em C++/WinRT.

Para um estudo de caso sobre a portabilidade de um dos exemplos de aplicações da Plataforma Universal do Windows (UWP), veja o tópico complementar Portar o exemplo do Clipboard para C++/WinRT a partir de C#. Pode ganhar prática e experiência em portabilidade seguindo esse guia passo a passo e adaptando o exemplo por si, à medida que progride.

Como preparar-se e o que esperar

O estudo de caso Porting the Clipboard sample do C# para C++/WinRT ilustra exemplos dos tipos de decisões de design de software que tomará ao portar um projeto para C++/WinRT. Por isso, é uma boa ideia preparar-se para a portabilidade, adquirindo uma compreensão sólida de como funciona o código existente. Assim, terá uma boa visão geral da funcionalidade da aplicação e da estrutura do código, e depois as decisões que tomar o levarão sempre para a frente, na direção certa.

Quanto ao tipo de alterações de portabilidade a esperar, pode agrupá-las em quatro categorias.

• Adapte a projeção de linguagem. O Windows Runtime (WinRT) é projetado para várias linguagens de programação. Cada uma dessas projeções de linguagem foi concebida para parecer idiomática para a linguagem de programação em questão. Para C#, alguns tipos de Windows Runtime são projetados como tipos .NET. Por exemplo, vais traduzir System.Collections.Generic.IReadOnlyList<T> novamente para Windows.Foundation.Collections.IVectorView<T>. Também em C#, algumas operações do Windows Runtime são projetadas como funcionalidades convenientes da linguagem C#. Um exemplo é que em C# usas a += sintaxe do operador para registar um delegado de gestão de eventos. Assim, vais traduzir funcionalidades da linguagem como essa de volta para a operação fundamental que está a ser realizada (registo de eventos, neste exemplo).
• Sintaxe da linguagem de porta. Muitas destas alterações são transformações mecânicas simples, substituindo um símbolo por outro. Por exemplo, mudar ponto (.) para dois pontos (::).
• Procedimento de linguagem do porto. Algumas destas podem ser mudanças simples e repetitivas (como myObject.MyProperty para myObject.MyProperty()). Outros necessitam de alterações mais profundas (por exemplo, portar um procedimento que envolve o uso do System.Text.StringBuilder para um que envolva o uso do std::wostringstream).
• Tarefas relacionadas com portabilidade que são específicas para C++/WinRT. Certos detalhes do Windows Runtime são tratados implicitamente pelo C#, nos bastidores. Esses detalhes são feitos explicitamente em C++/WinRT. Um exemplo é que usas um .idl ficheiro para definir as tuas classes de runtime.

Após o índice baseado em tarefas que se segue, as restantes secções deste tópico são estruturadas de acordo com a taxonomia acima.

Encontre conteúdo com base na tarefa que está a realizar

Alterações que envolvem a projeção da linguagem

Registar/revogar um gestor de eventos

Em C++/WinRT, tens várias opções sintáticas para registar/revogar um delegado handler de eventos, conforme descrito em Handle events, usando delegados em C++/WinRT. Veja também como portar o método EnableClipboardContentChangedNotifications.

Por vezes, por exemplo, quando um destinatário de um evento (um objeto que processa um evento) está prestes a ser destruído, vai querer remover um processador de eventos para que a fonte do evento (o objeto que gera o evento) não invoque um objeto destruído. Ver Revogar um delegado registado. Nesses casos, cria uma variável event_token membro para os teus gestores de eventos. Para um exemplo, veja Portar o método EnableClipboardContentChangedNotifications.

Também pode registar um processador de eventos na linguagem de marcação XAML.

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

Em C#, o teu método OpenButton_Click pode ser privado, e o XAML ainda poderá ligá-lo ao evento ButtonBase.Click gerado pelo OpenButton.

Em C++/WinRT, o seu método OpenButton_Click deve ser público no seu tipo deimplementação se quiser registar o método em marcação XAML. Se registares um gestor de eventos apenas em código imperativo, então o gestor de eventos não precisa de ser 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);
    }
};

Em alternativa, pode tornar a página XAML registada como amiga do seu tipo de implementação e OpenButton_Click privada.

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);
    }
};

Um último cenário é quando o projeto C# que estás a portar se liga para o gestor de eventos a partir da marcação (para mais contexto sobre esse cenário, vê Funções em x:Bind).

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

Podes simplesmente mudar essa marcação para a mais simples Click="OpenButton_Click". Ou, se preferires, podes manter essa margem como está. Tudo o que tens de fazer para o suportar é declarar o gestor de eventos no IDL.

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

Alterações que envolvem a sintaxe da linguagem

Migração de classes e membros

Terá de decidir, para cada tipo de C#, se o deve migrar para um tipo do Windows Runtime ou para uma classe/estrutura/enumeração normal de C++. Para mais informações e exemplos detalhados que ilustrem como tomar essas decisões, veja Portar o exemplo do Clipboard para C++/WinRT a partir do C#.

Uma propriedade C# torna-se tipicamente uma função de acesso, uma função mutadora e um elemento de dados de apoio. Para mais informações e um exemplo, veja Migrar a propriedade IsClipboardContentChangedEnabled.

Para campos não estáticos, torne-os membros de dados do teu tipo de implementação.

Um campo estático C# torna-se uma função de acesso estática C++/WinRT e/ou uma função modificadora. Para mais informações e um exemplo, veja Porting the constructor, Current e FEATURE_NAME.

Para funções-membro, mais uma vez, terá de decidir, relativamente a cada uma, se deve ou não constar da IDL, ou se é uma função-membro pública ou privada do seu tipo de implementação. Para mais informações e exemplos de como decidir, veja IDL para o tipo MainPage.

Portar marcação XAML e ficheiros de recursos

No caso de portar a amostra do Clipboard para C++/WinRT a partir do C#, conseguimos usar a mesma marcação XAML (incluindo recursos) e ficheiros de assets em todo o projeto C# e C++/WinRT. Em alguns casos, serão necessárias edições na marcação para que isso se consiga. Consulte Copiar o XAML e os estilos necessários para concluir a migração de MainPage.

Alterações que envolvem procedimentos dentro da linguagem

As secções seguintes detalham alguns dos itens da tabela.

Construção dos elementos UI

Estes exemplos de código mostram a construção de um elemento UI no código imperativo de uma 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()

Os tipos C# fornecem o método Object.ToString .

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

O C++/WinRT não oferece esta funcionalidade diretamente, mas pode recorrer a alternativas.

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

C++/WinRT também suporta winrt::to_hstring para um número limitado de tipos. Terás de adicionar sobrecargas para quaisquer tipos adicionais que queiras stringificar.

No caso de converter um enum em string, terá de fornecer a implementação 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 conversões em cadeia de caracteres são frequentemente utilizadas de forma implícita pela associação de dados.

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

Estas ligações executarão winrt::to_hstring da propriedade vinculada. No caso do segundo exemplo (o StatusEnum), deve fornecer a sua própria sobrecarga de winrt::to_hstring; caso contrário, irá obter um erro de compilação.

Veja também a portabilidade do método Footer_Click.

Construção de cordas

Para construção de cordas, o C# tem um tipo StringBuilder incorporado.

Veja também Portar o método BuildClipboardFormatsOutputString e Portar o método DisplayChangedFormats.

Execução de código na thread principal da IU

Este exemplo é retirado da amostra do leitor de códigos de barras.

Quando queres trabalhar na thread principal da interface num projeto C#, normalmente usas o método DispatcherQueue.TryEnqueue (ou o antigo CoreDispatcher.RunAsync no UWP). Aqui está como é o padrão em C#.

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

É muito mais simples expressar isso em C++/WinRT. Note que estamos a aceitar parâmetros pelo valor na suposição de que queremos aceder a eles após o primeiro ponto de suspensão (o co_await, neste caso). Para mais informações, veja Passagem 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.
}

Se tiver de efetuar o trabalho com uma prioridade que não a predefinida, consulte a função winrt::resume_foreground, que dispõe de uma sobrecarga que aceita um argumento de prioridade. Para obter exemplos de código que mostram como aguardar uma chamada a winrt::resume_foreground, consulte Programação tendo em conta a afinidade de thread.

Tarefas relacionadas com portabilidade específicas para C++/WinRT

Defina as suas classes de runtime no IDL

Veja IDL para o tipo MainPage e Consolide os seus .idl ficheiros.

Inclua os ficheiros de cabeçalho do namespace Windows C++/WinRT que precisa

No C++/WinRT, sempre que quiser utilizar um tipo de um namespace do Windows, tem de incluir o ficheiro de cabeçalho C++/WinRT correspondente ao namespace do Windows. Para um exemplo, veja Portar o método NotifyUser.

Boxe e desembalagem

C# encaixa automaticamente escalares em objetos. O C++/WinRT exige que chames explicitamente a função winrt::box_value . Ambas as línguas exigem que desembales explicitamente. Consulte Boxing e unboxing com C++/WinRT.

Nas tabelas que se seguem, usaremos estas definições.

C++/CX e C# criam exceções se tentares abrir um ponteiro nulo para um tipo de valor. O C++/WinRT considera isto um erro de programação, e crasha. Em C++/WinRT, usa a função winrt::unbox_value_or se quiseres lidar com o caso em que o objeto não é do tipo que pensavas.

Para um exemplo, veja Portar o método OnNavigatedTo e Portar o método Footer_Click.

Boxe e desembalagem de uma corda

Uma cadeia é, de certa forma, um tipo de valor e, noutros aspetos, um tipo de referência. C# e C++/WinRT tratam as cadeias de forma diferente.

O tipo ABI HSTRING é um apontador para uma cadeia contada por referência. Mas não deriva de IInspectable, por isso tecnicamente não é um objeto. Além disso, uma HSTRING nula representa a cadeia vazia. O empacotamento de elementos não derivados de IInspectable faz-se envolvendo-os num IReference<T>, e o Windows Runtime fornece uma implementação padrão sob a forma do objeto PropertyValue (os tipos personalizados são indicados como PropertyType::OtherType).

C# representa uma string do Windows Runtime como tipo de referência; enquanto C++/WinRT projeta uma string como tipo de valor. Isto significa que uma cadeia nula em caixa pode ter representações diferentes dependendo de como lá chegaste.

Boxe básico e desencaixe.

Disponibilizar uma classe para a extensão de marcação {Binding}

Se pretender usar a extensão de marcação {Binding} para estabelecer uma associação de dados ao seu tipo de dados, consulte objeto Binding declarado com {Binding}.

Consumir objetos a partir da marcação XAML

Num projeto C#, pode consumir membros privados e elementos nomeados a partir da marcação XAML. Mas em C++/WinRT, todas as entidades consumidas ao usar a extensão de marcação XAML {x:Bind} devem ser expostas publicamente em IDL.

Além disso, a vinculação a um Boolean apresenta true ou false em C#, mas mostra Windows.Foundation.IReference`1<Boolean> em C++/WinRT.

Para mais informações e exemplos de código, consulte Consumir objetos a partir de marcação.

Disponibilizar uma fonte de dados para marcação XAML

Em C++/WinRT versão 2.0.190530.8 ou posterior, winrt::single_threaded_observable_vector cria um vetor observável que suporta tanto IObservableVector<T> como IObservableVector<IInnspectable>. Para um exemplo, veja a propriedade Porting the Scenarios.

Pode redigir o seu ficheiro Midl (.idl) desta forma (veja também Dividir classes de runtime em ficheiros 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 assim.

// 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 mais informações, consulte controlos de itens XAML; vincular a uma coleção C++/WinRT e Coleções com C++/WinRT.

Disponibilizar uma fonte de dados para marcação XAML (antes do C++/WinRT 2.0.190530.8)

A ligação de dados XAML requer que a origem dos itens implemente IIterable<IInspectable>, bem como uma das seguintes combinações de interfaces.

• IObservableVector<IInspectable>
• IBindableVector e INotifyCollectionChanged
• IBindableVector e IBindableObservableVector
• IBindableVector sozinho (não responde a alterações)
• IVector<IInspectable>
• IBindableIterable (irá iterar e guardar elementos numa coleção privada)

Uma interface genérica como a IVector<T> não pode ser detetada em tempo de execução. Cada IVector<T> tem um identificador de interface (IID) diferente, que é uma função de T. Qualquer programador pode expandir o conjunto de T arbitrariamente, pelo que claramente o código de ligação XAML nunca pode saber o conjunto completo a consultar. Essa restrição não é um problema para C# porque todos os objetos CLR que implementam IEnumerable<T> implementam automaticamente IEnumerable. Ao nível da ABI, isso significa que todos os objetos que implementam IObservableVector<T> implementam automaticamente IObservableVector<IInspectable>.

O C++/WinRT não oferece essa garantia. Se uma classe de runtime C++/WinRT implementar IObservableVector<T>, então não podemos assumir que uma implementação de IObservableVector<IInspectable> também seja fornecida de alguma forma.

Consequentemente, aqui está como o exemplo anterior terá de ser.

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

E a implementação.

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

Se precisares de aceder a objetos em m_bookSkus, terás de fazer QI novamente para 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;
}

Classes derivadas

Para derivar de uma classe de execução, a classe base deve ser componível. C# não exige que tomes medidas especiais para tornar as tuas classes componíveis, mas C++/WinRT sim. Usas a palavra-chave não selada para indicar que queres que a tua classe seja utilizável como classe base.

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

No ficheiro de cabeçalho do seu tipo de implementação, deve incluir o ficheiro de cabeçalho da classe base antes de incluir o cabeçalho gerado automaticamente para a classe derivada. Caso contrário, vais receber erros como "Uso ilegal deste tipo como expressão".

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

APIs importantes

• Espaço de nomes winrt

Tópicos relacionados

• tutoriais em C#
• C++/WinRT
• Vinculação de dados em profundidade