Flytta till C++/WinRT från C#

Det här avsnittet innehåller en omfattande katalog över den tekniska information som ingår i porteringen av källkoden i ett C#- projekt till dess motsvarighet i C++/WinRT.

En fallstudie om att portera ett av de Universal Windows Platform (UWP) appexemplen finns i det tillhörande ämnet Porting the Clipboard sample to C++/WinRT from C#. Du kan öva på portering och skaffa dig erfarenhet genom att följa den genomgången och själv portera exemplet under tiden.

Så här förbereder du dig och vad du kan förvänta dig

Fallstudien Porting the Clipboard sample to C++/WinRT from C# illustrerar exempel på de typer av beslut om programvarudesign som du ska fatta när du porterar ett projekt till C++/WinRT. Därför är det en bra idé att förbereda för portning genom att få en gedigen förståelse för hur den befintliga koden fungerar. På så sätt får du en bra översikt över appens funktioner och kodens struktur, och sedan kommer de beslut du fattar alltid att föra dig framåt och i rätt riktning.

När det gäller vilka typer av portningsändringar som kan förväntas kan du gruppera dem i fyra kategorier.

• Porta språkprojektionen. Windows Runtime (WinRT) projiceras till olika programmeringsspråk. Var och en av dessa språkprojektioner är utformad för att känna sig idiomatisk för programmeringsspråket i fråga. För C# beräknas vissa Windows Runtime typer som .NET typer. Du kommer till exempel att översätta System.Collections.Generic.IReadOnlyList<T> tillbaka till Windows. Foundation.Collections.IVectorView<T>. Även i C# återges vissa Windows Runtime-operationer som praktiska språkfunktioner i C#. Ett exempel är att du i C# använder operatorsyntaxen += för att registrera ett ombud för händelsehantering. Så du kommer att översätta språkfunktioner som den tillbaka till den grundläggande åtgärd som utförs (händelseregistrering, i det här exemplet).
• Syntax för portspråk. Många av dessa ändringar är enkla mekaniska transformeringar som ersätter en symbol för en annan. Du kan till exempel ändra punkt (.) till dubbelkolon (::).
• Procedur för portspråk. Vissa av dessa kan vara enkla, repetitiva ändringar (till exempel myObject.MyProperty till myObject.MyProperty()). Andra behöver djupare ändringar (till exempel portning av en procedur som innebär användning av System.Text.StringBuilder till en som innebär användning av std::wostringstream).
• Portningsrelaterade uppgifter som är specifika för C++/WinRT. Vissa detaljer om Windows Runtime tas hand om implicit av C#, i bakgrunden. De detaljerna hanteras uttryckligen i C++/WinRT. Ett exempel är att du använder en .idl-fil för att definiera dina runtime-klasser.

Efter det aktivitetsbaserade indexet som följer struktureras resten av avsnitten i det här avsnittet enligt taxonomi ovan.

Hitta innehåll baserat på den uppgift du utför

Ändringar som omfattar språkprojektionen

Registrera/återkalla en händelsehanterare

I C++/WinRT har du flera syntaktiska alternativ för att registrera/återkalla ett händelsehanterardelegat enligt beskrivningen i Hantera händelser med hjälp av ombud i C++/WinRT. Se även Portning av metoden EnableClipboardContentChangedNotifications.

Ibland, till exempel när en händelsemottagare (ett objekt som hanterar en händelse) håller på att förstöras, vill du återkalla en händelsehanterare så att händelsekällan (objektet som lyfter händelsen) inte anropar till ett förstört objekt. Se Återkalla ett registrerat ombud. I så fall skapar du en event_token medlemsvariabel för dina händelsehanterare. Ett exempel finns i portningen av metoden EnableClipboardContentChangedNotifications.

Du kan också registrera en händelsehanterare i XAML-markering.

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

I C# kan din OpenButton_Click-metod vara privat, och XAML kan fortfarande ansluta den till ButtonBase.Click-händelsen som skapats av OpenButton.

I C++/WinRT måste din OpenButton_Click-metod vara offentlig i din implementeringstypom du vill registrera den i XAML-markering. Om du registrerar en händelsehanterare endast i imperativ kod behöver händelsehanteraren inte vara offentlig.

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

Du kan också göra XAML-sidan som utför registreringen till vän med din implementeringstyp och göra OpenButton_Click privat.

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

Ett sista scenario är när C#-projektet som du porterar binder till händelsehanteraren i uppmärkningen (mer information om det scenariot finns i Functions in x:Bind).

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

Du kan bara ändra den markeringen till den enklare Click="OpenButton_Click". Eller, om du föredrar det, kan du behålla den markeringen som den är. Allt du behöver göra för att stödja det är att deklarera händelsehanteraren i IDL.

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

