Passer de C# à C++/WinRT

Cette rubrique répertorie en détail les détails techniques impliqués dans le portage du code source dans un projet C# vers son équivalent en C++/WinRT.

Pour une étude de cas sur le portage de l’un des exemples d’application Plateforme Windows universelle (UWP), consultez la rubrique complémentaire Portage de l’exemple Presse-papiers vers C++/WinRT à partir de C#. Vous pouvez acquérir une pratique de portage et une expérience en suivant cette procédure pas à pas et en transférant l’exemple pour vous-même à mesure que vous le souhaitez.

Comment préparer et ce à quoi s’attendre

L’étude de cas Portage de l’exemple Presse-papiers vers C++/WinRT depuis C# illustre des exemples de décisions de conception logicielle que vous serez amené à prendre lors du portage d’un projet vers C++/WinRT. Il est donc judicieux de se préparer au portage en obtenant une bonne compréhension du fonctionnement du code existant. De cette façon, vous obtiendrez une bonne vue d’ensemble des fonctionnalités de l’application et de la structure du code, puis les décisions que vous prenez vous aideront toujours à avancer, et dans la bonne direction.

En termes de types de modifications de portage à attendre, vous pouvez les regrouper en quatre catégories.

• Migrer la projection linguistique. Le Windows Runtime (WinRT) est projeté dans différents langages de programmation. Chacune de ces projections de langage est conçue pour être idiomatique dans le langage de programmation concerné. Pour C#, certains types Windows Runtime sont projetés en tant que types .NET. Par exemple, vous allez traduire System.Collections.Generic.IReadOnlyList<T> en Windows. Foundation.Collections.IVectorView<T>. En outre, dans C#, certaines opérations Windows Runtime sont projetées en tant que fonctionnalités de langage C# pratiques. Par exemple, dans C#, vous utilisez la syntaxe de l’opérateur += pour inscrire un délégué de gestion des événements. Vous allez donc traduire des fonctionnalités de langage comme celle-ci vers l’opération fondamentale en cours d’exécution (inscription d’événements, dans cet exemple).
• Syntaxe du langage de port. La plupart de ces changements sont des transformations mécaniques simples, en remplaçant un symbole pour un autre. Par exemple, en remplaçant le point (.) par deux-points (::).
• Procédure de langue de port. Certains d’entre eux peuvent être des modifications simples et répétitives (par exemple myObject.MyPropertymyObject.MyProperty()). D’autres ont besoin de modifications plus approfondies (par exemple, le portage d’une procédure qui implique l’utilisation de System.Text.StringBuilder vers une autre qui implique l’utilisation de std ::wostringstream).
• Tâches liées au portage spécifiques à C++/WinRT. Certains détails de la Windows Runtime sont pris en charge implicitement par C#, en arrière-plan. Ces détails sont effectués explicitement en C++/WinRT. Par exemple, vous utilisez un .idl fichier pour définir vos classes runtime.

Après l’index basé sur les tâches qui suit, les autres sections de cette rubrique sont structurées en fonction de la taxonomie ci-dessus.

Rechercher du contenu en fonction de la tâche que vous effectuez

Modifications qui impliquent la projection de langage

Inscrire/révoquer un gestionnaire d’événements

Dans C++/WinRT, vous avez plusieurs options syntactiques pour inscrire/révoquer un délégué de gestionnaire d’événements, comme décrit dans Gérer les événements à l’aide de délégués en C++/WinRT. Voir également Portage de la méthode EnableClipboardContentChangedNotifications.

Parfois, quand un destinataire d’événement (objet qui gère un événement) est sur le point d’être détruit, vous voudrez révoquer un gestionnaire d’événements afin que la source d’événement (l’objet qui déclenche l’événement) n’appelle pas un objet détruit. Voir Révoquer un délégué inscrit. Dans ce cas, créez une variable membre event_token pour vos gestionnaires d’événements. Pour obtenir un exemple, consultez Portage de la méthode EnableClipboardContentChangedNotifications.

