Erstellen von Komponenten für Windows-Runtime in C# und Visual BasicCreating Windows Runtime Components in C# and Visual Basic

Ab .NET Framework 4.5, können Sie verwalteten Code verwenden, um Ihre eigenen Windows-Runtime-Typen zu erstellen und Packen Sie sie in einer Windows-Runtime-Komponente.Starting with the .NET Framework 4.5, you can use managed code to create your own Windows Runtime types and package them in a Windows Runtime component. Sie können Ihre Komponente verwenden, in apps für universelle Windows-Plattform (UWP), die in C++, JavaScript, Visual Basic geschrieben werden oder C#.You can use your component in Universal Windows Platform (UWP) apps that are written in C++, JavaScript, Visual Basic, or C#. In diesem Thema werden die Regeln zum Erstellen einer Komponente und einige Aspekte der .NET Framework-Unterstützung für die Windows-Runtime erläutert.This topic outlines the rules for creating a component, and discusses some aspects of .NET Framework support for the Windows Runtime. Im Allgemeinen ist diese Unterstützung allen .NET Framework-Programmierern klar.In general, that support is designed to be transparent to the .NET Framework programmer. Wenn Sie aber eine Komponente erstellen, die mit JavaScript oder C++ verwendet werden soll, müssen Sie auf die Unterschiede bei der Unterstützung der Windows-Runtime durch diese Sprachen achten.However, when you create a component to use with JavaScript or C++, you need to be aware of differences in the way those languages support the Windows Runtime.

Wenn Sie eine Komponente für die Verwendung nur in UWP-apps erstellen, die in Visual Basic geschrieben werden oder C#, und die Komponente enthält keine UWP-Steuerelemente, und klicken Sie dann mithilfe von Onsider der Klassenbibliothek Vorlage anstelle von der Windows Runtime-Komponente in Microsoft Visual Studio-Projektvorlage.If you are creating a component for use only in UWP apps that are written in Visual Basic or C#, and the component does not contain UWP controls, then onsider using the Class Library template instead of the Windows Runtime Component project template in Microsoft Visual Studio. Eine einfache Klassenbibliothek weist weniger Einschränkungen auf.There are fewer restrictions on a simple class library.

Deklarieren von Typen in Komponenten für Windows-RuntimeDeclaring types in Windows Runtime Components

Intern können die Windows-Runtime-Typen in Ihrer Komponente alle .NET Framework-Funktionalitäten verwenden, die in einer UWP-app zulässig ist.Internally, the Windows Runtime types in your component can use any .NET Framework functionality that's allowed in a UWP app. Weitere Informationen finden Sie unter .NET für UWP-apps.For more info, see .NET for UWP apps.

Extern können die Member Ihrer Typen verfügbar machen nur über die Windows-Runtime-Typen für ihre Parameter und Rückgabewerte.Externally, the members of your types can expose only Windows Runtime types for their parameters and return values. Die folgende Liste beschreibt die Einschränkungen für .NET Framework-Typen, die von einer Windows-Runtime-Komponente verfügbar gemacht werden.The following list describes the limitations on .NET Framework types that are exposed from a Windows Runtime Component.

  • Die Felder, Parameter und Rückgabewerte aller öffentlichen Typen und Member in der Komponente müssen Windows-Runtime-Typen sein.The fields, parameters, and return values of all the public types and members in your component must be Windows Runtime types. Diese Einschränkung gilt auch für die Windows-Runtime-Typen, die Sie erstellen und die Typen an, die von der Windows-Runtime selbst bereitgestellt werden.This restriction includes the Windows Runtime types that you author as well as types that are provided by the Windows Runtime itself. Außerdem trifft sie auf einige .NET Framework-Typen zu.It also includes a number of .NET Framework types. Die Aufnahme dieser Typen ist Teil der Unterstützung der .NET Framework stellt die normale Verwendung der Windows-Runtime in verwaltetem Code—Code bekannte .NET Framework-Typen anstelle der zugrunde liegenden Windows-Runtime-Typen zu verwenden scheint.The inclusion of these types is part of the support the .NET Framework provides to enable the natural use of the Windows Runtime in managed code—your code appears to use familiar .NET Framework types instead of the underlying Windows Runtime types. Beispielsweise können Sie .NET Framework-primitive Typen wie z. B. Int32 und doppelte, bestimmte grundlagentypen wie DateTimeOffset und Uri , sowie einige häufig verwendete generische Schnittstellentypen wie z. B. "IEnumerable"<T> (IEnumerable (Of T) in Visual Basic) und IDictionary< TKey, TValue> .For example, you can use .NET Framework primitive types such as Int32 and Double, certain fundamental types such as DateTimeOffset and Uri, and some commonly used generic interface types such as IEnumerable<T> (IEnumerable(Of T) in Visual Basic) and IDictionary<TKey,TValue>. Beachten Sie, dass die Typargumente dieser generischen Typen mit Windows-Runtime-Typen sein müssen.Note that the type arguments of these generic types must be Windows Runtime types. Dies wird in den Abschnitten erläutert übergeben von Windows-Runtime-Typen an verwalteten Code und übergeben von verwalteten Typen an Windows-Runtimeweiter unten in diesem Thema.This is discussed in the sections Passing Windows Runtime types to managed code and Passing managed types to the Windows Runtime, later in this topic.

  • Öffentliche Klassen und Schnittstellen können Methoden, Eigenschaften und Ereignisse enthalten.Public classes and interfaces can contain methods, properties, and events. Sie können Delegaten für Ereignisse zu deklarieren, oder die EventHandler<T> delegieren.You can declare delegates for your events, or use the EventHandler<T> delegate. Eine öffentliche Klasse oder Schnittstelle kann nicht:A public class or interface can't:

    • generisch sein.Be generic.
    • Implementieren einer Schnittstelle, die nicht auf einem Windows-Runtime-Schnittstelle ist (jedoch Sie erstellen Ihre eigenen Windows-Runtime-Schnittstellen und diese implementieren).Implement an interface that is not a Windows Runtime interface (however, you can create your own Windows Runtime interfaces and implement them).
    • Ableiten von Typen, die nicht in der Windows-Runtime, z. B. "System.Exception" und System.EventArgs.Derive from types that are not in the Windows Runtime, such as System.Exception and System.EventArgs.
  • Alle öffentliche Typen müssen über einen Stammnamespace verfügen, der mit dem Assemblynamen übereinstimmt, und der Assemblyname darf nicht mit „Windows” beginnen.All public types must have a root namespace that matches the assembly name, and the assembly name must not begin with "Windows".

    Tipp.Tip. Standardmäßig haben Visual Studio-Projekte für Namespacenamen, die Namen der Assembly übereinstimmen.By default, Visual Studio projects have namespace names that match the assembly name. In Visual Basic wird die Namespace-Anweisung für diesen Standardnamespace nicht im Code angezeigt.In Visual Basic, the Namespace statement for this default namespace is not shown in your code.

  • Öffentliche Strukturen können nur öffentliche Felder als Member enthalten, und diese Felder müssen Werttypen oder Zeichenfolgen sein.Public structures can't have any members other than public fields, and those fields must be value types or strings.

  • Öffentliche Klassen müssen versiegelt (NotInheritable in Visual Basic) sein.Public classes must be sealed (NotInheritable in Visual Basic). Erfordert das Programmiermodell Polymorphie, können Sie eine öffentliche Schnittstelle erstellen und implementieren diese Schnittstelle für die Klassen, die polymorph sein müssen.If your programming model requires polymorphism, then you can create a public interface, and implement that interface on the classes that must be polymorphic.

