IAsyncActionWithProgress<TProgress> Schnittstelle

  • Referenz

Definition

Namespace:
Windows.Foundation
Bearbeiten

Stellt eine asynchrone Aktion dar, die Statusaktualisierungen an Aufrufer melden kann. Dies ist der Rückgabetyp für alle Windows-Runtime asynchronen Methoden, die kein Ergebnisobjekt haben, aber den Status an Rückruflistener melden.

public interface class IAsyncActionWithProgress : IAsyncInfo
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.FoundationContract, 65536)]
/// [Windows.Foundation.Metadata.Guid(527282776, 59395, 18593, 149, 70, 235, 115, 83, 57, 136, 132)]
template <typename TProgress>
struct IAsyncActionWithProgress : IAsyncInfo
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.FoundationContract), 65536)]
[Windows.Foundation.Metadata.Guid(527282776, 59395, 18593, 149, 70, 235, 115, 83, 57, 136, 132)]
public interface IAsyncActionWithProgress<TProgress> : IAsyncInfo
Public Interface IAsyncActionWithProgress(Of TProgress)
Implements IAsyncInfo

Typparameter

TProgress
Attribute
ContractVersionAttribute GuidAttribute
Implementiert
IAsyncInfo

Windows-Anforderungen

Gerätefamilie
Windows 10 (eingeführt in 10.0.10240.0)
API contract
Windows.Foundation.FoundationContract (eingeführt in v1.0)

Beispiele

Beispiel : C++/WinRT-Code , der veranschaulicht, wie das Progress-Ereignis behandelt wird, finden Sie unter Delegieren von Typen für asynchrone Aktionen und Vorgänge.

Hinweise

IAsyncActionWithProgress<TProgress> ist der Rückgabetyp für alle Windows-Runtime asynchronen Methoden, die kein Ergebnisobjekt kommunizieren, aber eine App aktivieren, um den Fortschritt der Aktion zu überprüfen. Es gibt nicht annähernd so viele wie Methoden, die IAsyncAction verwenden. IAsyncAction APIs melden keinen Fortschritt und haben kein Ergebnis.