Ändringar som omfattar språksyntaxen

Portering av klasser och medlemmar

För varje C#-typ måste du bestämma om du vill portera den till en Windows Runtime typ eller till en vanlig C++-klass/struct/uppräkning. Mer information och detaljerade exempel som visar hur dessa beslut kan fattas finns i Porting the Clipboard sample to C++/WinRT from C#.

En C#-egenskap blir vanligtvis en accessorfunktion, en mutatorfunktion och en stöddatamedlem. Mer information och ett exempel finns i Migrera egenskapen IsClipboardContentChangedEnabled.

För icke-statiska fält gör du dem till datamedlemmar av din implementeringstyp.

Ett statiskt fält i C# blir en statisk åtkomst- och/eller mutatorfunktion i C++/WinRT. Mer information och ett exempel finns i Portering av konstruktorn, Current och FEATURE_NAME.

För medlemsfunktioner måste du återigen bestämma för var och en om den tillhör IDL eller inte, eller om det är en offentlig eller privat medlemsfunktion av din implementeringstyp. Mer information och exempel på hur du bestämmer finns i IDL för MainPage-typen.

Portera XAML-kod och resursfiler

När det gäller att portera Urklippsexemplet till C++/WinRT från C#, kunde vi använda samma XAML-markering (inklusive resurser) och tillgångsfiler i C# och C++/WinRT-projektet. I vissa fall är redigeringar av markering nödvändiga för att uppnå detta. Se Kopiera XAML och de format som krävs för att slutföra porteringen av MainPage.

Ändringar som omfattar procedurer på språket

Följande avsnitt går in närmare på några av objekten i tabellen.

UI-elementkonstruktion

Dessa kodexempel visar konstruktionen av ett gränssnittselement i den imperativa koden på en XAML-sida.

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#-typerna innehåller metoden Object.ToString .

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

C++/WinRT tillhandahåller inte den här funktionen direkt, men du kan vända dig till alternativ.

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

C++/WinRT stöder också winrt::to_hstring för ett begränsat antal typer. Du måste lägga till överlagrade funktioner för alla de ytterligare typer som du vill konvertera till sträng.

Om du vill konvertera en enum till en sträng måste du tillhandahålla en implementering av 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));
        }
    }
}

Dessa strängrepresentationer används ofta implicit vid databindning.

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

Dessa bindningar kommer att använda winrt::to_hstring på den bundna egenskapen. När det gäller det andra exemplet ( StatusEnum) måste du ange din egen överbelastning av winrt::to_hstring, annars får du ett kompilatorfel.

Se även Portering av metoden Footer_Click.

Strängbygge

För strängbyggnad har C# en inbyggd StringBuilder-typ .

Se även Portering av metoden BuildClipboardFormatsOutputString och portering av metoden DisplayChangedFormats.

Köra kod i huvudgränssnittstråden

Det här exemplet är hämtat från streckkodsskannerexemplet.

När du vill arbeta med huvudgränssnittstråden i ett C#-projekt använder du vanligtvis metoden DispatcherQueue.TryEnqueue (eller den äldre CoreDispatcher.RunAsync i UWP). Så här ser mönstret ut i C#.

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

Det är mycket enklare att uttrycka det i C++/WinRT. Observera att vi accepterar parametrar efter värde enligt antagandet att vi vill komma åt dem efter den första avstängningspunkten ( co_awaiti det här fallet). Mer information finns i Parameter-passing.

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

Om du behöver utföra arbetet med en annan prioritet än standard kan du se funktionen winrt::resume_foreground , som har en överbelastning som prioriteras. Kodexempel som visar hur du väntar på ett anrop till winrt::resume_foreground finns i Programmering med trådtillhörighet i åtanke.

Portningsrelaterade uppgifter som är specifika för C++/WinRT

Definiera dina körningsklasser i IDL

Se IDL för MainPage-typen och Konsolidera dina .idl filer.

Inkludera de C++/WinRT-Windows namnområdeshuvudfiler som du behöver

När du vill använda en typ från en Windows namnområden i C++/WinRT måste du inkludera motsvarande C++/WinRT-Windows namnområdeshuvudfil. Ett exempel finns i Portering av metoden NotifyUser.

Boxning och avboxning

C# boxar automatiskt skalärer till objekt. C++/WinRT kräver att du anropar funktionen winrt::box_value explicit. Båda språken kräver att du packar upp explicit. Se Boxning och avboxning med C++/WinRT.

I tabellerna som följer använder vi dessa definitioner.

C++/CX och C# utlöser undantag om du försöker avboxa en null-pekare till en värdetyp. C++/WinRT anser att detta är ett programmeringsfel och kraschar. I C++/WinRT använder du funktionen winrt::unbox_value_or om du vill hantera fallet där objektet inte är av den typ som du trodde att det var.