Debuggen der KomponenteDebugging your component

Wenn sowohl Ihre UWP-app und Ihre Komponente mit verwaltetem Code basieren, können Sie beide gleichzeitig Debuggen.If both your UWP app and your component are built with managed code, then you can debug them both at the same time.

Wenn Sie Ihre Komponente als Teil einer UWP-app mit C++ testen, können Sie verwalteten und systemeigenen Code gleichzeitig Debuggen.When you're testing your component as part of a UWP app using C++, you can debug managed and native code at the same time. Die Vorgabe ist nur systemeigener Code.The default is native code only.

So debuggen Sie systemeigenen C++-Code und verwalteten CodeTo debug both native C++ code and managed code

  1. Öffnen Sie das Kontextmenü für das Visual C++-Projekt, und wählen Sie Eigenschaften aus.Open the shortcut menu for your Visual C++ project, and choose Properties.
  2. Wählen Sie auf den Eigenschaftenseiten unter Konfigurationseigenschaften die Option Debuggen aus.In the property pages, under Configuration Properties, choose Debugging.
  3. Wählen Sie Debuggertyp aus, und ändern Sie dann in der Dropdownliste Nur systemeigen in Gemischt (verwaltet und systemeigen) .Choose Debugger Type, and in the drop-down list box change Native Only to Mixed (Managed and Native). Klicken Sie auf OK.Choose OK.
  4. Legen Sie Haltepunkte im systemeigenen und verwalteten Code fest.Set breakpoints in native and managed code.

Wenn Sie Ihre Komponente als Teil einer UWP-app mit JavaScript testen, ist die Lösung wird standardmäßig in JavaScript-Debugmodus.When you're testing your component as part of a UWP app using JavaScript, by default the solution is in JavaScript debugging mode. In Visual Studio ist das gleichzeitige Debuggen von JavaScript und verwaltetem Code nicht möglich.In Visual Studio, you can't debug JavaScript and managed code at the same time.

So debuggen Sie verwalteten Code anstelle von JavaScriptTo debug managed code instead of JavaScript

  1. Öffnen Sie das Kontextmenü für das JavaScript-Projekt, und wählen Sie Eigenschaften aus.Open the shortcut menu for your JavaScript project, and choose Properties.
  2. Wählen Sie auf den Eigenschaftenseiten unter Konfigurationseigenschaften die Option Debuggen aus.In the property pages, under Configuration Properties, choose Debugging.
  3. Wählen Sie Debuggertyp aus, und ändern Sie in der Dropdownliste Nur Skript in Nur verwaltet.Choose Debugger Type, and in the drop-down list box change Script Only to Managed Only. Klicken Sie auf OK.Choose OK.
  4. Legen Sie Haltepunkte im verwaltetem Code fest, und debuggen Sie wie gewohnt.Set breakpoints in managed code and debug as usual.

Übergeben von Windows-Runtime Typen an verwalteten CodePassing Windows Runtime types to managed code

Wie bereits im Abschnitt erwähnt Deklarieren von Typen in Windows-Runtime-Komponenten, bestimmte .NET Framework-Typen können in den Signaturen von Membern öffentlicher Klassen erscheinen.As mentioned previously in the section Declaring types in Windows Runtime Components, certain .NET Framework types can appear in the signatures of members of public classes. Dies ist Teil der Unterstützung, die .NET Framework bietet, um die natürliche Verwendung der Windows-Runtime in verwaltetem Code zu ermöglichen.This is part of the support that the .NET Framework provides to enable the natural use of the Windows Runtime in managed code. Darin sind primitive Typen und einige Klassen und Schnittstellen enthalten.It includes primitive types and some classes and interfaces. Wenn die Komponente über JavaScript oder von C++-Code verwendet wird, ist es wichtig zu wissen, wie die .NET Framework-Typen an den Aufrufer angezeigt werden.When your component is used from JavaScript, or from C++ code, it's important to know how your .NET Framework types appear to the caller. Finden Sie unter Exemplarische Vorgehensweise: Erstellen einer einfachen Komponente in C# oder Visual Basic und Aufrufen dieser Komponente über JavaScript Beispiele mit JavaScript.See Walkthrough: Creating a simple component in C# or Visual Basic and calling it from JavaScript for examples with JavaScript. In diesem Abschnitt werden häufig verwendete Typen beschrieben.This section discusses commonly used types.

