Verplaatsen naar C++/WinRT van C#

Dit onderwerp biedt een uitgebreid overzicht van de technische details die komen kijken bij het overzetten van de broncode van een C#-project naar de equivalente code in C++/WinRT.

Voor een casestudy van het overzetten van een van de Universal Windows Platform (UWP) app-voorbeelden raadpleegt u het bijbehorende onderwerp Het Klembord-voorbeeld overzetten naar C++/WinRT van C#. U kunt oefenen met het overzetten en ervaring opdoen door die stapsgewijze handleiding te volgen en onderweg zelf het voorbeeld over te zetten.

Voorbereiden en wat u kunt verwachten

De casestudy Het Clipboard-voorbeeld overzetten van C# naar C++/WinRT illustreert welke ontwerpkeuzes voor software u moet maken bij het overzetten van een project naar C++/WinRT. Het is dus een goed idee om u voor te bereiden op porting door een goed inzicht te krijgen in de werking van de bestaande code. Op die manier krijgt u een goed overzicht van de functionaliteit van de app en de structuur van de code, en zorgen de beslissingen die u vervolgens neemt er altijd voor dat u vooruitgaat en de juiste richting op gaat.

In termen van wat voor soort overdrachtswijzigingen u kunt verwachten, kunt u deze groeperen in vier categorieën.

• De taalprojectie overzetten. De Windows Runtime (WinRT) wordt in verschillende programmeertalen geprojecteerd. Elk van deze taalprojecties is ontworpen om idiomatisch te voelen voor de betreffende programmeertaal. Voor C# worden sommige Windows Runtime typen geprojecteerd als .NET typen. U vertaalt bijvoorbeeld System.Collections.Generic.IReadOnlyList<T> terug naar Windows. Foundation.Collections.IVectorView<T>. Ook in C# worden sommige Windows Runtime bewerkingen geprojecteerd als handige C#-taalfuncties. Een voorbeeld is dat u in C# de syntaxis van de += operator gebruikt om een gemachtigde voor gebeurtenisafhandeling te registreren. U vertaalt dus taalfuncties zoals die terug naar de fundamentele bewerking die wordt uitgevoerd (gebeurtenisregistratie in dit voorbeeld).
• Syntaxis van poorttaal. Veel van deze wijzigingen zijn eenvoudige mechanische transformaties, waarbij het ene symbool voor het andere wordt vervangen. Bijvoorbeeld: een punt (.) veranderen in een dubbele punt (::).
• Taalprocedure voor de poort. Sommige hiervan kunnen eenvoudige, herhaalde wijzigingen zijn (zoals myObject.MyProperty naar myObject.MyProperty()). Anderen hebben diepere wijzigingen nodig (bijvoorbeeld het overzetten van een procedure waarbij System.Text.StringBuilder wordt gebruikt voor een procedure waarbij std::wostringstream wordt gebruikt).
• Overdrachtsgerelateerde taken die specifiek zijn voor C++/WinRT. Bepaalde details van de Windows Runtime worden impliciet verzorgd door C#, achter de schermen. Deze details worden expliciet uitgevoerd in C++/WinRT. Een voorbeeld is dat u een .idl bestand gebruikt om uw runtimeklassen te definiëren.

Na de op taken gebaseerde index die volgt, zijn de rest van de secties in dit onderwerp gestructureerd volgens de bovenstaande taxonomie.

Inhoud zoeken op basis van de taak die u uitvoert

Wijzigingen die betrekking hebben op de taalprojectie

Een gebeurtenis-handler registreren/intrekken

In C++/WinRT hebt u verschillende syntactische opties voor het registreren/intrekken van een gemachtigde voor een gebeurtenis-handler, zoals beschreven in Handle events by using delegates in C++/WinRT. Zie ook de methode EnableClipboardContentChangedNotifications overzetten.

