Mover do C# para C++/WinRT

Este tópico descreve os detalhes técnicos envolvidos na portabilidade do código-fonte em um projeto C# para o equivalente no C++/WinRT.

Para obter um estudo de caso de portabilidade de um dos exemplos de aplicativo UWP (Plataforma Universal do Windows), confira o tópico complementar Como portar a amostra de área de transferência para o C++/WinRT do C#. Você pode adquirir prática e experiência em portabilidade seguindo o passo a passo e fazendo a portabilidade da amostra por conta própria durante as etapas.

Como se preparar e o que esperar

O estudo de caso Como portar a amostra de área de transferência para o C++/WinRT do C# ilustra exemplos dos tipos de decisões de design de software que você tomará ao portar um projeto para o C++/WinRT. Portanto, é uma boa ideia se preparar para a portabilidade adquirindo uma compreensão substancial de como o código existente funciona. Dessa forma, você obterá uma boa visão geral da funcionalidade do aplicativo e da estrutura do código, e as decisões que você tomará sempre o conduzirão para frente e na direção certa.

Em relação a quais tipos de portabilidade devem ser esperados, é possível agrupá-los em quatro categorias.

• Portar a projeção de linguagem. O WinRT (Windows Runtime) é projetado em várias linguagens de programação. Cada uma dessas projeções de linguagem foi criada para dar um aspecto idiomático à linguagem de programação em questão. Quanto ao C#, alguns tipos do Windows Runtime foram projetados como tipos .NET. Por exemplo, você converterá System.Collections.Generic.IReadOnlyList<T> novamente em Windows.Foundation.Collections.IVectorView<T>. Também em C#, algumas operações do Windows Runtime foram projetadas como recursos da linguagem C# convenientes. Um exemplo é que, em C#, você usa a sintaxe do operador += para registrar um delegado de processamento de eventos. Portanto, você converterá recursos de linguagem como esse novamente na operação fundamental que está sendo executada (registro de evento, neste exemplo).
• Portar a sintaxe da linguagem. Muitas dessas alterações são transformações mecânicas simples, com a substituição de um símbolo por outro. Por exemplo, alteração do ponto (.) para dois-pontos (::).
• Portar o procedimento da linguagem. Algumas dessas podem ser alterações simples e repetitivas (como myObject.MyProperty para myObject.MyProperty()). Outras precisam de alterações mais profundas (por exemplo, portar um procedimento que envolve o uso de System.Text.StringBuilder para um que envolve o uso de std::wostringstream).
• Tarefas relacionadas à portabilidade que são específicas para o C++/WinRT. Alguns detalhes do Windows Runtime são resolvidos implicitamente pelo C#, nos bastidores. Esses detalhes são realizados explicitamente no C++/WinRT. Um exemplo disso é que você usa um arquivo .idl para definir as classes de runtime.

Após o índice baseado em tarefa a seguir, o restante das seções deste tópico é estruturado de acordo com a taxonomia acima.

Localizar um conteúdo com base na tarefa que você está executando

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

Registrar/revogar um manipulador de eventos

No C++/WinRT, há várias opções sintáticas para registrar/revogar um delegado de manipulador de eventos, conforme descrito em Processar eventos usando delegados no C++/WinRT. Confira também Como portar o método EnableClipboardContentChangedNotifications.

Às vezes, por exemplo, quando um destinatário de evento (um objeto que processa um evento) está prestes a ser destruído, o ideal é revogar um manipulador de eventos para que a origem do evento (o objeto que gera o evento) não chame um objeto destruído. Veja Revogar um delegado registrado. Em casos como esse, crie uma variável de membro event_token para os manipuladores de eventos. Para obter um exemplo, confira Como portar o método EnableClipboardContentChangedNotifications.

Você também pode registrar um manipulador de eventos na marcação XAML.

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

No C#, o método OpenButton_Click pode ser privado e o XAML ainda poderá conectá-lo ao evento ButtonBase.Click gerado por OpenButton.

No C++/WinRT, o método OpenButton_Click precisará ser público no tipo de implementação se você desejar registrá-lo na marcação XAML. Se você registrar um manipulador de eventos somente no código imperativo, o manipulador de eventos não precisará ser público.

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

Como alternativa, você pode tornar o registro da página XAML um amigo do tipo de implementação e o OpenButton_Click privado.

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

Um último cenário é quando o projeto C# que você está portando se associa ao manipulador de eventos da marcação (para obter mais informações sobre esse cenário, confira Funções em x:Bind).

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

Você pode alterar essa marcação para o Click="OpenButton_Click" mais simples. Ou, caso prefira, você pode manter essa marcação como está. Tudo o que você precisa fazer para dar suporte a ela é declarar o manipulador de eventos em IDL.

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

