Mover do C# para C++/WinRT

Este tópico cataloga de forma abrangente os detalhes técnicos envolvidos na portabilidade do código-fonte em um projeto C# para seu equivalente em 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, obtendo uma compreensão sólida de como o código existente funciona. Dessa forma, você terá uma boa visão geral da funcionalidade do aplicativo e da estrutura do código e, em seguida, as decisões tomadas sempre o levarão adiante e na direção certa.

Em termos dos tipos de alterações de portabilidade a serem esperadas, você pode agrupá-las em quatro categorias.

• Portar a projeção de linguagem. O Windows Runtime (WinRT) é projetado em várias linguagens de programação. Cada uma dessas projeções de linguagem foi projetada para se sentir idiomática para a linguagem de programação em questão. Para C#, alguns tipos de Windows Runtime são projetados como tipos de .NET. Portanto, por exemplo, você estará traduzindo System.Collections.Generic.IReadOnlyList<T> de volta para Windows. Foundation.Collections.IVectorView<T>. Também no C#, algumas operações de Windows Runtime são projetadas como recursos convenientes de linguagem C#. Um exemplo é que em C# você usa a sintaxe do += operador para registrar um delegado de manipulação de eventos. Portanto, você estará traduzindo recursos de linguagem como esse de volta para a operação fundamental que está sendo executada (registro de evento, neste exemplo).
• Sintaxe da linguagem de porta. Muitas dessas alterações são transformações mecânicas simples, substituindo um símbolo por outro. Por exemplo, alteração do ponto (.) para dois-pontos (::).
• Portar procedimento de linguagem. Algumas delas podem ser alterações simples e repetitivas (como myObject.MyProperty para myObject.MyProperty()). Outros precisam de alterações mais profundas (por exemplo, portar um procedimento que envolva o uso de System.Text.StringBuilder para um que envolva o uso de std::wostringstream).
• Tarefas de migração específicas do C++/WinRT. Alguns detalhes da Windows Runtime são tratados implicitamente pelo C#, nos bastidores. Esses detalhes são feitos explicitamente em C++/WinRT. Um exemplo é que você usa um .idl arquivo para definir suas classes de runtime.

Após o índice baseado em tarefas a seguir, o restante das seções neste tópico são estruturadas de acordo com a taxonomia acima.

Localizar 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, você tem várias opções sintacticas para registrar/revogar um delegado do manipulador de eventos, conforme descrito em Manipular eventos usando delegados em C++/WinRT. Confira também Como portar o método EnableClipboardContentChangedNotifications.

Às vezes, por exemplo, quando um destinatário de evento (um objeto que manipula um evento) está prestes a ser destruído, você deseja revogar um manipulador de eventos para que a origem do evento (o objeto que está gerando o evento) não chame um objeto destruído. Consulte Revogar um delegado registrado. Em casos como esse, crie uma variável membro event_token para os manipuladores de eventos. Para obter um exemplo, consulte Portando 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#, seu método OpenButton_Click pode ser privado e o XAML ainda poderá conectá-lo ao evento ButtonBase.Click gerado pelo OpenButton.

No C++/WinRT, seu método OpenButton_Click deve ser público no tipo de implementaçãose você quiser registrá-lo na marcação XAML. Se você registrar um manipulador de eventos apenas 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::Microsoft::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::Microsoft::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ê poderia apenas alterar essa marcação para o mais simples Click="OpenButton_Click". Ou, caso prefira, você pode manter essa marcação como está. Tudo o que você precisa fazer para dar suporte a ele é declarar o manipulador de eventos no IDL.

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

Alterações que envolvem a sintaxe do idioma

Como portar classes e membros

Você precisará decidir, para cada tipo de C#, se deve portá-lo para um tipo do Windows Runtime ou para uma classe/estrutura/enumeração C++ comum. 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 em C# torna-se uma função acessora estática e/ou mutadora do C++/WinRT. Para obter mais informações e um exemplo, confira Como portar o construtor, Current e FEATURE_NAME.

Para funções-membro, novamente, você precisará decidir para cada uma se ela deve ou não estar na IDL, ou se é uma função-membro pública ou privada do seu tipo de implementação. Para obter mais informações e exemplos de como decidir, consulte IDL para o tipo MainPage.

