Passare a C++/WinRT da C#

Questo argomento cataloga in modo completo i dettagli tecnici relativi alla conversione del codice sorgente in un progetto C# al relativo equivalente in C++/WinRT.

Per un case study sulla conversione di uno degli esempi di app Piattaforma UWP (Universal Windows Platform), vedi l'argomento complementare Conversione dell'esempio degli Appunti in C++/WinRT da C#. È possibile acquisire esperienza e pratica di conversione seguendo questa procedura dettagliata e la conversione dell'esempio manualmente man mano che si procede.

Come prepararsi e cosa aspettarsi

Il case study Porting the Clipboard sample to C++/WinRT from C# (Conversione dell'esempio degli Appunti in C++/WinRT da C#) illustra esempi dei tipi di decisioni di progettazione software che verranno prese durante la conversione di un progetto in C++/WinRT. È quindi consigliabile prepararsi per la conversione ottenendo una conoscenza approfondita del funzionamento del codice esistente. In questo modo, si otterrà una buona panoramica delle funzionalità dell'app e della struttura del codice, quindi le decisioni che si prendono verranno sempre prese in avanti e nella giusta direzione.

In termini di quali tipi di modifiche di conversione si prevede, è possibile raggrupparli in quattro categorie.

• Trasferire la proiezione del linguaggio. Il Windows Runtime (WinRT) viene proiettato in vari linguaggi di programmazione. Ciascuna di queste proiezioni linguistiche è concepita per risultare idiomatica nel linguaggio di programmazione in questione. Per C#, alcuni tipi di Windows Runtime vengono proiettati come tipi di .NET. Ad esempio, si eseguirà la conversione di System.Collections.Generic.IReadOnlyList<T> in Windows. Foundation.Collections.IVectorView<T>. Anche in C#, alcune operazioni di Windows Runtime vengono proiettate come funzionalità del linguaggio C# utili. Un esempio è che in C# si usa la sintassi dell'operatore += per registrare un delegato di gestione degli eventi. Si tradurranno quindi le funzionalità del linguaggio, ad esempio, nell'operazione fondamentale da eseguire (registrazione eventi, in questo esempio).
• Sintassi del linguaggio delle porte. Molte di queste modifiche sono semplici trasformazioni meccaniche, sostituendo un simbolo per un altro. Ad esempio, la modifica del punto (.) in due punti (::).
• Procedura del linguaggio di porta. Alcuni di questi possono essere semplici e ripetitivi (ad esempio myObject.MyProperty in myObject.MyProperty()). Altri richiedono modifiche più approfondite, ad esempio la conversione di una routine che prevede l'uso di System.Text.StringBuilder a uno che implica l'uso di std::wostringstream.
• Attività relative al porting specifiche di C++/WinRT. Alcuni dettagli del Windows Runtime vengono presi in considerazione in modo implicito da C#, dietro le quinte. Questi dettagli vengono eseguiti in modo esplicito in C++/WinRT. Un esempio è che si usa un .idl file per definire le classi di runtime.

Dopo l'indice basato su attività che segue, le altre sezioni di questo argomento sono strutturate in base alla tassonomia precedente.

Trovare contenuto in base all'attività che si sta eseguendo

Modifiche che coinvolgono la proiezione del linguaggio

Registrare/revocare un gestore eventi

In C++/WinRT sono disponibili diverse opzioni sintattiche per registrare/revocare un delegato del gestore eventi, come descritto in Gestire gli eventi usando delegati in C++/WinRT. Vedere anche Conversione del metodo EnableClipboardContentChangedNotifications.

Talvolta, ad esempio quando il destinatario dell’evento (un oggetto che gestisce un evento) sta per essere distrutto, è opportuno revocare un gestore di eventi in modo che l’origine dell’evento (l’oggetto che genera l’evento) non invochi un oggetto distrutto. Vedere Revocare un delegato registrato. In casi simili, creare una variabile membro event_token per i gestori eventi. Per un esempio, vedere Conversione del metodo EnableClipboardContentChangedNotifications.

Puoi anche registrare un gestore eventi nel markup XAML.

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

In C# il metodo OpenButton_Click può essere privato e XAML sarà comunque in grado di connetterlo all'evento ButtonBase.Click generato da OpenButton.

In C++/WinRT il metodo OpenButton_Click deve essere pubblico nel tipo di implementazionese vuoi registrarlo nel markup XAML. Se si registra un gestore eventi solo nel codice imperativo, il gestore eventi non deve essere pubblico.

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

In alternativa, puoi rendere la pagina XAML di registrazione un tipo friend del tuo tipo di implementazione e rendere privato il metodo OpenButton_Click.

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

Un ultimo scenario si verifica quando il progetto C# che si sta convertendo si associa al gestore eventi nel markup (per ulteriori informazioni su questo scenario, vedere Funzioni in x:Bind).

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

È sufficiente modificare il markup impostando il codice più semplice Click="OpenButton_Click". In alternativa, se si preferisce, è possibile mantenere il markup così come è. Tutto quello che devi fare per supportarlo è dichiarare il gestore eventi in IDL.

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