Soms wilt u bijvoorbeeld, wanneer een gebeurtenisontvanger (een object dat een gebeurtenis afhandelt) op het punt staat te worden vernietigd, een gebeurtenisafhandelaar verwijderen zodat de gebeurtenisbron (het object dat de gebeurtenis activeert) geen vernietigd object meer aanroept. Zie Een geregistreerde gemachtigde intrekken. In dergelijke gevallen maakt u voor uw gebeurtenisverwerkers een lidvariabele event_token aan. Zie voor een voorbeeld De methode EnableClipboardContentChangedNotifications overzetten.

U kunt ook een gebeurtenis-handler registreren in XAML-markeringen.

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

In C# kan uw OpenButton_Click methode privé zijn en kan XAML deze nog steeds verbinden met de ButtonBase.Click-gebeurtenis die door OpenButton wordt gegenereerd.

In C++/WinRT moet uw OpenButton_Click methode openbaar zijn in uw implementatietypeals u deze wilt registreren in XAML-markeringen. Als u een gebeurtenis-handler alleen registreert in imperatieve code, hoeft de gebeurtenis-handler niet openbaar te zijn.

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

U kunt ook de registrerende XAML-pagina een vriend van uw implementatietype maken en OpenButton_Click 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);
    }
};

Een laatste scenario is dat het C#-project dat u overzet bindt aan de eventhandler in de markup (meer achtergrond over dat scenario vindt u in Functions in x:Bind).

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

U kunt die markering gewoon wijzigen in de eenvoudigere Click="OpenButton_Click". Of, als u wilt, kunt u die markeringen behouden zoals het is. Het enige wat u hoeft te doen om dit te ondersteunen, is de gebeurtenisafhandelaar in IDL declareren.

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

Wijzigingen die betrekking hebben op de taalsyntaxis

Klassen en leden overzetten

U moet voor elk C#-type bepalen of u het wilt overzetten naar een Windows Runtime type of naar een reguliere C++-klasse/struct/opsomming. Zie Het Klembord-voorbeeld overzetten naar C++/WinRT van C# voor meer informatie en gedetailleerde voorbeelden die illustreren hoe u deze beslissingen kunt nemen.

Een C#-eigenschap wordt doorgaans omgezet in een accessorfunctie, een mutatorfunctie en een onderliggend gegevenslid. Zie De eigenschap IsClipboardContentChangedEnabled overzetten voor meer informatie en een voorbeeld.

Voor niet-statische velden moet u gegevensleden van uw implementatietype maken.

Een statisch C#-veld wordt een statische C++/WinRT-toegangsfunctie en/of mutatorfunctie. Zie De constructor, Current en FEATURE_NAME overzetten voor meer informatie, en een voorbeeld.

Voor lidfuncties moet u voor elke functie beslissen of deze deel uitmaakt van de IDL, of het een openbare of persoonlijke lidfunctie van uw implementatietype is. Zie IDL voor het type MainPage voor meer informatie en voorbeelden van hoe u kunt beslissen.

Het overzetten van XAML-opmaak en assetbestanden

In het geval van het overzetten van het Klembord-voorbeeld naar C++/WinRT vanuit C#, konden we dezelfde XAML-markeringen (inclusief resources) en assetbestanden in de C# en het C++/WinRT-project gebruiken. In sommige gevallen zijn bewerkingen voor markeringen nodig om dat te bereiken. Zie Kopiëren van de XAML en stijlen die nodig zijn om de overdracht van MainPage te voltooien.

Wijzigingen die betrekking hebben op procedures in de taal

In de volgende secties wordt dieper ingegaan op een aantal items in de tabel.

Opbouw van UI-elementen

Deze codevoorbeelden tonen de constructie van een UI-element in de imperatieve code van een XAML-pagina.

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()

C#-typen bieden de methode Object.ToString .

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

C++/WinRT biedt deze faciliteit niet rechtstreeks, maar u kunt ook alternatieven gebruiken.

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

C++/WinRT ondersteunt ook winrt::to_hstring voor een beperkt aantal typen. U moet overbelastingen toevoegen voor eventuele extra typen die u wilt stringifyen.

Als u een enum naar een tekenreeks converteert, moet u de implementatie van winrt::to_hstring aanleveren.

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

Deze tekenreeksrepresentaties worden vaak impliciet verwerkt door gegevensbinding.

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