In .NET Framework, Primitive Typen wie die Int32 Struktur besitzen viele nützliche Eigenschaften und Methoden, wie z. B. die TryParse Methode.In the .NET Framework, primitive types such as the Int32 structure have many useful properties and methods, such as the TryParse method. Im Gegensatz dazu haben primitive Typen und Strukturen in der Windows-Runtime nur Felder.By contrast, primitive types and structures in the Windows Runtime only have fields. Wenn Sie diese Typen an verwalteten Code übergeben, verhalten sie sich wie .NET Framework-Typen, und Sie können die Eigenschaften und Methoden der .NET Framework-Typen wie gewohnt verwenden.When you pass these types to managed code, they appear to be .NET Framework types, and you can use the properties and methods of the .NET Framework types as you normally would. Die folgende Liste fasst die Ersetzungen zusammen, die automatisch in der IDE vorgenommen werden:The following list summarizes the substitutions that are made automatically in the IDE:

  • Für die Windows-Runtime-primitive Int32, Int64, einzelne, doppelte, booleschen, Zeichenfolge (eine unveränderliche Auflistung von Unicode-Zeichen), Enum, UInt32, UInt64, und Guid, verwenden Sie den Typ mit dem gleichen Namen im System-Namespace.For the Windows Runtime primitives Int32, Int64, Single, Double, Boolean, String (an immutable collection of Unicode characters), Enum, UInt32, UInt64, and Guid, use the type of the same name in the System namespace.
  • Für UInt8, verwenden Sie System.Byte.For UInt8, use System.Byte.
  • Für Char16, verwenden Sie System.Char.For Char16, use System.Char.
  • Für die "iinspectable" Schnittstelle, verwenden Sie "System.Object" .For the IInspectable interface, use System.Object.

Wenn C# oder Visual Basic bietet ein Programmiersprachen-Schlüsselwort für alle Typen, dann können Sie stattdessen das Schlüsselwort verwenden.If C# or Visual Basic provides a language keyword for any of these types, then you can use the language keyword instead.

Zusätzlich zu primitiven Typen erscheinen einige grundlegende, häufig verwendete Windows-Runtime-Typen in verwaltetem Code als ihre .NET Framework-Entsprechung.In addition to primitive types, some basic, commonly used Windows Runtime types appear in managed code as their .NET Framework equivalents. Nehmen wir beispielsweise an Ihre JavaScript-Code verwendet die Windows.Foundation.Uri -Klasse, und Sie möchten, zum Übergeben einer C# oder Visual Basic-Methode.For example, suppose your JavaScript code uses the Windows.Foundation.Uri class, and you want to pass it to a C# or Visual Basic method. Entspricht der Typ in verwaltetem Code von .NET Framework ist System.Uri -Klasse, und das ist der Typ, der für den Methodenparameter verwendet.The equivalent type in managed code is the .NET Framework System.Uri class, and that's the type to use for the method parameter. Sie können feststellen, wann ein Windows-Runtime-Typ als .NET Framework-Typ erscheint, da IntelliSense in Visual Studio den Windows-Runtime-Typ ausblendet, wenn Sie verwalteten Code schreiben und den entsprechenden .NET Framework-Typ anzeigt.You can tell when a Windows Runtime type appears as a .NET Framework type, because IntelliSense in Visual Studio hides the Windows Runtime type when you're writing managed code, and presents the equivalent .NET Framework type. (In der Regel haben beiden Typen den gleichen Namen.(Usually the two types have the same name. Beachten Sie jedoch, dass die Windows.Foundation.DateTime Struktur wird in verwaltetem Code als System.DateTimeOffset und nicht als System.DateTime.)However, note that the Windows.Foundation.DateTime structure appears in managed code as System.DateTimeOffset and not as System.DateTime.)

Für einige häufig verwendete Sammlungstypen erfolgt die Zuordnung zwischen den Schnittstellen, die von einem Windows-Runtime-Typ implementiert werden, und den Schnittstellen, die vom entsprechenden .NET Framework-Typ implementiert werden.For some commonly used collection types, the mapping is between the interfaces that are implemented by a Windows Runtime type and the interfaces that are implemented by the corresponding .NET Framework type. Wie bei den bereits erwähnten Typen deklarieren Sie Parametertypen, indem Sie den .NET Framework-Typ verwenden.As with the types mentioned above, you declare parameter types by using the .NET Framework type. Dadurch werden bestimmte Unterschiede zwischen den Typen ausgeblendet, und das Schreiben von .NET Framework-Code wirkt natürlicher.This hides some differences between the types and makes writing .NET Framework code more natural.

In der folgenden Tabelle sind die häufigsten dieser generischen Schnittstellentypen zusammen mit anderen allgemeinen Klassen- und Schnittstellenzuordnungen aufgeführt.The following table lists the most common of these generic interface types, along with other common class and interface mappings. Eine vollständige Liste der Windows-Runtime-Typen, die vom .NET Framework zugeordnet werden soll, finden Sie unter .NET Framework-Zuordnungen von Windows-Runtime-Typen.For a complete list of Windows Runtime types that the .NET Framework maps, see .NET Framework mappings of Windows Runtime types.

