Passer de C# à C++/WinRT

Cette rubrique catalogue tous 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 concernant le portage de l’un des exemples d’application UWP (plateforme Windows universelle), consultez la rubrique complémentaire Portage de l’exemple Clipboard vers C++/WinRT à partir de C#. Vous pouvez bénéficier d’une pratique et d’une expérience de portage en suivant cette procédure pas à pas et en portant l’exemple pour vous-même au fur et à mesure.

Comment se préparer et à quoi s’attendre

L’étude de cas Portage de l’exemple Clipboard vers C++/WinRT à partir de C# présente les types de décisions que vous devrez prendre en matière de conception logicielle lors du portage d’un projet vers C++/WinRT. Il est donc judicieux de se préparer au portage en acquérant de solides connaissances du fonctionnement du code existant. De cette façon, vous aurez une bonne idée de la fonctionnalité de l’application et de la structure du code, et les décisions que vous prendrez vous feront toujours aller de l’avant et dans la bonne voie.

Vous pouvez regrouper les changements de portage à prévoir en quatre catégories.

• Porter la projection du langage. 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 en question. Pour C#, certains types Windows Runtime sont projetés en tant que types .NET. Par exemple, System.Collections.Generic.IReadOnlyList<T> sera traduit en Windows.Foundation.Collections.IVectorView<T>. Par ailleurs, en C#, certaines opérations Windows Runtime sont projetées en tant que fonctionnalités du langage C# par souci pratique. Par exemple, en C#, vous utilisez la syntaxe d’opérateur += pour inscrire un délégué de gestion d’événements. Vous allez donc traduire des fonctionnalités de langage comme celle-ci vers l’opération fondamentale effectuée (dans cet exemple, l’inscription d’événements).
• Porter la syntaxe du langage. Bon nombre de ces changements sont de simples transformations mécaniques consistant à remplacer un symbole par un autre. Citons par exemple le remplacement d’un point (.) par deux signes deux-points (::).
• Porter la procédure de langage. Certains de ces changements peuvent être simples et répétitifs (comme remplacer myObject.MyProperty par myObject.MyProperty()). D’autres peuvent être plus approfondis (comme porter une procédure impliquant l’utilisation de System.Text.StringBuilder vers une autre impliquant l’utilisation de std::wostringstream).
• Tâches relatives au portage spécifiques à C++/WinRT. Certains détails de Windows Runtime sont pris en charge implicitement par C# en arrière-plan. Ces détails sont définis explicitement en C++/WinRT. Par exemple, vous utilisez un fichier .idl pour définir vos classes runtime.

La liste ci-dessous est organisée par tâche, et les autres sections de cette rubrique suivent la taxonomie ci-dessus.

Rechercher du contenu relatif à la tâche à effectuer

Modifications qui impliquent la projection du langage

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

En C++/WinRT, vous disposez de plusieurs options syntaxiques pour inscrire/révoquer un délégué de gestionnaire d’événements, comme décrit dans Gérer des événements en utilisant des délégués en C++/WinRT. Consultez également Portage de la méthode EnableClipboardContentChangedNotifications.

Par exemple, quand un destinataire d’événement (objet gérant un événement) est sur le point d’être détruit, vous devrez parfois révoquer un gestionnaire d’événements pour que la source de l’événement (objet déclenchant l’événement) n’effectue pas d’appel dans l’objet détruit. Consultez Révoquer un délégué inscrit. Dans des cas comme celui-ci, 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" />

Dans C#, même si votre méthode OpenButton_Click est privée, XAML sera toujours en mesure de la connecter à l’événement ButtonBase.Click déclenché par OpenButton.

En C++/WinRT, votre méthode OpenButton_Click doit être publique dans votre type d’implémentation si vous souhaitez l’inscrire dans le balisage XAML. Si vous enregistrez un gestionnaire d’événements uniquement en 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::Windows::UI::Xaml::RoutedEventArgs const& args);
    }
};

Vous pouvez également faire en sorte que la page XAML d’inscription soit l’amie de votre type d’implémentation et définir OpenButton_Click en méthode privée.

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

Dernier scénario, le projet C# que vous portez est lié au gestionnaire d’événements à partir du balisage (pour plus de détails sur ce scénario, consultez Fonctions dans x:Bind).

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

Vous pouvez juste remplacer ce balisage par le Click="OpenButton_Click" plus simple. Ou, si vous préférez, vous pouvez conserver ce balisage tel quel. Pour le prendre en charge, il vous suffit de déclarer le gestionnaire d’événements dans l’IDL.

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

Modifications qui impliquent la syntaxe du langage

Portage des classes et des membres

Pour chaque type C#, vous devez décider si vous souhaitez le porter vers un type Windows Runtime ou vers une classe, un struct ou une énumération C++ normal. Pour obtenir plus d’informations et des exemples détaillés montrant comment prendre ces décisions, consultez Portage de l’exemple Clipboard vers C++/WinRT à partir de C#.

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

Configurez les champs non statiques en membres de données de votre type d’implémentation.

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

Là encore, pour chaque fonction membre, vous devez décider si elle appartient ou non à l’IDL ou si elle constitue une fonction membre publique ou privée de votre type d’implémentation. Pour obtenir plus d’informations et des exemples illustrant le processus de décision, consultez IDL pour le type MainPage.

Portage du balisage XAML et des fichiers de ressources

Dans le cas du portage de l’exemple Clipboard vers C++/WinRT à partir de C#, nous avons pu utiliser un balisage XAML (ressources comprises) et des fichiers de ressources identiques dans l’ensemble du projet C# et C++/WinRT. Dans certains cas, des modifications du balisage sont nécessaires. Consultez Copier le XAML et les styles nécessaires pour terminer le portage de MainPage.