Met deze bindingen wordt winrt::to_hstring van de afhankelijke eigenschap uitgevoerd. In het tweede voorbeeld ( statusenum) moet u uw eigen overbelasting van winrt::to_hstring opgeven, anders krijgt u een compilerfout.

Zie ook De methode Footer_Click porteren.

Tekenreeks bouwen

Voor het samenstellen van tekenreeksen heeft C# een ingebouwd StringBuilder-type.

Zie ook de methode BuildClipboardFormatsOutputString overzetten en de methode DisplayChangedFormats overzetten.

Code uitvoeren op de hoofd-UI-thread

Dit voorbeeld wordt genomen uit het voorbeeld van de streepjescodescanner.

Als u wilt werken aan de hoofd-UI-thread in een C#-project, gebruikt u doorgaans de methode DispatcherQueue.TryEnqueue (of de oudere CoreDispatcher.RunAsync in UWP). Het patroon ziet er als volgt uit in C#.

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

Het is veel eenvoudiger om dat in C++/WinRT uit te drukken. Merk op dat we parameters op basis van waarde doorgeven, ervan uitgaande dat we er na het eerste onderbrekingspunt toegang toe willen hebben (de co_await, in dit geval). Zie Parameter-passing voor meer informatie.

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

Als u het werk met een andere prioriteit dan de standaardprioriteit moet uitvoeren, raadpleegt u de functie winrt::resume_foreground, die een overload heeft die een prioriteit accepteert. Zie Programmeren met threadaffiniteit in gedachten voor codevoorbeelden die laten zien hoe u wacht op een aanroep naar winrt::resume_foreground.

Taken met betrekking tot het overzetten die specifiek zijn voor C++/WinRT

Runtimeklassen definiëren in IDL

Zie IDL voor het type MainPage en voeg uw .idl bestanden samen.

Neem de C++/WinRT-Windows naamruimteheaderbestanden op die u nodig hebt

Wanneer u in C++/WinRT een type uit een Windows naamruimten wilt gebruiken, moet u het bijbehorende C++/WinRT-Windows naamruimteheaderbestand opnemen. Zie De methode NotifyUser overzetten voor een voorbeeld.

Verpakken en uitpakken

C# vakken automatisch scalaire waarden in objecten. C++/WinRT vereist dat u de winrt::box_value-functie expliciet aanroept. Voor beide talen moet u het selectievakje expliciet uitvinken. Zie Boksen en uitpakken met C++/WinRT.

In de volgende tabellen gebruiken we deze definities.

C++/CX en C# werpen een uitzondering op als u probeert een null-pointer te unboxen naar een waardetype. C++/WinRT beschouwt deze als een programmeerfout en loopt vast. Gebruik in C++/WinRT de functie winrt::unbox_value_or als u de case wilt afhandelen waarin het object niet van het type is dat u dacht dat het was.

Zie voor een voorbeeld de methode OnNavigatedTo overzetten en de methode Footer_Click overzetten.

Boxing en unboxing van een tekenreeks

Een tekenreeks is in sommige opzichten een waardetype en in andere opzichten een referentietype. C# en C++/WinRT behandelen tekenreeksen anders.

Het ABI-type HSTRING is een aanwijzer naar een tekenreeks die wordt geteld. Maar het is niet afgeleid van IInspectable, dus het is technisch geen object. Bovendien vertegenwoordigt een null-HSTRING de lege tekenreeks. Boksen van dingen die niet zijn afgeleid van IInspectable wordt uitgevoerd door ze in een IReference<T> te verpakken en de Windows Runtime biedt een standaard implementatie in de vorm van het PropertyValue-object (aangepaste typen worden gerapporteerd als PropertyType::OtherType).

C# vertegenwoordigt een Windows Runtime tekenreeks als referentietype; terwijl C++/WinRT een tekenreeks projecteert als een waardetype. Dit betekent dat een in een vak geplaatste null-tekenreeks verschillende weergaven kan hebben, afhankelijk van hoe u daar bent gekomen.

Basisprincipes van boxing en unboxing.