Modifiche che coinvolgono la sintassi del linguaggio

Migrazione di classi e membri

Sarà necessario decidere, per ogni tipo C#, se eseguirne il porting a un tipo Windows Runtime oppure a una normale classe/struct/enumerazione C++. Per ulteriori informazioni e per esempi dettagliati che illustrano come prendere tali decisioni, vedere Eseguire il porting dell'esempio Clipboard a C++/WinRT da C#.

Una proprietà C# in genere diventa una funzione di accesso, una funzione di modifica e un campo dati sottostante. Per altre info e un esempio, vedi Conversione della proprietà IsClipboardContentChangedEnabled.

Per i campi non-statici, definiscili come membri dati del tipo di implementazione.

Un campo statico di C# diventa una funzione di accesso statica in C++/WinRT e/o una funzione impostatrice. Per altre info e un esempio, vedi Conversione del costruttore, Current e FEATURE_NAME.

Per le funzioni membro, anche in questo caso, è necessario decidere per ognuna se debba essere inclusa nell'IDL oppure se si tratti di una funzione membro pubblica o privata del tipo di implementazione. Per altre info ed esempi su come decidere, vedi IDL per il tipo MainPage.

Porting del codice XAML e dei file di risorse

Nel caso della conversione dell'esempio degli Appunti in C++/WinRT da C#, è stato possibile usare lo stesso markup XAML (incluse le risorse) e i file di asset nel progetto C# e C++/WinRT. In alcuni casi, le modifiche apportate al markup saranno necessarie per ottenere tale risultato. Vedi Copiare il codice XAML e gli stili necessari per completare la conversione di MainPage.

Modifiche che coinvolgono procedure all'interno del linguaggio

Le sezioni seguenti illustrano in modo più dettagliato alcuni elementi della tabella.

Costruzione di elementi dell'interfaccia utente

Questi esempi di codice mostrano la costruzione di un elemento dell'interfaccia utente nel codice imperativo di una pagina 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()

I tipi C# forniscono il metodo Object.ToString .

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

C++/WinRT non fornisce direttamente questa funzionalità, ma puoi passare a alternative.

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

C++/WinRT supporta anche winrt::to_hstring per un numero limitato di tipi. È necessario aggiungere sovraccarichi per tutti gli eventuali tipi aggiuntivi che si desidera convertire in stringa.

Nel caso in cui si voglia convertire un enum in stringa, sarà necessario fornire l'implementazione di 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));
        }
    }
}

Queste conversioni in stringa vengono spesso utilizzate implicitamente dal data binding.

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

Questi binding eseguiranno la conversione winrt::to_hstring della proprietà associata. Nel caso del secondo esempio ( statusEnum), è necessario fornire il proprio overload di winrt::to_hstring, in caso contrario verrà visualizzato un errore del compilatore.

Vedere anche Conversione del metodo Footer_Click.

Creazione di stringhe

Per la compilazione di stringhe, C# ha un tipo StringBuilder predefinito.

Vedere anche Conversione del metodo BuildClipboardFormatsOutputString e Conversione del metodo DisplayChangedFormats.

Esecuzione del codice nel thread principale dell'interfaccia utente

Questo esempio è tratto dall'esempio dello scanner di codice a barre.

Quando vuoi lavorare sul thread principale dell'interfaccia utente in un progetto C#, in genere usi il metodo DispatcherQueue.TryEnqueue (o coreDispatcher.RunAsync precedente in UWP). Ecco l'aspetto del modello in C#.

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

È molto più semplice esprimerlo in C++/WinRT. Si noti che accettiamo i parametri per valore, partendo dal presupposto che vorremo accedervi dopo il primo punto di sospensione (in questo caso, co_await). Per altre info, vedi Passaggio di parametri.

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

Se è necessario eseguire il lavoro con una priorità diversa da quella predefinita, consultare la funzione winrt::resume_foreground, che ha un overload che accetta una priorità. Per esempi di codice che mostrano come attendere il completamento di una chiamata a winrt::resume_foreground, vedi Programmazione tenendo conto dell'affinità dei thread.

Attività relative al porting specifiche di C++/WinRT

Definire le classi di runtime in IDL

Vedere IDL per il tipo MainPage e Consolidare i .idl file.

Includere i file di intestazione dello spazio dei nomi C++/WinRT Windows necessari

In C++/WinRT, ogni volta che si desidera usare un tipo di un namespace di Windows, è necessario includere il file header C++/WinRT del corrispondente namespace di Windows. Per un esempio, vedere Conversione del metodo NotifyUser.

Boxing e unboxing

C# converte automaticamente i valori scalari in oggetti. C++/WinRT richiede di chiamare in modo esplicito la funzione winrt::box_value . Entrambe le lingue richiedono che si esegua esplicitamente l'unboxing. Vedi Boxing e unboxing con C++/WinRT.

Nelle tabelle seguenti si useranno queste definizioni.