Vous pouvez également inscrire un gestionnaire d’événements dans le balisage XAML.

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

En C#, votre méthode de OpenButton_Click peut être privée et XAML peut toujours la connecter à l’événement ButtonBase.Click déclenché par OpenButton.

Dans C++/WinRT, votre méthode OpenButton_Click doit être publique dans votre type d’implémentationsi vous souhaitez l’inscrire dans le balisage XAML. Si vous inscrivez un gestionnaire d’événements uniquement dans le code impératif, le gestionnaire d’événements n’a pas besoin d’être public.

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

Vous pouvez également accorder à la page XAML qui effectue l’enregistrement un accès ami à votre type d’implémentation et déclarer OpenButton_Click comme privé.

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 scénario final est l’endroit où le projet C# que vous transférez est lié au gestionnaire d’événements à partir du balisage (pour plus d’informations sur ce scénario, consultez Functions dans x :Bind).

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

Vous pourriez simplement changer ce balisage en plus simple Click="OpenButton_Click". Ou, si vous préférez, vous pouvez conserver ce balisage tel qu’il est. Pour le prendre en charge, il vous suffit de déclarer le gestionnaire d’événement dans l’IDL.

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

Modifications qui impliquent la syntaxe du langage

Portage de classes et de membres

Vous devez décider, pour chaque type C#, s'il faut le porter vers un type Windows Runtime ou vers une classe/struct/énumération C++ standard. Pour plus d’informations, ainsi que des exemples détaillés illustrant comment prendre ces décisions, consultez Portage de l’exemple Clipboard de C# vers C++/WinRT.

Une propriété C# devient généralement une fonction d’accesseur, une fonction de modification et un membre de données sous-jacent. Pour plus d’informations et un exemple, consultez Portage de la propriété IsClipboardContentChangedEnabled.

Pour les champs non statiques, faites-les membres de données de votre type d’implémentation.

Un champ statique C# devient un accesseur statique C++/WinRT et/ou une fonction mutateur. Pour plus d’informations et un exemple, consultez Portage du constructeur, Current et FEATURE_NAME.

Pour les fonctions membres, là encore, vous devez décider pour chacun d’eux s’il appartient ou non à l’IDL, ou s’il s’agit d’une fonction membre publique ou privée de votre type d’implémentation. Pour plus d’informations et des exemples de choix, consultez IDL pour le type MainPage.

Portage du balisage XAML et des fichiers de ressources

Dans le cas du portage de l’exemple Presse-papiers de C# vers C++/WinRT, nous avons pu utiliser le même code XAML (y compris les ressources) et les fichiers de ressources graphiques dans les projets C# et C++/WinRT. Dans certains cas, les modifications de balisage seront nécessaires pour y parvenir. Consultez Copier le code XAML et les styles nécessaires pour terminer le portage de MainPage.

Modifications impliquant des procédures dans la langue

Les sections suivantes décrivent plus en détail certains des éléments du tableau.

Construction d’éléments d’interface utilisateur

Ces exemples de code montrent la construction d’un élément d’interface utilisateur dans le code impératif d’une page 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()

Les types C# fournissent la méthode Object.ToString .

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

C++/WinRT ne fournit pas directement cette fonctionnalité, mais vous pouvez vous tourner vers des alternatives.

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

C++/WinRT prend également en charge winrt ::to_hstring pour un nombre limité de types. Vous devrez ajouter des surcharges pour tout type supplémentaire que vous souhaitez convertir en chaîne.

Dans le cas de la conversion d’une énumération en chaîne, vous devrez fournir l’implémentation 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));
        }
    }
}

Ces conversions en chaîne de caractères sont souvent utilisées implicitement par la liaison de données.

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

