Přechod na C++/WinRT z C#

Toto téma komplexně kataloguje technické podrobnosti týkající se přenosu zdrojového kódu do projektu C# do jeho ekvivalentu v C++/WinRT.

Případovou studii portování jednoho z ukázkových projektů platformy Univerzální platforma Windows (UPW) najdete v doprovodném tématu Portování ukázky Schránka z jazyka C# do C++/WinRT. Praxi a zkušenosti s portováním můžete získat tak, že budete postupovat podle tohoto návodu a v jeho průběhu si sami přeportujete ukázku.

Jak se připravit a co očekávat

Případová studie Přenos ukázky Schránka z jazyka C# do C++/WinRT ilustruje příklady druhů rozhodnutí týkajících se návrhu softwaru, která budete činit při převodu projektu na C++/WinRT. Proto je vhodné se připravit na přenos tím, že získáte solidní znalosti o tom, jak stávající kód funguje. Tak získáte dobrý přehled o funkčnosti aplikace i struktuře kódu a rozhodnutí, která pak učiníte, vás budou vždy posouvat kupředu správným směrem.

Z hlediska toho, jaké druhy změn přenosu se mají očekávat, můžete je seskupit do čtyř kategorií.

• Portujte projekci jazyka. prostředí Windows Runtime (WinRT) se projektuje do různých programovacích jazyků. Každá z těchto jazykových projekcí je navržena tak, aby působila přirozeně pro daný programovací jazyk. U jazyka C# jsou některé typy prostředí Windows Runtime projektovány jako typy .NET. Takže například přeložíte System.Collections.Generic.IReadOnlyList<T> zpět na Windows. Foundation.Collections.IVectorView<T>. V jazyce C# jsou některé operace prostředí Windows Runtime promítnuty jako pohodlné jazykové funkce jazyka C#. Příkladem je, že v jazyce C# použijete syntaxi operátoru += k registraci delegáta zpracování událostí. Budete tedy převádět jazykové konstrukce, jako je tato, na základní operaci, která se provádí (v tomto příkladu registrace události).
• Syntaxe jazyka portu Mnoho z těchto změn je jednoduchých mechanických transformací, nahrazení jednoho symbolu za druhý. Například změna tečky (.) na dvojtečku (::).
• Procedura jazyka portu Některé z nich mohou být jednoduché, opakované změny (například myObject.MyProperty na myObject.MyProperty()). Jiné potřebují hlubší změny (například portování procedury, která zahrnuje použití System.Text.StringBuilder na takový, který zahrnuje použití std::wostringstream).
• Přenos úloh souvisejících s C++/WinRT O některé podrobnosti rozhraní prostředí Windows Runtime se na pozadí automaticky stará jazyk C#. Tyto podrobnosti se provádějí explicitně v jazyce C++/WinRT. Příkladem je použití .idl souboru k definování tříd modulu runtime.

Po následujícím indexu založeném na úlohách jsou zbývající části tohoto tématu strukturovány podle výše uvedené taxonomie.

Vyhledání obsahu na základě úkolu, který provádíte

Změny, které zahrnují projekci jazyka

Zaregistrovat nebo zrušit registraci obslužné rutiny pro událost

V jazyce C++/WinRT máte několik syntaktických možností registrace nebo odvolání delegáta obslužné rutiny události, jak je popsáno v tématu Zpracování událostí pomocí delegátů v C++/WinRT. Viz také Přenos metody EnableClipboardContentChangedNotifications.

Někdy se například stane, že příjemce události (objekt zpracovávající událost) bude zničen, budete chtít odvolat obslužnou rutinu události, aby zdroj události (objekt vyvolávácí událost) nevolal do zničeného objektu. Viz Odvolání registrovaného delegáta. V takových případech vytvořte členskou proměnnou event_token pro vaše obslužné rutiny událostí. Příklad naleznete v části Portování metody EnableClipboardContentChangedNotifications.

Obslužnou rutinu události můžete také zaregistrovat v kódu XAML.

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

V jazyce C# může být vaše metoda OpenButton_Click soukromá a XAML ji stále bude moct připojit k události ButtonBase.Click vyvolanou OpenButtonem.

V jazyce C++/WinRT musí být vaše metoda OpenButton_Click ve vašem typu implementace veřejná, pokud ji chcete zaregistrovat v kódu XAML. Pokud zaregistrujete obslužnou rutinu události pouze v imperativním kódu, obslužná rutina události nemusí být veřejná.

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

Případně můžete stránku XAML, která provádí registraci, prohlásit jako friend vašeho typu implementace a metodu OpenButton_Click jako soukromou.

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

Jedním z konečných scénářů je situace, kdy projekt C#, který portujete, vytvoří vazbu na obslužnou rutinu události z kódu (další pozadí tohoto scénáře najdete v tématu Funkce v x:Bind).

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

Mohli byste jen změnit tento kód na jednodušší Click="OpenButton_Click". Nebo, pokud chcete, můžete toto značení ponechat beze změny. Jediné, co musíte udělat, abyste to podpořili, je deklarovat obsluhu události v IDL.

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

Změny, které zahrnují syntaxi jazyka