C++/CX e C# generano eccezioni se si tenta di eseguire l'unboxing di un puntatore null in un tipo di valore. C++/WinRT considera questo un errore di programmazione e va in crash. In C++/WinRT usa la funzione winrt::unbox_value_or se vuoi gestire il caso in cui l'oggetto non sia del tipo che pensavi fosse.

Per un esempio, vedere Conversione del metodo OnNavigatedTo e Conversione del metodo Footer_Click.

Boxing e unboxing di una stringa

Una stringa è in alcuni modi un tipo di valore e in altri modi un tipo riferimento. C# e C++/WinRT trattano le stringhe in modo diverso.

Il tipo ABI HSTRING è un puntatore a una stringa con conteggio dei riferimenti. Ma non deriva da IInspectable, quindi non è tecnicamente un oggetto. Inoltre, una HSTRING null rappresenta la stringa vuota. Il boxing di elementi non derivati da IInspectable viene eseguito eseguendo il wrapping all'interno di un oggetto IReference<T> e il Windows Runtime fornisce un'implementazione standard sotto forma di oggetto PropertyValue (i tipi personalizzati vengono segnalati come PropertyType::OtherType).

C# rappresenta una stringa Windows Runtime come tipo riferimento, mentre C++/WinRT proietta una stringa come tipo valore. Ciò significa che una stringa null boxed può avere rappresentazioni diverse a seconda di come ci si è arrivati.

Concetti di base di boxing e unboxing.

Rendere disponibile una classe per l'estensione di markup {Binding}

Se si intende utilizzare l'estensione di markup {Binding} per associare i dati al proprio tipo di dati, vedere Binding object declared using {Binding}.

Utilizzo di oggetti nel markup XAML

In un progetto C# puoi usare membri privati e elementi denominati dal markup XAML. In C++/WinRT, tuttavia, tutte le entità utilizzate tramite l'estensione di markup XAML {x:Bind} devono essere esposte pubblicamente in IDL.

Inoltre, l'associazione a un valore booleano visualizza true o false in C#, ma mostra Windows. Foundation.IReference'1<Boolean> in C++/WinRT.

Per altre info ed esempi di codice, vedi Utilizzo di oggetti dal markup.

Rendere disponibile un'origine dati per il markup XAML

In C++/WinRT versione 2.0.190530.8 o successiva , winrt::single_threaded_observable_vector crea un vettore osservabile che supporta sia IObservableVector<T> che IObservableVector<IInspectable>. Per un esempio, vedere Conversione della proprietà Scenarios.

È possibile scrivere il file MIDL (.idl) in questo modo (vedere anche Spostare le classi di runtime in file 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; };
    }
}

E implementalo così.

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

Per ulteriori informazioni, vedere controlli degli elementi XAML; associazione a una raccolta C++/WinRT, e Raccolte con C++/WinRT.

Rendere disponibile un'origine dati per il markup XAML (prima di C++/WinRT 2.0.190530.8)

Il data binding XAML richiede che l'origine degli elementi implementi IIterable<IInspectable>, nonché una delle combinazioni seguenti di interfacce.

• IObservableVector<IInspectable>
• IBindableVector e INotifyCollectionChanged
• IBindableVector e IBindableObservableVector
• IBindableVector da solo (non risponderà alle modifiche)
• IVector<IInspectable>
• IBindableIterable (eseguirà l'iterazione e salverà gli elementi in una raccolta privata)

Non è possibile rilevare un'interfaccia generica come IVector<T> in fase di esecuzione. Ogni IVector<T> ha un identificatore di interfaccia diverso (IID), che è una funzione di T. Qualsiasi sviluppatore può espandere il set di T in modo arbitrario, quindi chiaramente il codice di associazione XAML non può mai conoscere il set completo per cui eseguire la query. Questa restrizione non è un problema per C# perché ogni oggetto CLR che implementa IEnumerable<T> implementa automaticamente IEnumerable. A livello di ABI, significa che ogni oggetto che implementa IObservableVector<T> implementa automaticamente IObservableVector<IInspectable>.

C++/WinRT non offre tale garanzia. Se una classe di runtime C++/WinRT implementa IObservableVector<T>, non possiamo presupporre che venga fornita anche un'implementazione di IObservableVector<IInspectable> .

Di conseguenza, ecco come verrà visualizzato l'esempio precedente.

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

E l'implementazione.

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

Se è necessario accedere agli oggetti in m_bookSkus, sarà necessario tornare a 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;
}

Classi derivate

Per derivare da una classe di runtime, la classe base deve essere componibile. C# non richiede alcuna procedura speciale per rendere le classi componibili, ma C++/WinRT. Usare la parola chiave unsealed per indicare che si vuole che la classe sia utilizzabile come classe di base.

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

Nel file di intestazione per il tipo di implementazione è necessario includere il file di intestazione della classe di base prima di includere l'intestazione generata automaticamente per la classe derivata. In caso contrario, si otterranno errori come "Uso non valido di questo tipo come espressione".

// 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 importanti

• spazio dei nomi WinRT

Argomenti correlati

• lezioni di C#
• C++/WinRT
• Informazioni approfondite sul data binding