Alterações que envolvem a sintaxe de linguagem

Como portar classes e membros

Você precisará decidir, para cada tipo C#, se desejará portá-lo para um tipo do Windows Runtime ou para uma classe/um struct/uma numeração C++ normal. Para obter mais informações e exemplos detalhados que ilustram como tomar essas decisões, confira Como portar a amostra de área de transferência para o C++/WinRT do C#.

Uma propriedade C# normalmente se torna uma função de acessador, uma função de modificador e um membro de dados de backup. Para obter mais informações e um exemplo, confira Como portar a propriedade IsClipboardContentChangedEnabled.

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

Um campo estático C# torna-se um acessador estático e/ou uma função de modificador C++/WinRT. Para obter mais informações e um exemplo, confira Como portar o construtor, Current e FEATURE_NAME.

Para as funções de membro, novamente, você precisará decidir para cada uma delas se pertencem ou não à IDL ou se elas são uma função de membro pública ou privada do tipo de implementação. Para obter mais informações e exemplos de como tomar essa decisão, confira IDL para o tipo MainPage.

Como portar a marcação XAML e os arquivos de ativos

No caso de Como portar a amostra de área de transferência para o C++/WinRT do C#, pudemos usar a mesma marcação XAML (incluindo os recursos) e os arquivos de ativos em todo o projeto C# e C++/WinRT. Em alguns casos, as edições na marcação serão necessárias para conseguir isso. Confira Copiar o XAML e os estilos necessários para concluir a portabilidade de MainPage.

Alterações que envolvem procedimentos dentro da linguagem

As seções a seguir fornecem mais detalhes em relação a alguns dos itens da tabela.

construção de instrução da interface do usuário

Estes exemplos de código mostram a construção de um elemento da interface do usuário no código imperativo de uma página XAML.

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

TextBlock myTextBlock;
myTextBlock.Text(L"Text");
myTextBlock.Style(
    winrt::unbox_value<Windows::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 fornece diretamente esse recurso, mas você poderá usar alternativas.

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

O C++/WinRT também dá suporte a winrt::to_hstring em um número limitado de tipos. Você precisará adicionar sobrecargas para os tipos adicionais que deseja converter em cadeia de caracteres.

No caso da conversão de uma enumeração em cadeia de caracteres, você precisará 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));
        }
    }
}

Em geral, essas conversões em cadeia de caracteres são consumidas implicitamente pela vinculação de dados.

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

Essas associações executarão winrt::to_hstring da propriedade associada. No caso do segundo exemplo (o StatusEnum), você precisará fornecer sua própria sobrecarga de winrt::to_hstring; caso contrário, obterá um erro do compilador.

Confira também Como portar o método Footer_Click.

Construção da cadeia de caracteres

Para a construção de cadeia de caracteres, o C# tem um tipo StringBuilder interno.

Confira também Como portar o método BuildClipboardFormatsOutputString e Como portar o método DisplayChangedFormats.

Executar código no thread da IU principal

Este exemplo é obtido do exemplo de scanner de código de barras.

Quando você deseja trabalhar no thread da IU principal em um projeto C#, normalmente você usa o método CoreDispatcher.RunAsync, assim.

private async void Watcher_Added(DeviceWatcher sender, DeviceInformation args)
{
    await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
    {
        // Do work on the main UI thread here.
    });
}

É muito mais simples expressar isso em C++/WinRT. Observe que estamos aceitando parâmetros por valor na pressuposição que desejaremos acessá-los após o primeiro ponto de suspensão (co_await, nesse caso). Para obter mais informações, consulte Passagem de parâmetros.

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

Se você precisar fazer o trabalho com uma prioridade diferente do padrão, confira a função winrt::resume_foreground, que tem uma sobrecarga que recebe uma prioridade. Para obter exemplos de código que mostram como aguardar uma chamada para winrt::resume_foreground, confira Programando com a afinidade de thread em mente.

Tarefas relacionadas à portabilidade que são específicas para o C++/WinRT

Definir as classes de runtime na IDL

Confira IDL para o tipo MainPage e Consolidar os arquivos .idl.

Incluir os arquivos de cabeçalho do namespace C++/WinRT do Windows de que você precisa

No C++/WinRT, sempre que desejar usar um tipo de um namespace do Windows, inclua o arquivo de cabeçalho do namespace C++/WinRT do Windows correspondente. Para obter um exemplo, confira Como portar o método NotifyUser.

Conversão boxing e unboxing

O C# faz a conversão boxing automática de escalares em objetos. O C++/WinRT exige que você chame explicitamente a função winrt::box_value. Ambas as linguagens exigem que você faça a conversão unboxing explicitamente. Confira Conversão boxing e unboxing com o C++/WinRT.