Een klasse beschikbaar maken voor de markeringsextensie {Binding}

Als u de markeringsextensie {Binding} wilt gebruiken om gegevens te binden aan uw gegevenstype, raadpleegt u Bindingsobject dat is gedeclareerd met {Binding}.

Objecten uit XAML-opmaak gebruiken

In een C#-project kunt u privéleden en benoemde elementen uit XAML-markeringen gebruiken. Maar in C++/WinRT moeten alle entiteiten die worden gebruikt met behulp van de XAML -markeringsextensie {x:Bind} openbaar worden weergegeven in IDL.

Ook wordt bij binding aan een Booleaanse waarde in C# true of false weergegeven, maar in C++/WinRT wordt Windows.Foundation.IReference`1<Boolean> weergegeven.

Zie Objecten in markup gebruiken voor meer informatie en codevoorbeelden.

Een gegevensbron beschikbaar maken voor XAML-markeringen

In C++/WinRT versie 2.0.190530.8 of hoger maakt winrt::single_threaded_observable_vector een waarneembare vector die zowel IObservableVectorT< als IObservableVector ><IInspectable> ondersteunt. Zie De eigenschap Scenario's overzetten voor een voorbeeld.

U kunt uw Midl-bestand (.idl) als volgt opstellen (zie ook Runtime-klassen onderbrengen in Midl-bestanden (.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; };
    }
}

En implementeer zo.

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

Zie besturingselementen voor XAML-items voor meer informatie; bind aan een C++/WinRT-verzameling en verzamelingen met C++/WinRT.

Een gegevensbron beschikbaar maken voor XAML-opmaak (vóór C++/WinRT 2.0.190530.8)

XAML-gegevensbinding vereist dat een itemsbron IIterable<IInspectable> implementeert, evenals een van de volgende combinaties van interfaces.

• IObservableVector<IInspectable>
• IBindableVector en INotifyCollectionChanged
• IBindableVector en IBindableObservableVector
• IBindableVector zelf (reageert niet op wijzigingen)
• IVector<IInspectable>
• IBindableIterable (zal over elementen itereren en deze opslaan in een privécollectie)

Een algemene interface, zoals IVector<T> , kan tijdens runtime niet worden gedetecteerd. Elke IVector<T> heeft een andere interface-id (IID), een functie van T. Elke ontwikkelaar kan de set T willekeurig uitbreiden, zodat de XAML-bindingscode nooit de volledige set kan kennen waarvoor een query moet worden uitgevoerd. Deze beperking is geen probleem voor C# omdat elk CLR-object dat IEnumerable<T implementeert, IEnumerable T> automatisch IEnumerable implementeert. Op ABI-niveau betekent dit dat elk object dat IObservableVector T< implementeert, automatisch IObservableVector><IInspectable> implementeert.

C++/WinRT biedt geen garantie. Als een C++/WinRT-runtimeklasse IObservableVector<T> implementeert, kunnen we er niet van uitgaan dat een implementatie van IObservableVector<IInspectable> ook is opgegeven.

Daarom moet het vorige voorbeeld er als volgt uitzien.

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

En de implementatie.

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

Als u toegang wilt krijgen tot objecten in m_bookSkus, moet u ze weer terugzetten naar 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;
}

Afgeleide klassen

Om van een runtime-klasse te kunnen overerven, moet de basisklasse samenstelbaar zijn. C# vereist niet dat u speciale stappen uitvoert om uw klassen composable te maken, maar C++/WinRT wel. U gebruikt het niet-verzegelde trefwoord om aan te geven dat uw klasse bruikbaar moet zijn als basisklasse.

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

In het headerbestand voor uw implementatietype moet u het headerbestand van de basisklasse opnemen voordat u de automatisch gegenereerde header voor de afgeleide klasse opneemt. Anders krijgt u fouten zoals 'Ongeldig gebruik van dit type als een expressie'.

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

Belangrijke API's

• winrt-naamruimte

Verwante onderwerpen

• C#-handleidingen
• C++/WinRT
• Uitgebreide gegevensbinding