Übergeben von Arrays an eine Komponente für Windows-RuntimePassing arrays to a Windows Runtime Component

Parameter in der UWP (Universal Windows-Plattform) sind entweder für die Eingabe oder für die Ausgabe, nie für beides, vorgesehen.In the Windows Universal Platform (UWP), parameters are either for input or for output, never both. Das bedeutet, dass der Inhalt eines Arrays, der an eine Methode übergeben wird, wie auch das Array selbst für die Eingabe oder für die Ausgabe vorgesehen sind.This means that the contents of an array that is passed to a method, as well as the array itself, are either for input or for output. Wenn der Inhalt des Arrays für die Eingabe vorgesehen ist, liest die Methode aus dem Array, aber schreibt nicht in das Array.If the contents of the array are for input, the method reads from the array but doesn't write to it. Wenn der Inhalt des Arrays für die Ausgabe vorgesehen ist, schreibt die Methode in das Array, aber liest nicht in daraus.If the contents of the array are for output, the method writes to the array but doesn't read from it. Dies stellt ein Problem für Array Parameter dar, da Arrays in .net Verweis Typen sind und der Inhalt eines Arrays änderbar ist, auch wenn der Array Verweis als Wert (ByVal in Visual Basic) übermittelt wird.This presents a problem for array parameters, because arrays in .NET are reference types, and the contents of an array are mutable even when the array reference is passed by value (ByVal in Visual Basic). Für das Windows-Runtime-Metadatenexport-Tool (Winmdexp.exe) müssen Sie die beabsichtigte Verwendung des Arrays angeben, falls dies nicht eindeutig aus dem Kontext ersichtlich ist. Fügen Sie dem Parameter zu diesem Zweck das Attribut „ReadOnlyArrayAttribute” oder „WriteOnlyArrayAttribute” hinzu.The Windows Runtime Metadata Export Tool (Winmdexp.exe) requires you to specify the intended usage of the array if it is not clear from context, by applying the ReadOnlyArrayAttribute attribute or the WriteOnlyArrayAttribute attribute to the parameter. Die Array-Nutzung wird wie folgt bestimmt:Array usage is determined as follows:

  • Für den Rückgabewert oder einen Ausgabeparameter (einen ByRef-Parameter mit dem OutAttribute-Attribut in Visual Basic) ist das Array immer nur für die Ausgabe vorgesehen.For the return value or for an out parameter (a ByRef parameter with the OutAttribute attribute in Visual Basic) the array is always for output only. Geben Sie das Attribut „ReadOnlyArrayAttribute” nicht an.Do not apply the ReadOnlyArrayAttribute attribute. Das „WriteOnlyArrayAttribute”-Attribut ist für Ausgabeparameter zulässig, aber redundant.The WriteOnlyArrayAttribute attribute is allowed on output parameters, but it's redundant.

    Vorsicht    Der Visual Basic-Compiler erzwingt keine reinen Ausgabe Regeln.Caution  The Visual Basic compiler does not enforce output-only rules. Sie sollten nie aus Ausgabeparametern lesen, sie könnten Nothing enthalten.You should never read from an output parameter; it may contain Nothing. Weisen Sie immer ein neues Array zu.Always assign a new array.  

  • Parameter mit dem Modifizierer ref (ByRef in Visual Basic) sind nicht zulässig.Parameters that have the ref modifier (ByRef in Visual Basic) are not allowed. Winmdexp.exe erzeugt einen Fehler.Winmdexp.exe generates an error.

  • Für einen Parameter, der als Wert übergeben wird, müssen Sie angeben, ob der Arrayinhalt für die Eingabe oder die Ausgabe vorgesehen ist, indem Sie entweder das Attribut ReadOnlyArrayAttribute oder das Attribut WriteOnlyArrayAttribute angeben.For a parameter that is passed by value, you must specify whether the array contents are for input or output by applying either the ReadOnlyArrayAttribute attribute or the WriteOnlyArrayAttribute attribute. Die Angabe von beiden Attributen ist ein Fehler.Specifying both attributes is an error.