Wenn Sie Methoden verwenden, die IAsyncActionWithProgress<TProgress> in Ihrem App-Code zurückgeben, greifen Sie in der Regel nicht direkt auf den IAsyncAction-Rückgabewert zu. Das liegt daran, dass Sie fast immer die sprachspezifische, erwartbare Syntax verwenden. In diesem Fall ist der scheinbare Rückgabewert der Methode void. Weitere Informationen finden Sie unter Asynchrone Programmierung oder eine der sprachspezifischen Anleitungen zum Windows-Runtime asynchroner Programmierung (Aufrufen asynchroner APIs in C# oder Visual Basic, C++, JavaScript).

Es ist nicht üblich, IAsyncActionWithProgress<TProgress> direkt zu verwenden, auch wenn Sie keine sprachspezifische, erwartbare Syntax verwenden. Jede der Sprachen verfügt über Erweiterungspunkte, die im Allgemeinen einfacher zu verwenden sind als die Windows-Runtime-Schnittstelle. JavaScript verfügt über WinJS.Promise und die dann/fertig mit onProgress-Syntax . .NET verfügt über die AsTask-Erweiterungsmethoden , und sobald IAsyncActionWithProgress<TProgress> in einen Task konvertiert wurde, ist es einfacher, abzubrechen, Benachrichtigungen bei abschluss zu erhalten, IProgress<T> zu verwenden usw. Für C++/CX können Sie die Aufrufe mit der Concurrency Runtime umschließen (und create_task verwenden). Mit anderen Worten, IAsyncActionWithProgress<TProgress> kann als Infrastruktur auf Laufzeitebene betrachtet werden, die jede der Sprachen als Framework verwendet, um die erwartbare Syntax oder asynchrone Programmiermodelle auf ihre eigene Weise zu unterstützen.

Wenn Sie den Fortschritt in .NET-Code behandeln möchten, verwenden Sie die AsTask-Signatur , die in einer Erweiterungsverwendung über einen einzelnen IProgress-Verweisparameter verfügt. (Bei dieser Verwendung ist die Fortschrittseinheit bereits eingeschränkt und entspricht der IAsyncActionWithProgress-Methode, die Sie verwenden.) Geben Sie ein Objekt an, das IProgress implementiert, und ihre Report-Methodenimplementierung wird jedes Mal aufgerufen, wenn die Windows-Runtime-Methode eine Statusbenachrichtigung meldet.

Um den Fortschritt der Aktion zu überwachen (wenn nicht die oben beschriebenen sprachspezifischen Techniken verwendet werden), legen Sie die Progress-Eigenschaft fest, und geben Sie ihr den Namen einer Methode an, die den AsyncActionProgressHandler-TProgress-Delegat<> implementiert.

C++/WinRT-Erweiterungsfunktionen

Hinweis

Erweiterungsfunktionen sind für die C++/WinRT-Projektionstypen für bestimmte Windows-Runtime-APIs vorhanden. Winrt::Windows::Foundation::IAsyncAction ist beispielsweise der C++/WinRT-Projektionstyp für IAsyncAction. Die Erweiterungsfunktionen sind nicht Teil der ABI-Oberfläche (Application Binary Interface) der tatsächlichen Windows-Runtime-Typen, daher werden sie nicht als Member der Windows-Runtime-APIs aufgeführt. Sie können sie jedoch in jedem C++/WinRT-Projekt aufrufen. Weitere Informationen finden Sie unter C++/WinRT-Funktionen, die Windows-Runtime-APIs erweitern.

void get() const;

Wartet synchron, bis die Aktion abgeschlossen ist. Löst eine entsprechende Ausnahme aus, wenn die Aktion abgebrochen wird oder in einen Fehlerzustand wechselt. Sie dürfen es nicht aus einem Singlethread-Apartment aufrufen. Weitere Informationen und Codebeispiele zum Aufrufen von get finden Sie unter Schreiben einer Coroutine.

AsyncStatus wait_for(TimeSpan const& timeout) const;

Wartet synchron, bis die Aktion abgeschlossen ist oder auf das angegebene Timeout. Gibt den Zustand von IAsyncActionWithProgress oder AsyncStatus::Started zurück, wenn das Timeout abgelaufen ist. Wenn für die Aktion kein Timeout ausgeführt wurde, rufen Sie GetResults auf, um die Ergebnisse der Aktion abzurufen. Weitere Informationen und Codebeispiele zum Aufrufen wait_for finden Sie unter Asynchrone Timeouts leicht gemacht.

Schnittstellenvererbung

IAsyncActionWithProgress<TProgress> erbt IAsyncInfo. Typen, die IAsyncActionWithProgress<TProgress> implementieren, implementieren auch die Schnittstellenmember von IAsyncInfo:

Hinweise für Implementierer

Wie beim Aufrufen vorhandener Methoden gibt es sprachspezifische Möglichkeiten, asynchrone Methoden zu definieren, die IAsyncActionWithProgress<TProgress> nicht direkt verwenden. Wenn Sie Code mithilfe von .NET schreiben, kann Ihre Methode einen Task zurückgeben. Für C++/CX können Sie die Concurrency Runtime verwenden. Wenn Sie jedoch eine Komponente definieren, können Sie task/intern verwenden, aber Sie müssen eine der Windows-Runtime Schnittstellen für Ihre öffentlichen Methoden zurückgeben. Die sprachspezifischen asynchronen Unterstützungstypen (und viele andere sprachspezifische Typen, die Sie normalerweise im Code verwenden) können nicht für den öffentlichen Oberflächenbereich einer Windows-Runtime Komponente verwendet werden.

Eigenschaften

Completed

Ruft den Delegat ab, der aufgerufen wird, wenn die Aktion abgeschlossen ist, oder legt diesen fest.
ErrorCode

Ruft eine Zeichenfolge ab, die eine Fehlerbedingung des asynchronen Vorgangs beschreibt.

(Geerbt von IAsyncInfo)
Id

Ruft das Handle des asynchronen Vorgangs ab.

(Geerbt von IAsyncInfo)
Progress

Ruft die Rückrufmethode ab, die Statusbenachrichtigungen empfängt, oder legt diese fest.
Status

Ruft einen Wert ab, der die status des asynchronen Vorgangs angibt.

(Geerbt von IAsyncInfo)

Methoden

Cancel()

Bricht den asynchronen Vorgang ab.

(Geerbt von IAsyncInfo)
Close()

Schließt den asynchronen Vorgang.

(Geerbt von IAsyncInfo)
GetResults()

Gibt die Ergebnisse der Aktion zurück.

Gilt für:

Weitere Informationen