Windows-RuntimeWindows Runtime .NET Framework.NET Framework
IIterable<T>IIterable<T> IEnumerable<T>IEnumerable<T>
IVector<T>IVector<T> IList<T>IList<T>
IVectorView<T>IVectorView<T> IReadOnlyList<T>IReadOnlyList<T>
IMap<K, V>IMap<K, V> IDictionary<TKey, TValue>IDictionary<TKey, TValue>
IMapView<K, V>IMapView<K, V> IReadOnlyDictionary<TKey, TValue>IReadOnlyDictionary<TKey, TValue>
IKeyValuePair<K, V>IKeyValuePair<K, V> KeyValuePair<TKey, TValue>KeyValuePair<TKey, TValue>
IBindableIterableIBindableIterable IEnumerableIEnumerable
IBindableVecinrIBindableVector IListIList
Windows.UI.Xaml.Data.INotifyPropertyChangedWindows.UI.Xaml.Data.INotifyPropertyChanged System.ComponentModel.INotifyPropertyChangedSystem.ComponentModel.INotifyPropertyChanged
Windows.UI.Xaml.Data.PropertyChangedEventHandlerWindows.UI.Xaml.Data.PropertyChangedEventHandler System.ComponentModel.PropertyChangedEventHandlerSystem.ComponentModel.PropertyChangedEventHandler
Windows.UI.Xaml.Data.PropertyChangedEventArgsWindows.UI.Xaml.Data.PropertyChangedEventArgs System.ComponentModel.PropertyChangedEventArgsSystem.ComponentModel.PropertyChangedEventArgs

Wenn ein Typ mehrere Schnittstellen implementiert, können Sie jede Schnittstelle verwenden, die als Parametertyp oder Rückgabetyp eines Members implementiert wird.When a type implements more than one interface, you can use any of the interfaces it implements as a parameter type or return type of a member. Sie können z. B. übergeben oder Zurückgeben einer Wörterbuch<ganze Zahl, Zeichenfolge> (Dictionary (Of Integer, String) in Visual Basic) als IDictionary<ganze Zahl, Zeichenfolge> , IReadOnlyDictionary<ganze Zahl, Zeichenfolge> , oder "IEnumerable"< System.Collections.Generic.KeyValuePair<TKey, TValue>> .For example, you can pass or return a Dictionary<int, string> (Dictionary(Of Integer, String) in Visual Basic) as IDictionary<int, string>, IReadOnlyDictionary<int, string>, or IEnumerable<System.Collections.Generic.KeyValuePair<TKey, TValue>>.

Wichtig

JavaScript verwendet die Schnittstelle, die zuerst in der Liste der Schnittstellen angezeigt wird, die ein verwalteter Typ implementiert.JavaScript uses the interface that appears first in the list of interfaces that a managed type implements. Wenn Sie zurückkehren, z. B. Wörterbuch<ganze Zahl, Zeichenfolge> an JavaScript-Code, sie wird als IDictionary<ganze Zahl, Zeichenfolge> unabhängig davon, welche Schnittstelle, die Sie als Rückgabetyp angeben.For example, if you return Dictionary<int, string> to JavaScript code, it appears as IDictionary<int, string> no matter which interface you specify as the return type. Das bedeutet, dass die erste Schnittstelle Member enthalten muss, die in den nächsten Schnittstellen erscheinen, damit diese Member für JavaScript sichtbar sind.This means that if the first interface doesn't include a member that appears on later interfaces, that member isn't visible to JavaScript.

In der Windows-Runtime IMap<K, V> und IMapView<K, V> durchlaufen, indem Sie IKeyValuePair.In the Windows Runtime, IMap<K, V> and IMapView<K, V> are iterated by using IKeyValuePair. Wenn Sie sie an verwalteten Code übergeben, werden sie als IDictionary<TKey, TValue> und IReadOnlyDictionary<TKey, TValue> , sodass Sie verwenden, auf natürliche Weise System.Collections.Generic.KeyValuePair<TKey, TValue> um diese aufzulisten.When you pass them to managed code, they appear as IDictionary<TKey, TValue> and IReadOnlyDictionary<TKey, TValue>, so naturally you use System.Collections.Generic.KeyValuePair<TKey, TValue> to enumerate them.

Die Darstellungsweise von Schnittstellen in verwaltetem Code wirkt sich auf die Darstellungsweise der Typen aus, die diese Schnittstellen implementieren.The way interfaces appear in managed code affects the way types that implement these interfaces appear. Z. B. die PropertySet -Klasse implementiert IMap<K, V> , die angezeigt wird, in verwaltetem Code als IDictionary<TKey, TValue> .For example, the PropertySet class implements IMap<K, V>, which appears in managed code as IDictionary<TKey, TValue>. PropertySet scheint, als ob er implementiert IDictionary<TKey, TValue> anstelle von IMap<K, V> in verwaltet Code anscheinend über eine hinzufügen -Methode, die wie verhält sich die hinzufügen -Methode in .NET Framework-Wörterbüchern.PropertySet appears as if it implemented IDictionary<TKey, TValue> instead of IMap<K, V>, so in managed code it appears to have an Add method, which behaves like the Add method on .NET Framework dictionaries. Es nicht angezeigt, damit ein einfügen Methode.It doesn't appear to have an Insert method. Sie finden dieses Beispiel im Thema Exemplarische Vorgehensweise: Erstellen einer einfachen Komponente in C# oder Visual Basic und Aufrufen dieser Komponente über JavaScript.You can see this example in the topic Walkthrough: Creating a simple component in C# or Visual Basic and calling it from JavaScript.