Nas tabelas a seguir, usaremos estas definições.

O C++/CX e o C# gerarão exceções se você tentar fazer a conversão unboxing de um ponteiro nulo em um tipo de valor. O C++/WinRT considera isso um erro de programação e falha. No C++/WinRT, use a função winrt::unbox_value_or se desejar lidar com o caso em que o objeto não é do tipo que você pensou que fosse.

Para obter um exemplo, confira Como portar o método OnNavigatedTo e Como portar o método Footer_Click.

Conversão boxing e unboxing de uma cadeia de caracteres

Uma cadeia de caracteres é, de algumas maneiras, um tipo de valor e, de outras, um tipo de referência. O C# e o C++/WinRT tratam as cadeias de caracteres de maneira diferente.

O tipo do ABI HSTRING é um ponteiro para uma cadeia de caracteres de contagem de referências. Mas ele não é derivado de IInspectable, portanto, não é tecnicamente um objeto. Além disso, um HSTRING nulo representa a cadeia de caracteres vazia. A conversão boxing de itens não derivados de IInspectable é feita encapsulando-os dentro de um IReference<T> e o Windows Runtime fornece uma implementação padrão na forma do objeto PropertyValue (os tipos personalizados são relatados como PropertyType::OtherType).

O C# representa uma cadeia de caracteres do Windows Runtime como um tipo de referência, enquanto o C++/WinRT projeta uma cadeia de caracteres como um tipo de valor. Isso significa que uma cadeia de caracteres nula convertida pode ter diferentes representações, dependendo do procedimento adotado.

Conversões boxing e unboxing básicas.

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

Se você pretende usar a extensão de marcação {Binding} para associar dados ao tipo de dados, confira Objeto de associação declarado usando {Binding}.

Como consumir objetos por meio da marcação XAML

Em um projeto C#, você pode consumir membros privados e elementos nomeados por meio da marcação XAML. Mas no C++/WinRT, todas as entidades consumidas com o uso da extensão de marcação XAML {x:Bind} precisam ser expostas publicamente em IDL.

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

Para obter mais informações e exemplos de código, confira Como consumir objetos para marcação.

Como disponibilizar uma fonte de dados para marcação XAML

No C++/WinRT 2.0.190530.8 ou superior, winrt::single_threaded_observable_vector cria um vetor observável que dá suporte a IObservableVector<T> e a IObservableVector<IInspectable>. Para obter um exemplo, confira Como portar a propriedade Scenarios.

Você pode criar o arquivo MIDL (.idl) desta forma (confira também Como fatorar classes de runtime em arquivos MIDL (.idl)).

namespace Bookstore
{
    runtimeclass BookSku { ... }

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

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

Depois, implemente-o desta forma.

// 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 obter informações, confira Controles de itens XAML; associação a uma coleção do C++/WinRT e Coleções com C++/WinRT.

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

A vinculação de dados XAML exige que uma origem de itens implemente IIterable<IInspectable>, bem como uma das combinações de interfaces a seguir.

• IObservableVector<IInspectable>
• IBindableVector e INotifyCollectionChanged
• IBindableVector e IBindableObservableVector
• IBindableVector por si só (não responderá a alterações)
• IVector<IInspectable>
• IBindableIterable (iterará e salvará elementos em uma coleção particular)

Uma interface genérica, como IVector<T>, não pode ser detectada em runtime. Cada IVector<T> tem um IID (identificador de interface) distinto, que é uma função de T. Qualquer desenvolvedor pode expandir o conjunto de T de maneira arbitrária e, portanto, é evidente que o código de associação XAML nunca pode saber o conjunto completo a ser consultado. Essa restrição não é um problema para o C#, porque cada objeto CLR que implementa IEnumerable<T> implementa IEnumerable automaticamente. No nível do ABI, isso significa que cada objeto que implementa IObservableVector<T> implementa IObservableVector<IInspectable> automaticamente.

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

Consequentemente, veja abaixo como o exemplo anterior precisará ser examinado.

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

Veja também 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;
};
...

Caso você precise acessar objetos em m_bookSkus, precisará executar o 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 derivação de uma classe de runtime, a classe base precisa ser combinável. O C# não exige que você execute nenhuma etapa especial para tornar suas classes combináveis, ao contrário do C++/WinRT. Use a palavra-chave não selada para indicar que deseja que a classe seja utilizável como uma classe base.

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

Na classe do cabeçalho do tipo de implementação, inclua o arquivo de cabeçalho da classe base antes de incluir o cabeçalho gerado automaticamente da classe derivada. Caso contrário, você receberá erros como "uso ilícito deste tipo como uma 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

• namespace winrt

Tópicos relacionados

• Tutoriais do C#
• C++/WinRT
• Vinculação de dados em detalhes