Přenos tříd a členů

Pro každý typ jazyka C# budete muset rozhodnout, jestli se má portovat na typ prostředí Windows Runtime, nebo do běžné třídy,struktury/výčtu jazyka C++. Další informace a podrobné příklady, které ukazují, jak tato rozhodnutí učinit, viz Přenos ukázky Clipboard z jazyka C# do C++/WinRT.

Vlastnost jazyka C# se obvykle stává přistupující funkcí, funkcí mutátoru a záložním datovým členem. Další informace a příklad najdete v tématu Přenos vlastnosti IsClipboardContentChangedEnabled.

U nestatického pole je nastavte jako datové členy vašeho typu implementace.

Statické pole jazyka C# se převede na statickou přístupovou a/nebo nastavovací funkci v C++/WinRT. Další informace a příklad naleznete v článku Přenesení konstruktoru, Current a FEATURE_NAME.

U členských funkcí budete muset znovu rozhodnout, jestli patří do IDL, nebo jestli se jedná o veřejnou nebo soukromou členskou funkci vašeho typu implementace. Další informace a příklady, které vám pomohou se rozhodnout, najdete v dokumentaci IDL pro typ MainPage.

Převod značkovacího kódu XAML a souborů prostředků

V případě přenosu ukázky schránky do C++/WinRT z C# jsme mohli použít stejný kód XAML (včetně zdrojů) a souborů prostředků v rámci C# a projektu C++/WinRT. V některých případech budou k dosažení tohoto cíle nezbytné úpravy značkování. Viz Zkopírování XAML a stylů potřebných k dokončení portování MainPage.

Změny, které zahrnují postupy v rámci jazyka

Následující části obsahují podrobnější informace o některých položkách v tabulce.

Konstrukce prvků uživatelského rozhraní

Tyto příklady kódu ukazují vytvoření prvku uživatelského rozhraní v imperativním kódu stránky 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()

Typy jazyka C# poskytují metodu Object.ToString .

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

C++/WinRT přímo neposkytuje toto zařízení, ale můžete se obrátit na alternativy.

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

C++/WinRT také podporuje winrt::to_hstring pro omezený počet typů. Budete muset přidat přetížení pro všechny další typy, které chcete převést na řetězec.

Při převodu výčtu na řetězec budete muset poskytnout implementaci 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));
        }
    }
}

Tyto řetězcové reprezentace jsou často implicitně využívány při datové vazbě.

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

Tyto vazby budou provádět winrt::to_hstring vázané vlastnosti. V případě druhého příkladu ( StatusEnum) musíte zadat vlastní přetížení winrt::to_hstring, jinak se zobrazí chyba kompilátoru.

Podívejte se také na portování metody Footer_Click.

Vytváření řetězců

Pro vytváření řetězců má jazyk C# integrovaný typ StringBuilder .

Viz také Přenos metody BuildClipboardFormatsOutputString a přenos metody DisplayChangedFormats.

Spuštění kódu v hlavním vlákně uživatelského rozhraní

Tento příklad je převzat z vzorku skeneru čárových kódů.

Pokud chcete pracovat na hlavním vlákně uživatelského rozhraní v projektu C#, obvykle používáte metodu DispatcherQueue.TryEnqueue (nebo starší CoreDispatcher.RunAsync v UPW). Takto vypadá vzor v jazyce C#.

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

V jazyce C++/WinRT je mnohem jednodušší to vyjádřit. Všimněte si, že přijímáme parametry podle hodnoty podle předpokladu, že k nim budeme chtít přistupovat po prvním bodu pozastavení ( co_awaitv tomto případě). Další informace najdete v tématu Předávání parametrů.

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

Pokud potřebujete pracovat s jinou prioritou než výchozí, podívejte se na funkci winrt::resume_foreground , která má přetížení, které má prioritu. Příklady kódu, které ukazují, jak čekat na volání winrt::resume_foreground, najdete v článku Programování s ohledem na afinitu vláken.

Úlohy související s portováním specifické pro C++/WinRT

Definování tříd modulu runtime v IDL

Podívejte se na IDL pro typ MainPage a slučte své soubory .idl.

Zahrňte soubory hlaviček oboru názvů C++/WinRT Windows, které potřebujete.

V jazyce C++/WinRT musíte kdykoli, když chcete použít typ z některého jmenného prostoru Windows, zahrnout odpovídající soubor záhlaví jmenného prostoru Windows pro C++/WinRT. Příklad najdete v tématu Přenesení metody NotifyUser.

Boxování a rozbalování

Jazyk C# automaticky rozdělí skaláry do objektů. C++/WinRT vyžaduje, abyste explicitně volali funkci winrt::box_value . Oba jazyky vyžadují explicitní rozbalení. Viz Boxing and unboxing with C++/WinRT.

V následujících tabulkách použijeme tyto definice.

C++/CX a C# vyvolá výjimky, pokud se pokusíte rozbalit ukazatel null na typ hodnoty. C++/WinRT to považuje za programovací chybu a zhroutí se. V jazyce C++/WinRT použijte funkci winrt::unbox_value_or , pokud chcete zpracovat případ, kdy objekt není typu, o kterém jste si mysleli, že se jedná.