Übergeben von verwalteten Typen an die Windows-RuntimePassing managed types to the Windows Runtime

Wie bereits im vorherigen Abschnitt erwähnt, können einige Windows-Runtime-Typen als .NET Framework-Typen in den Signaturen von Komponentenmembern oder in den Signaturen von Windows-Runtime-Membern erscheinen, wenn Sie sie in der IDE verwenden.As discussed in the previous section, some Windows Runtime types can appear as .NET Framework types in the signatures of your component's members, or in the signatures of Windows Runtime members when you use them in the IDE. Wenn Sie .NET Framework-Typen an diese Member übergeben oder als Rückgabewerte von Komponentenmembern verwenden, werden sie dem Code auf der anderen Seite als der entsprechende Windows-Runtime-Typ dargestellt.When you pass .NET Framework types to these members or use them as the return values of your component's members, they appear to the code on the other side as the corresponding Windows Runtime type. Weitere Beispiele für die Auswirkungen, wenn die Komponente aus JavaScript aufgerufen wird, finden Sie unter im Abschnitt "Rückgabe von verwalteten Typen aus der Komponente" in Exemplarische Vorgehensweise: Erstellen einer einfachen Komponente in C# oder Visual Basic und Aufrufen dieser Komponente über JavaScript.For examples of the effects this can have when your component is called from JavaScript, see the "Returning managed types from your component" section in Walkthrough: Creating a simple component in C# or Visual Basic and calling it from JavaScript.

Überladene MethodenOverloaded methods

In der Windows-Runtime können Methoden überladen werden.In the Windows Runtime, methods can be overloaded. Wenn Sie mehrere Überladungen mit der gleichen Anzahl von Parametern deklarieren, Sie müssen jedoch anwenden, die Windows.Foundation.Metadata.DefaultOverloadAttribute -Attribut auf nur eine dieser Überladungen.However, if you declare multiple overloads with the same number of parameters, you must apply the Windows.Foundation.Metadata.DefaultOverloadAttribute attribute to only one of those overloads. Nur diese Überladung kann aus JavaScript aufgerufen werden.That overload is the only one you can call from JavaScript. Im folgenden Code ist beispielsweise die Überladung, die int übernimmt (Integer in Visual Basic), die Standardüberladung.For example, in the following code the overload that takes an int (Integer in Visual Basic) is the default overload.

public string OverloadExample(string s)
{
    return s;
}

[Windows.Foundation.Metadata.DefaultOverload()]
public int OverloadExample(int x)
{
    return x;
}
Public Function OverloadExample(ByVal s As String) As String
    Return s
End Function

<Windows.Foundation.Metadata.DefaultOverload> _
Public Function OverloadExample(ByVal x As Integer) As Integer
    Return x
End Function

[WICHTIG] JavaScript ermöglicht die Übergabe aller Werte, OverloadExample, und wandelt den Wert in den Typ, der durch den Parameter erforderlich ist.[IMPORTANT] JavaScript allows you to pass any value to OverloadExample, and coerces the value to the type that is required by the parameter. Rufen Sie OverloadExample mit "Zweiundvierzig", "42" oder 42,3 alle diese Werte werden an die Überladung übergeben.You can call OverloadExample with "forty-two", "42", or 42.3, but all those values are passed to the default overload. Die standardmäßige Überladung im vorherigen Beispiel gibt 0, 42 und 42 zurück.The default overload in the previous example returns 0, 42, and 42, respectively.

Sie können nicht angewendet werden die DefaultOverloadAttribute-Attribut an die Konstruktoren.You can't apply the DefaultOverloadAttribute attribute to constructors. Alle Konstruktoren in einer Klasse müssen eine unterschiedliche Anzahl von Parametern aufweisen.All the constructors in a class must have different numbers of parameters.

Implementieren von IStringableImplementing IStringable

Ab Windows 8.1, die Windows-Runtime enthält eine IStringable Schnittstelle, deren einzige Methode, IStringable.ToString, eine grundlegende formatierungsunterstützung vergleichbar mit der gebotenen bietet Object.ToString.Starting with Windows 8.1, the Windows Runtime includes an IStringable interface whose single method, IStringable.ToString, provides basic formatting support comparable to that provided by Object.ToString. Wenn Sie sich entschließen, implementieren Sie IStringable in einem öffentlich verwalteten Typ, der in einer Windows-Runtime-Komponente exportiert wird, gelten die folgenden Einschränkungen:If you do choose to implement IStringable in a public managed type that is exported in a Windows Runtime component, the following restrictions apply:

  • Sie können definieren, die IStringable -Schnittstelle nur in einer "class Implements"-Beziehung, z. B. den folgenden Code in C#:You can define the IStringable interface only in a "class implements" relationship, such as the following code in C#:

    public class NewClass : IStringable
    

    Oder in Visual Basic-Code:Or the following Visual Basic code:

    Public Class NewClass : Implements IStringable
    
  • Sie können nicht implementieren IStringable auf einer Schnittstelle.You can't implement IStringable on an interface.

  • Sie können einen Parameter vom Typ nicht deklarieren IStringable.You can't declare a parameter to be of type IStringable.

  • IStringable darf nicht der Rückgabetyp einer Methode, eine Eigenschaft oder ein Feld sein.IStringable can't be the return type of a method, property, or field.

  • Sie können nicht ausgeblendet werden Ihre IStringable Implementierung von Basisklassen mithilfe eine Methodendefinition wie die folgende:You can't hide your IStringable implementation from base classes by using a method definition such as the following:

    public class NewClass : IStringable
    {
       public new string ToString()
       {
          return "New ToString in NewClass";
       }
    }
    

    Stattdessen die IStringable.ToString Implementierung muss die basisklassenimplementierung immer überschreiben.Instead, the IStringable.ToString implementation must always override the base class implementation. Sie können Ausblenden einer ToString Implementierung nur, indem sie auf einer stark typisierten Klasseninstanz aufrufen.You can hide a ToString implementation only by invoking it on a strongly typed class instance.

