IAsyncOperationWithProgress<TResult,TProgress> Schnittstelle

Definition

Stellt einen asynchronen Vorgang dar, der Statusaktualisierungen an Aufrufer melden kann. Dies ist der Rückgabetyp für viele Windows-Runtime asynchronen Methoden, die Ergebnisse aufweisen und auch den Fortschritt melden.

public interface class IAsyncOperationWithProgress : IAsyncInfo
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.FoundationContract, 65536)]
/// [Windows.Foundation.Metadata.Guid(3050321623, 58007, 18831, 186, 96, 2, 137, 231, 110, 35, 221)]
template <typename TResult, typename TProgress>
struct IAsyncOperationWithProgress : IAsyncInfo
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.FoundationContract), 65536)]
[Windows.Foundation.Metadata.Guid(3050321623, 58007, 18831, 186, 96, 2, 137, 231, 110, 35, 221)]
public interface IAsyncOperationWithProgress<TResult,TProgress> : IAsyncInfo
Public Interface IAsyncOperationWithProgress(Of TResult, TProgress)
Implements IAsyncInfo

Typparameter

TResult
TProgress
Abgeleitet
Attribute
Implementiert

Windows-Anforderungen

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

Hinweise

IAsyncOperationWithProgress<TResult,TProgress> ist der Rückgabetyp für viele Windows-Runtime asynchronen Methoden, die nach Abschluss ein Ergebnis haben, und unterstützt auch Benachrichtigungen, die den Fortschritt melden (die Aufrufer abonnieren können, indem sie einen Rückruf für Fortschritt zuweisen). Dies sind etwa 100 verschiedene Windows-Runtime-APIs. APIs, die keinen Fortschritt melden (aber ein Ergebnis haben), verwenden eine andere Schnittstelle, IAsyncOperation<TResult>.

Wenn Sie Methoden verwenden, die IAsyncOperationWithProgress<TResult,TProgress> (mit einer TResult-spezifischen Einschränkung) in Ihrem App-Code zurückgeben, greifen Sie normalerweise nicht direkt auf den IAsyncOperationWithProgress-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 der Typ, der als TResult-Parameter angegeben wird. 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, IAsyncOperationWithProgress<TResult,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 Syntax "then/done" . .NET verfügt über die AsTask-Erweiterungsmethode, und sobald IAsyncOperationWithProgress<TResult, TProgress> in ein Task-TResult<> konvertiert wurde, ist es einfacher, das Ergebnis zu erhalten, abzubrechen, Benachrichtigungen bei Abschluss abzurufen usw. Für C++/CX können Sie die Aufrufe mit der Concurrency Runtime umschließen (und create_task verwenden). Mit anderen Worten, IAsyncOperationWithProgress<TResult, 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. (In dieser Verwendung ist die Fortschrittseinheit bereits eingeschränkt und entspricht der IAsyncOperationWithProgress-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 AsyncOperationProgressHandler<TResult,TProgress> Delegate 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.

TResult get() const;

Wartet synchron, bis der Vorgang abgeschlossen ist, und gibt den abgeschlossenen Wert zurück. Löst eine entsprechende Ausnahme aus, wenn der Vorgang 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 der Vorgang abgeschlossen ist oder auf das angegebene Timeout. Gibt den Zustand von IAsyncOperationWithProgress oder AsyncStatus::Started zurück, wenn das Timeout abgelaufen ist. Wenn für die Aktion kein Timeout auftritt, rufen Sie GetResults auf, um die Ergebnisse des Vorgangs abzurufen. Weitere Informationen und Codebeispiele zum Aufrufen wait_for finden Sie unter Asynchrone Timeouts leicht gemacht.

Schnittstellenvererbung

IAsyncOperationWithProgress<TResult,TProgress> erbt IAsyncInfo. Typen, die IAsyncOperationWithProgress<TResult,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 IAsyncOperationWithProgress<TResult,TProgress> nicht direkt verwenden. Wenn Sie Code mit .NET schreiben, kann Ihre Methode ein Task-TResult<> 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 der Vorgang 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 Methode ab, die Statusbenachrichtigungen verarbeitet, oder legt sie 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 des Vorgangs zurück.

Gilt für:

Weitere Informationen