Modifications qui impliquent des procédures dans le langage

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

Construction d’élément d’interface utilisateur

Ces exemples de code illustrent 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 = (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()

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 disposez d’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 certains types. Vous devez ajouter des surcharges pour tous les types supplémentaires que vous souhaitez convertir en chaîne.

Si vous souhaitez convertir une valeur enum en chaîne, vous devez 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 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 effectuent la conversion winrt::to_hstring de la propriété liée. Pour le deuxième exemple (StatusEnum), vous devez fournir votre propre surcharge de winrt::to_hstring. Dans le cas contraire, vous recevrez une erreur relative au compilateur.

Consultez également Portage de la méthode Footer_Click.

Génération de chaîne

Pour la génération de chaînes, C# possède 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 tiré 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 CoreDispatcher.RunAsync, comme ceci.

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

Il est bien plus simple d’exprimer cela en C++/WinRT. Notez que nous acceptons les paramètres par valeur en supposant que nous allons vouloir y accéder après le premier point de suspension (co_await, dans le cas présent). Pour plus d’informations, consultez Passage de paramètres.

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

Si vous devez effectuer le travail à une priorité différente de celle par défaut, consultez la fonction winrt::resume_foreground, qui a une surcharge qui est prioritaire. Pour obtenir des exemples de code montrant comment attendre un appel à winrt::resume_foreground, consultez Programmation en tenant compte de l’affinité des threads.

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

Définir vos classes runtime dans IDL

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

Inclure les fichiers d’en-tête de l’espace de noms Windows C++/WinRT nécessaires

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

Boxing et unboxing

C# effectue automatiquement une conversion boxing des scalaires en objets. C++/WinRT vous oblige à appeler la fonction winrt::box_value de manière explicite. Les deux langages nécessitent un unboxing explicite. Consultez Conversions boxing et unboxing avec C++/WinRT.

Dans les tableaux suivants, nous allons utiliser ces définitions.

C++/CX et C# génèrent des exceptions si vous essayez d’effectuer une conversion unboxing d’un pointeur null en un type de valeur. C++/WinRT considère qu’il s’agit d’une erreur de programmation, ce qui provoque un blocage. Dans C++/WinRT, utilisez la fonction winrt::unbox_value_or si vous souhaitez prendre en charge le cas avec l’objet qui 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.

Conversions boxing et unboxing d’une chaîne

Une chaîne est parfois un type de valeur et parfois un type de référence. C# et C++/WinRT traitent les chaînes différemment.

Le type ABI HSTRING est un pointeur vers une chaîne avec décompte des références. Toutefois, il ne dérive pas à partir de IInspectable. Techniquement, il ne s’agit donc pas d’un objet. En outre, un pointeur HSTRING null représente la chaîne vide. La conversion boxing d’éléments non dérivés à partir de IInspectable est effectuée en les encapsulant dans une interface IReference<T>. De plus, Windows Runtime fournit une implémentation standard sous la forme de l’objet PropertyValue (les types personnalisés sont signalés sous la forme PropertyType::OtherType).

C# représente une chaîne Windows Runtime sous la forme d’un type de référence, tandis que C++/WinRT projette une chaîne sous la forme d’un type de valeur. Cela signifie qu’une chaîne null convertie par boxing peut avoir des représentations différentes selon la façon dont vous l’avez obtenue.

Boxing et unboxing de base.

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 Objet de liaison déclaré à l’aide de {Binding}.

Utilisation d’objets à partir du balisage XAML

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

En outre, une liaison à un booléen affiche true ou false dans C#, mais affichera Windows.Foundation.IReference`1<Boolean> dans C++/WinRT.

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

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

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

Vous pouvez créer votre fichier Midl (.idl) de cette façon (consultez Factorisation des classes runtime dans des fichiers 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; };
    }
}

Ensuite, vous l’implémentez comme suit.

// 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 (version antérieure à C++/WinRT 2.0.190530.8)

La liaison de données XAML exige 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 uniquement (ne répond pas aux modifications)
• IVector<IInspectable>
• IBindableIterable (effectue une itération et enregistre les éléments dans une collection privée)

Une interface générique comme IVector<T> ne peut pas être détectée au moment de l’exécution. Chaque IVector<T> a une fonction T qui correspond à un identificateur d’interface (IID) différent. Les développeurs peuvent développer l’ensemble de fonctions T de manière arbitraire. Le code de liaison XAML ne peut donc jamais connaître l’ensemble complet à interroger. Cette restriction n’est pas un problème pour C#, car chaque objet CLR implémentant IEnumerable<T> implémente automatiquement IEnumerable. Au niveau de l’ABI, cela signifie que chaque objet implémentant IObservableVector<T> implémente automatiquement IObservableVector<IInspectable>.

C++/WinRT ne propose pas cette garantie. Si une classe runtime C++/WinRT implémente IObservableVector<T>, nous ne pouvons pas partir du principe qu’une implémentation IObservableVector<IInspectable> est également fournie.

Par conséquent, voici à quoi doit ressembler l’exemple précédent.

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

Quant à 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 appliquer en retour une méthode QI à 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

La classe de base doit être composable pour être dérivée à partir d’une classe runtime. C# ne nécessite pas de procédure spéciale pour que vos classes soient composables, contrairement à C++/WinRT. Vous utilisez le mot clé unsealed pour indiquer que vous souhaitez que votre classe soit utilisable comme classe de base.

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

Dans le fichier d’en-tête de votre type d’implémentation, vous devez ajouter le fichier d’en-tête de la classe de base avant d’inclure l’en-tête généré automatiquement pour la classe dérivée. Dans le cas contraire, vous obtiendrez des erreurs telles que « Utilisation non conforme de ce type comme 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

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