Hinweis

Unter einer Vielzahl von Bedingungen, Aufrufe von systemeigenem Code von einem verwalteten Typ, der implementiert IStringable oder blendet Sie aus der ToString Implementierung kann zu unerwartetem Verhalten führen.Under a variety of conditions, calls from native code to a managed type that implements IStringable or hides its ToString implementation can produce unexpected behavior.

Asynchrone VorgängeAsynchronous operations

Um eine asynchrone Methode in der Komponente zu implementieren, fügen Sie hinzu "Async" am Ende des Methodennamens, und zurückgeben Sie eines der Windows-Runtime-Schnittstellen, die asynchrone Aktionen oder Operationen darstellen: IAsyncAction, IAsyncActionWithProgress<TProgress> , IAsyncOperation<TResult> , oder IAsyncOperationWithProgress<TResult, TProgress> .To implement an asynchronous method in your component, add "Async" to the end of the method name and return one of the Windows Runtime interfaces that represent asynchronous actions or operations: IAsyncAction, IAsyncActionWithProgress<TProgress>, IAsyncOperation<TResult>, or IAsyncOperationWithProgress<TResult, TProgress>.

Können Sie .NET Framework-Aufgaben (die Aufgabe -Klasse und generische Aufgabe<TResult> Klasse), die asynchrone Methode zu implementieren.You can use .NET Framework tasks (the Task class and generic Task<TResult> class) to implement your asynchronous method. Sie müssen eine Aufgabe, die eine laufende Operation, wie z. B. eine Aufgabe darstellt, die von einer asynchronen Methode in geschriebenen zurückgegeben wird zurückgeben C# oder Visual Basic oder eine Aufgabe, die von zurückgegeben wird das "Task.Run" -Methode.You must return a task that represents an ongoing operation, such as a task that is returned from an asynchronous method written in C# or Visual Basic, or a task that is returned from the Task.Run method. Wenn Sie für die Aufgabenerstellung einen Konstruktor verwenden, müssen Sie seine Task.Start-Methode vor der Rückgabe aufrufen.If you use a constructor to create the task, you must call its Task.Start method before returning it.

Eine Methode, verwendet await (Await in Visual Basic) erfordert die async Schlüsselwort (Async in Visual Basic).A method that uses await (Await in Visual Basic) requires the async keyword (Async in Visual Basic). Wenn Sie solche Methode einer Komponente für Windows-Runtime verfügbar machen, wenden Sie die async Schlüsselwort an den Delegaten, die Sie zum Übergeben der ausführen Methode.If you expose such a method from a Windows Runtime component, apply the async keyword to the delegate that you pass to the Run method.

Für asynchrone Aktionen und Vorgänge, die weder die Abbruch- noch die Fortschrittsberichterstattung unterstützen, können Sie mit der Erweiterungsmethode WindowsRuntimeSystemExtensions.AsAsyncAction oder AsAsyncOperation<TResult> die Aufgabe in die entsprechende Schnittstelle umschließen.For asynchronous actions and operations that do not support cancellation or progress reporting, you can use the WindowsRuntimeSystemExtensions.AsAsyncAction or AsAsyncOperation<TResult> extension method to wrap the task in the appropriate interface. Beispielsweise implementiert der folgende Code eine asynchrone Methode mithilfe der "Task.Run"<TResult> Methode für den Aufgabenstart nutzt.For example, the following code implements an asynchronous method by using the Task.Run<TResult> method to start a task. Die AsAsyncOperation<TResult> Erweiterungsmethode gibt die Aufgabe als asynchronen Vorgang Windows-Runtime zurück.The AsAsyncOperation<TResult> extension method returns the task as a Windows Runtime asynchronous operation.

public static IAsyncOperation<IList<string>> DownloadAsStringsAsync(string id)
{
    return Task.Run<IList<string>>(async () =>
    {
        var data = await DownloadDataAsync(id);
        return ExtractStrings(data);
    }).AsAsyncOperation();
}
Public Shared Function DownloadAsStringsAsync(ByVal id As String) _
     As IAsyncOperation(Of IList(Of String))

    Return Task.Run(Of IList(Of String))(
        Async Function()
            Dim data = Await DownloadDataAsync(id)
            Return ExtractStrings(data)
        End Function).AsAsyncOperation()
End Function

Der folgende JavaScript-Code zeigt, wie die Methode mithilfe von aufgerufen werden konnte eine WinJS.Promise Objekt.The following JavaScript code shows how the method could be called by using a WinJS.Promise object. Die an die then-Methode übergebene Funktion wird ausgeführt, wenn der asynchrone Aufruf abgeschlossen ist.The function that is passed to the then method is executed when the asynchronous call completes. Der StringList-Parameter enthält die Liste der Zeichenfolgen, die von zurückgegeben wird das DownloadAsStringAsync -Methode, die Funktion übernimmt erforderliche Verarbeitung erforderlich ist.The stringList parameter contains the list of strings that is returned by the DownloadAsStringAsync method, and the function does whatever processing is required.

function asyncExample(id) {

    var result = SampleComponent.Example.downloadAsStringAsync(id).then(
        function (stringList) {
            // Place code that uses the returned list of strings here.
        });
}