Wenn eine Methode ein Array für die Eingabe akzeptieren soll, ändern Sie den Arrayinhalt, und geben Sie das Array an den Aufrufer zurück; verwenden Sie einen schreibgeschützten Parameter für die Eingabe und einen lesegeschützten Parameter (oder den Rückgabewert) für die Ausgabe.If a method must accept an array for input, modify the array contents, and return the array to the caller, use a read-only parameter for the input and a write-only parameter (or the return value) for the output. Der folgende Code zeigt eine Möglichkeit, dieses Muster zu implementieren:The following code shows one way to implement this pattern:

public int[] ChangeArray([ReadOnlyArray()] int[] input)
{
    int[] output = input.Clone();
    // Manipulate the copy.
    //   ...
    return output;
}
Public Function ChangeArray(<ReadOnlyArray> input() As Integer) As Integer()
    Dim output() As Integer = input.Clone()
    ' Manipulate the copy.
    '   ...
    Return output
End Function

Wir empfehlen, dass Sie sofort eine Kopie des Eingabearrays anlegen und die Kopie bearbeiten.We recommend that you make a copy of the input array immediately, and manipulate the copy. Dadurch wird sichergestellt, dass die-Methode gleich verhält, unabhängig davon, ob die-Komponente von .NET-Code aufgerufen wird.This helps ensure that the method behaves the same whether or not your component is called by .NET code.

Verwenden von Komponenten aus verwaltetem und nicht verwaltetem CodeUsing components from managed and unmanaged code

Parameter mit dem Attribut „ReadOnlyArrayAttribute” oder „WriteOnlyArrayAttribute” verhalten sich anders, je nachdem, ob der Aufrufer in systemeigenem oder verwaltetem Code geschrieben wurde.Parameters that have the ReadOnlyArrayAttribute attribute or the WriteOnlyArrayAttribute attribute behave differently depending on whether the caller is written in native code or managed code. Wenn der Aufrufer systemeigener Code (JavaScript oder Visual C++-Komponentenerweiterungen) ist, wird der Arrayinhalt wie folgt behandelt:If the caller is native code (JavaScript or Visual C++ component extensions), the array contents are treated as follows:

  • ReadOnlyArrayAttribute: Das Array wird kopiert, wenn der Aufruf die Grenze der binären Anwendungsschnittstelle (ABI) überschreitet.ReadOnlyArrayAttribute: The array is copied when the call crosses the application binary interface (ABI) boundary. Elemente werden bei Bedarf konvertiert.Elements are converted if necessary. Von der Methode fälschlicherweise an einem nur zur Eingabe bestimmten Array vorgenommene Änderungen sind daher für den Aufrufer nicht sichtbar.Therefore, any accidental changes the method makes to an input-only array are not visible to the caller.
  • WriteOnlyArrayAttribute: Die aufgerufene Methode kann keine Annahmen über den Inhalt des ursprünglichen Arrays treffen.WriteOnlyArrayAttribute: The called method can't make any assumptions about the contents of the original array. Beispielsweise ist das Array, das die Methode empfängt, möglicherweise nicht oder mit Standardwerten initialisiert.For example, the array the method receives might not be initialized, or might contain default values. Von der Methode wird das Festlegen der Werte aller Elemente im Array erwartet.The method is expected to set the values of all the elements in the array.

Wenn der Aufrufer verwalteter Code ist, steht das ursprüngliche Array der aufgerufenen Methode zur Verfügung, wie es bei jedem Methodenaufruf in .net der Fall wäre.If the caller is managed code, the original array is available to the called method, as it would be in any method call in .NET. Array Inhalte sind im .NET-Code änderbar, sodass alle Änderungen, die die Methode am Array vornimmt, für den Aufrufer sichtbar sind.Array contents are mutable in .NET code, so any changes the method makes to the array are visible to the caller. Dies ist wichtig, da es Komponententests für eine Komponente für Windows-Runtime betrifft.This is important to remember because it affects unit tests written for a Windows Runtime Component. Wenn die Tests in verwaltetem Code geschrieben werden, scheint der Inhalt eines Arrays während des Testens veränderlich zu sein.If the tests are written in managed code, the contents of an array will appear to be mutable during testing.