Ett exempel finns i Portera metoden OnNavigatedTo och Portera metoden Footer_Click.

Boxning och avboxning av en sträng

En sträng är på sätt och vis en värdetyp och på andra sätt en referenstyp. C# och C++/WinRT behandlar strängar på olika sätt.

ABI-typen HSTRING är en pekare till en referensberäkningssträng. Men det härleds inte från IInspectable, så det är inte tekniskt ett objekt. Dessutom representerar en null HSTRING den tomma strängen. Boxning av saker som inte härleds från IInspectable görs genom att omsluta dem i en IReference<T>, och Windows Runtime tillhandahåller en standardimplementering i form av PropertyValue-objektet (anpassade typer rapporteras som PropertyType::OtherType).

C# representerar en Windows Runtime sträng som referenstyp, medan C++/WinRT projicerar en sträng som en värdetyp. Det innebär att en rutad null-sträng kan ha olika representationer beroende på hur du kom dit.

Grundläggande boxning och avboxning.

Göra en klass tillgänglig för {Binding}-markeringstillägget

Om du tänker använda markeringstillägget {Binding} till databindning till din datatyp kan du läsa Bindningsobjekt som deklarerats med {Binding}.

Använda objekt från XAML-markering

I ett C#-projekt kan du få åtkomst till privata medlemmar och namngivna element från XAML-kod. Men i C++/WinRT måste alla entiteter som används med XAML {x:Bind}-markeringstillägget exponeras offentligt i IDL.

Dessutom visas true eller false i C# vid bindning till ett booleskt värde, men i C++/WinRT visas Windows.Foundation.IReference`1<Boolean>.

Mer information och kodexempel finns i Använda objekt från markup.

Göra en datakälla tillgänglig för XAML-markering

I C++/WinRT version 2.0.190530.8 eller senare skapar winrt::single_threaded_observable_vector en observerbar vektor som stöder både IObservableVector<T> och IObservableVector<IInspectable>. Ett exempel finns i Portering av egenskapen Scenarios.

Du kan skriva midl-filen (.idl) så här (se även Factoring runtime-klasser till Midl-filer (.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; };
    }
}

Och implementera så här.

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

Mer information finns i XAML-objektkontroller, bind till en C++/WinRT-samling och samlingar med C++/WinRT.

Göra en datakälla tillgänglig för XAML-markering (före C++/WinRT 2.0.190530.8)

XAML-databindning kräver att en objektkälla implementerar IIterable<IInspectable>, samt en av följande kombinationer av gränssnitt.

• IObservableVector<IInspectable>
• IBindableVector och INotifyCollectionChanged
• IBindableVector och IBindableObservableVector
• IBindableVector själv (svarar inte på ändringar)
• IVector<IInspectable>
• IBindableIterable (itererar och sparar element i en privat samling)

Ett generiskt gränssnitt som IVector<T> kan inte identifieras under körning. Varje IVector<T> har en annan gränssnittsidentifierare (IID), som är en funktion av T. Alla utvecklare kan utöka uppsättningen T godtyckligt, så det är tydligt att XAML-bindningskoden aldrig kan känna till den fullständiga uppsättningen att fråga efter. Den begränsningen är inte ett problem för C# eftersom varje CLR-objekt som implementerar IEnumerable<T> implementerar IEnumerable automatiskt. På ABI-nivå innebär det att varje objekt som implementerar IObservableVector<T> automatiskt implementerar IObservableVector<IInspectable>.

C++/WinRT erbjuder inte den garantin. Om en C++/WinRT-körningsklass implementerar IObservableVector<T> kan vi inte anta att en implementering av IObservableVector<IInspectable> på något sätt också tillhandahålls.

Därför måste det föregående exemplet se ut så här.

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

Och implementeringen.

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

Om du behöver komma åt objekt i m_bookSkus måste du skicka tillbaka dem till Bokhandel::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;
}

Härledda klasser

För att kunna ärva från en runtimeklass måste basklassen vara komponerbar. C# kräver inte att du vidtar några särskilda åtgärder för att göra dina klasser komposterbara, men det gör C++/WinRT. Du använder det oförseglade nyckelordet för att ange att du vill att din klass ska kunna användas som basklass.

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

I huvudfilen för implementeringstypen måste du inkludera huvudfilen för basklassen innan du tar med den automatiskt genererade rubriken för den härledda klassen. Annars får du fel som "Olaglig användning av den här typen som ett uttryck".

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

Viktiga API:er

• winrt-namnrymd

Relaterade ämnen

• C#-handledningar
• C++/WinRT
• Databindning på djupet