Migrando a marcação XAML e os arquivos de recursos

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, serão necessárias edições na marcação para alcançar isso. Consulte Como copiar o XAML e os estilos necessários para concluir a migração de MainPage.

Alterações que envolvem procedimentos dentro do idioma

As seções a seguir entram em mais detalhes sobre alguns dos itens na tabela.

Construção de elemento de interface

Esses exemplos de código mostram a construção de um elemento de interface do usuário 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 disponibiliza esse recurso diretamente, mas você pode recorrer a 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 para um número limitado de tipos. Você precisará adicionar sobrecargas para os tipos adicionais que deseja converter em cadeia de caracteres.

No caso de converter um enum 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ê deve fornecer sua própria sobrecarga de winrt::to_hstring, caso contrário, você receberá um erro do compilador.

Veja também Portando o método Footer_Click.

Construção de strings

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

Veja também a portabilidade do método BuildClipboardFormatsOutputString e a portabilidade do método DisplayChangedFormats.

Execução de código na thread principal da interface do usuário

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

Quando você deseja trabalhar no thread principal da interface do usuário em um projeto C#, normalmente usa o método DispatcherQueue.TryEnqueue (ou o CoreDispatcher.RunAsync mais antigo na UWP). Veja a aparência do 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. Observe que estamos aceitando parâmetros por valor na suposição de que queremos acessá-los após o primeiro ponto de suspensão (o co_await, neste caso). Para obter mais informações, consulte 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 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 suas classes de runtime no IDL

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

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

No C++/WinRT, sempre que você quiser usar um tipo de um dos namespaces do Windows, precisará incluir o arquivo de cabeçalho correspondente do namespace do Windows no C++/WinRT. Para obter um exemplo, consulte Portando 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 a função winrt::box_value explicitamente. Ambas as linguagens exigem que você desencaixote explicitamente. Consulte Boxing e unboxing com C++/WinRT.

Nas tabelas a seguir, usaremos essas 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 quiser lidar com o caso em que o objeto não é do tipo que você pensou que era.

Para obter um exemplo, consulte Portando o método OnNavigatedTo e portando o método Footer_Click.

Conversão boxing e unboxing de uma cadeia de caracteres

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

O tipo ABI HSTRING é um ponteiro para uma cadeia de caracteres com contagem de referências. Mas não deriva de IInspectable, portanto, tecnicamente não é 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).

C# representa uma cadeia de caracteres Windows Runtime como um tipo de referência; enquanto C++/WinRT projeta uma cadeia de caracteres como um tipo de valor. Isso significa que uma cadeia de caracteres nula em caixa pode ter representações diferentes dependendo de como você chegou lá.

Conversões boxing e unboxing básicas.

Tornando uma classe disponível para a extensão de marcação {Binding}

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

Como consumir objetos por meio da marcação XAML

Em um projeto C#, você pode acessar membros privados e elementos nomeados na marcação XAML. Mas, no C++/WinRT, todas as entidades consumidas usando a extensão de marcação XAML {x:Bind} devem ser expostas publicamente no IDL.

Além disso, vincular a um Boolean exibe true ou false em C#, mas exibe Windows.Foundation.IReference`1<Boolean> em C++/WinRT.

Para obter mais informações e exemplos de código, consulte Consuming objects from markup.

Disponibilizando uma fonte de dados para marcação XAML

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

Você pode escrever seu arquivo MIDL (.idl) assim (veja também Separando classes de runtime em arquivos 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 obter mais informações, consulte controles de itens XAML; associar a uma coleção C++/WinRT e Coleções com C++/WinRT.

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

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

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

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

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

Assim, veja como o exemplo anterior deverá ficar.

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

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 derivar de uma classe de tempo de execução, a classe base deve ser componível. O C# não exige que você execute etapas especiais para tornar suas classes redigidas, mas o C++/WinRT o faz. Use a palavra-chave não selada para indicar que deseja que sua classe seja utilizável como uma classe base.

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

No arquivo de cabeçalho do tipo de implementação, você deve incluir o arquivo de cabeçalho de classe base antes de incluir o cabeçalho gerado automaticamente para a classe derivada. Caso contrário, você receberá erros como "Uso ilegal desse 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 de C#
• C++/WinRT
• Vinculação de dados em profundidade