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 UWP-appexemplen (Universal Windows Platform) finns i det tillhörande avsnittet Porting the Clipboard sample to C++/WinRT from C#. Du kan få portningspraxis och erfarenhet genom att följa med i den genomgången och portera exemplet själv samtidigt.

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

Fallstudien Att portera Urklippsexemplet till C++/WinRT från 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.

• Portera 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>. I C# beräknas även vissa Windows Runtime-åtgärder som praktiska C#-språkfunktioner. 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).
• portspråksyntax. 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 (::).
• portspråksprocedur. 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 omfattar 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 hanteras implicit av C#, i bakgrunden. Dessa detaljer utförs explicit i C++/WinRT. Ett exempel är att du använder en .idl-fil för att definiera dina körningstidklasser.

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 en händelsehanterardelegat enligt beskrivningen i Hantera händelser med hjälp av ombud i C++/WinRT. Se även Portering av EnableClipboardContentChangedNotifications-metoden.

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 Portera 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 utlöses av OpenButton.

I C++/WinRT måste din OpenButton_Click-metod vara offentlig i din -implementeringstypom du vill registrera den i XAML-. 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::Windows::UI::Xaml::RoutedEventArgs const& args);
    }
};

Du kan också göra registreringen av XAML-sidan till en vän av din implementeringstyp och OpenButton_Click privat.

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

Ett sista scenario är när C#-projektet som du porterar binder till händelsehanteraren från markup (för mer bakgrund om det scenariot, se Funktioner i 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 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, Windows.UI.Xaml.RoutedEventArgs e);

Ändringar som omfattar språksyntaxen

Portningsklasser 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 illustrerar hur du fattar dessa beslut 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 Porting the IsClipboardContentChangedEnabled property.

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

Ett statiskt C#-fält blir en statisk C++ / WinRT-åtkomstfunktion och/eller mutatorfunktion. Mer information och ett exempel finns i Porting the constructor, Currentoch 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 man bestämmer finns i IDL för MainPage typ.

Porta XAML markup-kod och resursfiler

När det gäller att överföra Urklippsexemplet från C# till C++/WinRTkunde vi använda samma XAML-markup (inklusive resurser) och resursfiler i både 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 portningen 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 = (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()

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 överlagringar för alla ytterligare typer som du vill konvertera till strängar.

När det gäller att strängifiera en enum måste du ange implementeringen 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ängifieringar konsumeras ofta implicit av 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 utföra winrt::to_hstring för den bundna egenskapen. När det gäller det andra exemplet (StatusEnum) måste du ange en egen överlagring av winrt::to_hstring, annars får du ett kompilatorfel.

Se även Porting the Footer_Click method.

Strängkonstruering

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

Se även Portera BuildClipboardFormatsOutputString-metodenoch Portera DisplayChangedFormats-metoden.

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 CoreDispatcher.RunAsync, så här.

private async void Watcher_Added(DeviceWatcher sender, DeviceInformation args)
{
    await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
    {
        // 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_await, i det här fallet). Mer information finns i parameteröverföring.

winrt::fire_and_forget Watcher_Added(DeviceWatcher sender, winrt::DeviceInformation args)
{
    co_await Dispatcher();
    // 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_foregroundfinns 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 typoch Konsolidera dina .idl-filer.

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

När du vill använda en typ från en Windows-namnrymd i C++/WinRT måste du inkludera motsvarande C++/WinRT Windows-namnområdeshuvudfil. Ett exempel finns i Porting the NotifyUser method.

Boxning och avboxning

C# omvandlar automatiskt skalärtyper 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# genererar undantag om du försöker ta bort 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 det fall där objektet inte är av den typ som du trodde att det var.

Ett exempel finns i Porting the OnNavigatedTo method, and Porting the Footer_Click method.

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 sett ett objekt. Dessutom representerar en null-HSTRING- den tomma strängen. Inkapsling av objekt som inte härrör från IInspectable utförs genom att omsluta dem i ett IReference<T>. 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 en 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} för databindning till din datatyp kan du läsa Bindningsobjekt som deklarerats med {Binding}.

Konsumera objekt från XAML-markup

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

Bindning till ett booleskt värde visar också true eller false i C#, men det visar Windows.Foundation.IReference`1<Boolean> i C++/WinRT.

För mer information och kodexempel, se Konsumera 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 Porting the Scenarios property.

Du kan skapa Midl-fil (.idl) så här (se även Factoring-körningsklasser i Midl-filer (.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; };
    }
}

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, koppla till en C++/WinRT-samlingoch 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 vid körning. Varje IVector<T> har en annan gränssnittsidentifierare (IID), som är en funktion av T. Alla utvecklare kan utöka uppsättningen med 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 automatiskt IEnumerable. På ABI-nivå innebär det att varje objekt som implementerar IObservableVector<T> implementerar automatiskt 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_bookSkusmåste du anropa QI för att konvertera dem tillbaka till 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;
}

Härledda klasser

För att kunna härledas från en körningsklass 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 nyckelordet oförseglat för att ange att du vill att klassen ska kunna användas som basklass.

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

I huvudfilen för din implementeringstypmåste du inkludera huvudfilen för basklassen innan du inkluderar 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-namespace

Relaterade ämnen

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