Verwenden Sie für asynchrone Aktionen und Vorgänge, die Abbruch oder Fortschrittsberichterstattung unterstützt, die AsyncInfo Klasse, die eine begonnene Aufgabe zu generieren und zu verknüpfen, die die Abbruch- und fortschrittsberichterstattungs- die Funktionen des Tasks mit den Abbruch und Funktionen von der entsprechenden Windows-Runtime-Schnittstelle für statusberichterstellung.For asynchronous actions and operations that support cancellation or progress reporting, use the AsyncInfo class to generate a started task and to hook up the cancellation and progress reporting features of the task with the cancellation and progress reporting features of the appropriate Windows Runtime interface. Ein Beispiel, Abbruch- und Fortschrittsberichterstattung unterstützt, finden Sie unter Exemplarische Vorgehensweise: Erstellen einer einfachen Komponente in C# oder Visual Basic und Aufrufen dieser Komponente über JavaScript.For an example that supports both cancellation and progress reporting, see Walkthrough: Creating a simple component in C# or Visual Basic and calling it from JavaScript.

Beachten Sie, dass Sie die Methoden verwenden, können die AsyncInfo Klasse, auch wenn die asynchrone Methode unterstützen einen Abbruch oder Fortschrittsberichterstattung nicht.Note that you can use the methods of the AsyncInfo class even if your asynchronous method doesn't support cancellation or progress reporting. Wenn Sie eine Visual Basic-Lambda-Funktion verwenden oder ein C# anonyme Methode, geben Sie keine Parameter für das Token und IProgress<T> Schnittstelle.If you use a Visual Basic lambda function or a C# anonymous method, don't supply parameters for the token and IProgress<T> interface. Wenn Sie eine C#-Lambda-Funktion verwenden, geben Sie einen Tokenparameter an, aber ignorieren Sie ihn.If you use a C# lambda function, supply a token parameter but ignore it. Im vorherigen Beispiel verwendet die AsAsyncOperation<TResult> Methode sieht wie folgt aus, bei der Verwendung der AsyncInfo.Run<TResult>(Func< CancellationToken, Task<TResult>> )-Überladungsmethode.The previous example, which used the AsAsyncOperation<TResult> method, looks like this when you use the AsyncInfo.Run<TResult>(Func<CancellationToken, Task<TResult>>) method overload instead.

public static IAsyncOperation<IList<string>> DownloadAsStringsAsync(string id)
{
    return AsyncInfo.Run<IList<string>>(async (token) =>
    {
        var data = await DownloadDataAsync(id);
        return ExtractStrings(data);
    });
}
Public Shared Function DownloadAsStringsAsync(ByVal id As String) _
    As IAsyncOperation(Of IList(Of String))

    Return AsyncInfo.Run(Of IList(Of String))(
        Async Function()
            Dim data = Await DownloadDataAsync(id)
            Return ExtractStrings(data)
        End Function)
End Function

Wenn Sie eine asynchrone Methode, die optional die Abbruch- oder Fortschrittsberichterstattung unterstützt erstellen, erwägen Sie Überladungen, die keine Parameter für ein Abbruchtoken haben oder die IProgress<T> -Schnittstelle.If you create an asynchronous method that optionally supports cancellation or progress reporting, consider adding overloads that don't have parameters for a cancellation token or the IProgress<T> interface.

Auslösen von AusnahmenThrowing exceptions

Sie können jeden Ausnahmetyp auslösen, der in .NET für Windows-Apps enthalten ist.You can throw any exception type that is included in the .NET for Windows apps. Sie können keine eigenen öffentlichen Ausnahmetypen in einer Komponente für Windows-Runtime deklarieren, aber Sie können nicht öffentliche Typen deklarieren und auslösen.You can't declare your own public exception types in a Windows Runtime component, but you can declare and throw non-public types.

Wenn die Komponente die Ausnahme nicht behandelt, wird eine entsprechende Ausnahme im Code ausgelöst, der die Komponente aufgerufen hat.If your component doesn't handle the exception, a corresponding exception is raised in the code that called your component. Die Unterstützung der Windows-Runtime durch die aufrufende Sprache bestimmt, wie die Ausnahme dem Aufrufer dargestellt wird.The way the exception appears to the caller depends on the way the calling language supports the Windows Runtime.

  • In JavaScript erscheint die Ausnahme als Objekt, in dem die Ausnahmemeldung durch eine Stapelüberwachung ersetzt ist.In JavaScript, the exception appears as an object in which the exception message is replaced by a stack trace. Wenn Sie Ihre App in Visual Studio debuggen, wird der Originaltext der Meldung im Ausnahmedialogfeld des Debuggers unter „WinRT Information" angezeigt.When you debug your app in Visual Studio, you can see the original message text displayed in the debugger exception dialog box, identified as "WinRT Information". Sie können mit JavaScript-Code nicht auf den Originaltext der Meldung zugreifen.You can't access the original message text from JavaScript code.

    Tipp.Tip. Derzeit wird die stapelüberwachung enthält den verwalteten Ausnahmetyp, aber nicht empfohlen, analysieren die Ablaufverfolgung aus, um den Ausnahmetyp zu identifizieren. Currently, the stack trace contains the managed exception type, but we don't recommend parsing the trace to identify the exception type. Verwenden Sie stattdessen einen HRESULT-Wert, wie weiter unten in diesem Abschnitt beschrieben.Instead, use an HRESULT value as described later in this section.

  • In C++ erscheint die Ausnahme als Plattformausnahme.In C++, the exception appears as a platform exception. Wenn HResult-Eigenschaft der verwalteten Ausnahme dem HRESULT des einer bestimmten plattformausnahme zugeordnet werden kann, wird die spezielle Ausnahme verwendet. andernfalls ein Platform:: COMException Ausnahme ausgelöst.If the managed exception's HResult property can be mapped to the HRESULT of a specific platform exception, the specific exception is used; otherwise, a Platform::COMException exception is thrown. Der Meldungstext der verwalteten Ausnahme ist für C++-Code nicht verfügbar.The message text of the managed exception is not available to C++ code. Wenn eine bestimmte Plattformausnahme ausgelöst wurde, erscheint der Meldungstext für diesen Ausnahmetyp. Andernfalls wird kein Meldungstext ausgegeben.If a specific platform exception was thrown, the default message text for that exception type appears; otherwise, no message text appears. Siehe Ausnahmen (C++/CX).See Exceptions (C++/CX).

  • In C# oder Visual Basic ist die Ausnahme eine normale verwaltete Ausnahme.In C# or Visual Basic, the exception is a normal managed exception.