Příklad naleznete v části Portování metody OnNavigatedTo a Portování metody Footer_Click.

Boxing a unboxing řetězce

Řetězec je nějakým způsobem typ hodnoty a jiným způsobem typ odkazu. C# a C++/WinRT zachází s řetězci odlišně.

Typ ABI HSTRING je ukazatel na řetězec s počítáním referencí. Ale neodvozuje se od IInspectable, takže to není technicky objekt. Navíc hodnota HSTRING s hodnotou null představuje prázdný řetězec. Zabalení věcí, které nejsou odvozeny z IInspectable je provádí zabalením uvnitř IReference<T> a prostředí Windows Runtime poskytuje standardní implementaci ve formě PropertyValue objektu (vlastní typy jsou hlášeny jako PropertyType::OtherType).

Jazyk C# reprezentuje řetězec prostředí Windows Runtime jako referenční typ, zatímco C++/WinRT reprezentuje řetězec jako hodnotový typ. To znamená, že řetězec s hodnotou null s rámečkem může mít různé reprezentace v závislosti na tom, jak jste se tam dostali.

Základní boxování a rozbalení.

Zpřístupnění třídy rozšíření značek {Binding}

Pokud máte v úmyslu použít rozšíření značek {Binding} k vytvoření vazby dat s vaším datovým typem, podívejte se na objekt vazby deklarovaný pomocí {Binding}.

Využívání objektů z revizí XAML

V projektu jazyka C# můžete využívat soukromé členy a pojmenované elementy z kódu XAML. V jazyce C++/WinRT se ale všechny entity spotřebované pomocí rozšíření značek XAML {x:Bind} musí veřejně zveřejnit v IDL.

Také se při svázání s booleovskou hodnotou v jazyce C# zobrazí true nebo false, ale v jazyce C++/WinRT se zobrazí Windows.Foundation.IReference`1<Boolean>.

Další informace a příklady kódu najdete v tématu Využívání objektů z revizí.

Zpřístupnění zdroje dat pro kód XAML

V jazyce C++/WinRT verze 2.0.190530.8 nebo novější vytváří winrt::single_threaded_observable_vector pozorovatelný vektor, který podporuje jak IObservableVector<T>, tak IObservableVector<IInspectable>. Příklad najdete v tématu Přenos vlastnosti Scenarios.

Soubor MIDL (.idl) můžete vytvořit takto (viz také Rozdělení tříd modulu runtime do souborů 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; };
    }
}

A implementujte takhle.

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

Další informace najdete v tématu Ovládací prvky položek XAML, vazba na kolekci C++/WinRT a kolekce pomocí C++/WinRT.

Zpřístupnění zdroje dat pro kód XAML (před C++/WinRT 2.0.190530.8)

Datová vazba XAML vyžaduje, aby zdroj položek implementuje IIterable<IInspectable>, stejně jako jednu z následujících kombinací rozhraní.

• IObservableVector<IInspectable>
• IBindableVector a INotifyCollectionChanged
• IBindableVector a IBindableObservableVector
• IBindableVector sám (nebude reagovat na změny)
• IVector<IInspectable>
• IBindableIterable (bude iterovat a ukládat prvky do privátní kolekce)

Obecné rozhraní, jako je IVector<T> , nelze rozpoznat za běhu. Každý IVector<T> má jiný identifikátor rozhraní (IID), což je funkce T. Libovolný vývojář může libovolně rozšířit sadu T , takže jasně kód vazby XAML nikdy nezná úplnou sadu pro dotazování. Toto omezení není problém pro jazyk C#, protože každý objekt CLR, který implementuje IEnumerable<T> automaticky implementuje IEnumerable. Na úrovni ABI to znamená, že každý objekt, který implementuje IObservableVector<T> automaticky implementuje IObservableVector<IInspectable>.

C++/WinRT nenabízí tuto záruku. Pokud třída modulu runtime C++/WinRT implementuje IObservableVector<T>, pak nemůžeme předpokládat, že implementace IObservableVector<IInspectable> je nějakým způsobem poskytována.

V důsledku toho bude předchozí příklad muset vypadat takto.

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

A její implementace.

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

Pokud potřebujete přistupovat k objektům v m_bookSkus, budete je muset QI vrátit zpět do Knihkupectví::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;
}

Odvozené třídy

Aby bylo možné dědit z běhové třídy, musí být základní třída komponovatelná. Jazyk C# nevyžaduje, abyste podnikli nějaké speciální kroky, aby vaše třídy byly kompozibilní, ale v C++/WinRT ano. Nezapečetěné klíčové slovo použijete k označení, že chcete, aby vaše třída byla použitelná jako základní třída.

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

V hlavičkovém souboru pro váš typ implementace musíte zahrnout hlavičkový soubor základní třídy předtím, než zahrnete automaticky generovaný hlavičkový soubor odvozené třídy. V opačném případě se zobrazí chyby typu Neplatné použití tohoto typu jako výrazu.

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

Důležitá rozhraní API

• obor názvů winrt

Příbuzná témata

• návody C#
• C++/WinRT
• Hloubková datová vazba