Ces liaisons de données appliquent winrt::to_hstring à la propriété liée. Dans le cas du deuxième exemple ( StatusEnum), vous devez fournir votre propre surcharge de winrt ::to_hstring, sinon vous obtiendrez une erreur du compilateur.

Consultez également Portage de la méthode Footer_Click.

Construction de chaînes de caractères

Pour la génération de chaînes, C# a un type StringBuilder intégré.

Consultez également Portage de la méthode BuildClipboardFormatsOutputString et Portage de la méthode DisplayChangedFormats.

Exécution de code sur le thread d’interface utilisateur principal

Cet exemple est extrait de l’exemple de scanneur de codes-barres.

Lorsque vous souhaitez travailler sur le thread d’interface utilisateur principal dans un projet C#, vous utilisez généralement la méthode DispatcherQueue.TryEnqueue (ou l’ancienne coreDispatcher.RunAsync dans UWP). Voici à quoi ressemble le modèle en C#.

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

Il est beaucoup plus simple d’exprimer cela en C++/WinRT. Notez que nous acceptons les paramètres par valeur sur l’hypothèse que nous voulons y accéder après le premier point de suspension ( co_awaitdans ce cas). Pour plus d’informations, consultez Passage de paramètre.

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

Si vous devez effectuer le travail avec une priorité autre que celle par défaut, reportez-vous à la fonction winrt::resume_foreground, qui possède une surcharge acceptant une priorité en paramètre. Pour obtenir des exemples de code montrant comment attendre un appel à winrt ::resume_foreground, consultez Programmation avec affinité de thread à l’esprit.

Tâches liées au portage spécifiques à C++/WinRT

Définissez vos classes d’exécution en IDL

Consultez IDL pour le type MainPage et Consolidez vos .idl fichiers.

Incluez les fichiers d’en-tête de l’espace de noms Windows C++/WinRT dont vous avez besoin

Dans C++/WinRT, chaque fois que vous souhaitez utiliser un type à partir d’un espace de noms Windows, vous devez inclure le fichier d’en-tête d’espace de noms C++/Win Windows RT correspondant. Pour obtenir un exemple, consultez Portage de la méthode NotifyUser.

Boxing et unboxing

C# encapsule automatiquement les valeurs scalaires dans des objets. C++/WinRT vous oblige à appeler explicitement la fonction winrt ::box_value . Les deux langages exigent un déballage explicite. Consultez Boxing et unboxing avec C++/WinRT.

Dans les tables qui suivent, nous allons utiliser ces définitions.

C++/CX et C# déclenchent des exceptions si vous essayez de dissocier un pointeur Null vers un type valeur. C++/WinRT considère cette erreur de programmation et se bloque. Dans C++/WinRT, utilisez la fonction winrt ::unbox_value_or si vous souhaitez gérer le cas où l’objet n’est pas du type que vous pensiez.

Pour obtenir un exemple, consultez Portage de la méthode OnNavigatedTo et Portage de la méthode Footer_Click.

Boxing et unboxing d’une chaîne

Une chaîne est d’une certaine manière un type valeur et d’autres façons un type référence. C# et C++/WinRT traitent les chaînes différemment.

Le type ABI HSTRING est un pointeur vers une chaîne comptée par référence. Mais il ne dérive pas d’IInspectable, donc il n’est pas techniquement un objet. En outre, un HSTRING null représente la chaîne vide. L’encapsulage des éléments qui ne dérivent pas de IInspectable s’effectue en les enveloppant dans un IReference<T>, et Windows Runtime fournit une implémentation standard sous la forme de l’objet PropertyValue (les types personnalisés sont signalés comme PropertyType::OtherType).

C# représente une chaîne Windows Runtime en tant que type référence ; tandis que C++/WinRT projette une chaîne en tant que type valeur. Cela signifie qu’une chaîne null boxée peut avoir différentes représentations selon la façon dont vous y êtes arrivé.

Boxing de base et unboxing.