Wenn Sie in Ihrer Komponente eine Ausnahme auslösen, sollten Sie einen nicht öffentlichen Ausnahmetyp verwenden, dessen HResult-Eigenschaftswert speziell für Ihre Komponente gilt, damit die Ausnahme leichter von einem JavaScript- oder C++-Aufrufer verwaltet werden kann.When you throw an exception from your component, you can make it easier for a JavaScript or C++ caller to handle the exception by throwing a non-public exception type whose HResult property value is specific to your component. Das HRESULT ist verfügbar, um eine JavaScript-Aufrufer über das Ausnahmeobjekt Number-Eigenschaft und einer C++-Aufrufer über die COMException:: HRESULT Eigenschaft.The HRESULT is available to a JavaScript caller through the exception object's number property, and to a C++ caller through the COMException::HResult property.

Hinweis

Verwenden Sie einen negativen Wert für Ihre HRESULT.Use a negative value for your HRESULT. Ein positiver Wert wird als Erfolg interpretiert und im JavaScript- oder C++-Aufrufer wird keine Ausnahme ausgelöst.A positive value is interpreted as success, and no exception is thrown in the JavaScript or C++ caller.

Deklarieren und Auslösen von EreignissenDeclaring and raising events

Wenn Sie einen Typ deklarieren, um die Daten für das Ereignis aufzunehmen, leiten Sie diesen von „Object“ und nicht von „EventArgs“ ab, da „EventArgs“ kein Windows-Runtime-Typ ist.When you declare a type to hold the data for your event, derive from Object instead of from EventArgs, because EventArgs is not a Windows Runtime type. Verwenden Sie EventHandler<TEventArgs> als Typ des Ereignisses, und verwenden Sie den Ereignisargumenttyp als das allgemeine Typargument.Use EventHandler<TEventArgs> as the type of the event, and use your event argument type as the generic type argument. Lösen Sie das Ereignis genauso wie in einer .NET Framework-Anwendung aus.Raise the event just as you would in a .NET Framework application.

Wenn Ihre Komponente für Windows-Runtime von JavaScript oder C++ verwendet wird, folgt das Ereignis dem Windows-Runtime-Ereignismuster, das diese Sprachen erwarten.When your Windows Runtime component is used from JavaScript or C++, the event follows the Windows Runtime event pattern that those languages expect. Wenn Sie die Komponente in C# oder Visual Basic verwenden, erscheint das Ereignis als normales .NET Framework-Ereignis.When you use the component from C# or Visual Basic, the event appears as an ordinary .NET Framework event. Ein Beispiel finden Sie Exemplarische Vorgehensweise: Erstellen einer einfachen Komponente in C# oder Visual Basic und Aufrufen dieser Komponente über JavaScript.An example is provided in Walkthrough: Creating a simple component in C# or Visual Basic and calling it from JavaScript.

Wenn Sie benutzerdefinierte Ereignisaccessoren implementieren (in Visual Basic ein Ereignis mit dem Schlüsselwort Custom deklarieren), müssen Sie in der Implementierung das Windows-Runtime-Ereignismuster verwenden.If you implement custom event accessors (declare an event with the Custom keyword, in Visual Basic), you must follow the Windows Runtime event pattern in your implementation. Siehe Benutzerdefinierte Ereignisse und Ereignisaccessoren in Komponenten für Windows-Runtime.See Custom events and event accessors in Windows Runtime Components. Beachten Sie, dass das Ereignis auch dann als einfaches .NET Framework-Ereignis erscheint, wenn Sie C#- oder Visual Basic-Code verwenden.Note that when you handle the event from C# or Visual Basic code, it still appears to be an ordinary .NET Framework event.

Nächste SchritteNext steps

Nachdem Sie eine Komponente für Windows-Runtime für eigene Zwecke erstellt haben, stellen Sie möglicherweise fest, dass die Funktionen, die diese kapselt, für andere Entwickler nützlich sind.After you’ve created a Windows Runtime component for your own use, you may find that the functionality it encapsulates is useful to other developers. Sie haben zwei Optionen, um eine Komponente für die Verteilung an andere Entwickler zu packen.You have two options for packaging a component for distribution to other developers. Siehe Verteilen einer verwalteten Komponente für Windows-Runtime.See Distributing a managed Windows Runtime component.

Weitere Informationen zu Visual Basic- und C#-Sprachfunktionen und zur .NET Framework-Unterstützung für die Windows-Runtime finden Sie unter Visual Basic- und C#-Programmiersprachenreferenz.For more information about Visual Basic and C# language features, and .NET Framework support for the Windows Runtime, see Visual Basic and C# language reference.