Mise à disposition d’une classe pour l’extension de balisage {Binding}

Si vous envisagez d’utiliser l’extension de balisage {Binding} pour lier des données à votre type de données, consultez l’objet Binding déclaré à l’aide de {Binding}.

Consommation d’objets à partir du balisage XAML

Dans un projet C#, vous pouvez consommer des membres privés et des éléments nommés à partir du balisage XAML. Toutefois, dans C++/WinRT, toutes les entités consommées à l’aide de l’extension de balisage XAML {x :Bind} doivent être exposées publiquement dans IDL.

En outre, la liaison à un booléen affiche true ou false en C#, mais elle affiche Windows. Foundation.IReference'1<Boolean> en C++/WinRT.

Pour plus d’informations et pour obtenir des exemples de code, consultez Consommation d’objets à partir du balisage.

Mise à disposition d’une source de données pour le balisage XAML

Dans la version 2.0.190530.8 ou ultérieure de C++/WinRT, winrt::single_threaded_observable_vector crée un vecteur observable qui prend en charge à la fois IObservableVector<T> et IObservableVector<IInspectable>. Pour obtenir un exemple, consultez Portage de la propriété Scenarios.

Vous pouvez rédiger votre fichier Midl (.idl) comme ceci (voir également la factorisation des classes d’exécution dans des fichiers 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; };
    }
}

Et implémentez comme ça.

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

Pour plus d’informations, consultez contrôles d’éléments XAML ; liaison à une collection C++/WinRT et Collections avec C++/WinRT.

Mise à disposition d’une source de données pour le balisage XAML (avant C++/WinRT 2.0.190530.8)

La liaison de données XAML nécessite qu’une source d’éléments implémente IIterable<IInspectable>, ainsi que l’une des combinaisons d’interfaces suivantes.

• IObservableVector<IInspectable>
• IBindableVector et INotifyCollectionChanged
• IBindableVector et IBindableObservableVector
• IBindableVector lui-même (ne répond pas aux modifications)
• IVector<IInspectable>
• IBindableIterable (itérera et enregistrera des éléments dans une collection privée)

Une interface générique telle que IVector<T> ne peut pas être détectée au moment de l’exécution. Chaque IVector<T> a un identificateur d’interface (IID), qui est une fonction de T. Tout développeur peut développer arbitrairement l’ensemble de T , de sorte que le code de liaison XAML ne peut jamais connaître l’ensemble complet à interroger. Cette restriction n’est pas un problème pour C# car chaque objet CLR qui implémente IEnumerable<T> implémente automatiquement IEnumerable. Au niveau ABI, cela signifie que chaque objet qui implémente IObservableVector<T> implémente automatiquement IObservableVector<IInspectable>.

C++/WinRT n’offre pas cette garantie. Si une classe runtime C++/WinRT implémente IObservableVector<T>, nous ne pouvons pas supposer qu’une implémentation d’IObservableVector<IInspectable> est également fournie.

Par conséquent, voici comment l’exemple précédent devra ressembler.

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

Et l’implémentation.

// 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 vous avez besoin d’accéder à des objets dans m_bookSkus, vous devez revenir à 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 dérivées

Pour dériver d’une classe runtime, la classe de base doit être composable. C# ne vous oblige pas à prendre des mesures particulières pour rendre vos classes composables, alors que C++/WinRT l’exige. Vous utilisez le mot clé non scellé pour indiquer que votre classe doit être utilisable en tant que classe de base.

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

Dans le fichier d’en-tête de votre type d’implémentation, vous devez inclure le fichier d’en-tête de classe de base avant d’inclure l’en-tête généré automatiquement pour la classe dérivée. Sinon, vous obtiendrez des erreurs telles que « Utilisation illégale de ce type en tant qu’expression ».

// 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

• espace de noms WinRT

Rubriques connexes

• Tutoriels C#
• C++/WinRT
• Présentation détaillée de la liaison de données