IAsyncActionWithProgress<TProgress> Interface

Définition

Espace de noms:

Windows.Foundation

Représente une action asynchrone qui peut signaler les mises à jour de progression aux appelants. Il s’agit du type de retour pour toutes les méthodes asynchrones Windows Runtime qui n’ont pas d’objet de résultat, mais qui signalent la progression aux écouteurs de rappel.

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

Paramètres de type

TProgress

Attributs

ContractVersionAttribute GuidAttribute

Implémente

IAsyncInfo

Configuration requise pour Windows

Famille d’appareils	Windows 10 (introduit dans 10.0.10240.0)
API contract	Windows.Foundation.FoundationContract (introduit dans v1.0)

Exemples

Pour obtenir un exemple de code C++/WinRT illustrant la façon de gérer l’événement Progress , consultez Types délégués pour les actions et opérations asynchrones.

Remarques

IAsyncActionWithProgress TProgress<est le type de retour pour toutes les méthodes asynchrones> Windows Runtime qui ne communiquent pas d’objet de résultat, mais qui permettent à une application de case activée la progression de l’action. Il n’y a pas autant de méthodes qui utilisent IAsyncAction. IAsyncAction Les API ne rapportent pas de progression et n’ont pas de résultat.

Lorsque vous utilisez des méthodes qui retournent IAsyncActionWithProgress TProgress<> dans le code de votre application, vous n’accédez généralement pas directement à la valeur de retour IAsyncAction. En effet, vous utilisez presque toujours la syntaxe awaitable propre au langage. Dans ce cas, la valeur de retour apparente de la méthode est void. Pour plus d’informations, consultez Programmation asynchrone ou l’un des guides spécifiques au langage pour Windows Runtime la programmation asynchrone (Appeler des API asynchrones en C# ou Visual Basic, C++, JavaScript).

Il n’est pas courant d’utiliser IAsyncActionWithProgress<> directement même si vous n’utilisez pas de syntaxe d’attente spécifique au langage. Chacun des langages a des points d’extension qui sont généralement plus faciles à utiliser que l’interface Windows Runtime. JavaScript a WinJS.Promise, et la syntaxe then/done with onProgress . .NET possède les méthodes d’extension AsTask. Une fois que le TProgress IAsyncActionWithProgress<> est converti en tâche, il est plus facile d’annuler, d’obtenir une notification à l’achèvement, d’utiliser IProgress<T>, etc. Pour C++/CX, vous pouvez encapsuler les appels à l’aide du runtime d’accès concurrentiel (et utiliser create_task). En d’autres termes, IAsyncActionWithProgress TProgress<peut être considéré comme une infrastructure au niveau de l’exécution, que chacun des langages> utilise comme infrastructure pour prendre en charge la syntaxe attendue ou les modèles de programmation asynchrone à sa manière.

Plus précisément, si vous souhaitez gérer la progression dans le code .NET, utilisez la signature AsTask qui, dans l’utilisation d’une extension, a un seul paramètre de référence IProgress . (Dans cette utilisation, l’unité de progression est déjà contrainte et correspond à la méthode IAsyncActionWithProgress que vous utilisez.) Fournissez un objet qui implémente IProgress, et votre implémentation de méthode Report est appelée chaque fois que la méthode Windows Runtime signale une notification de progression.

Pour surveiller la progression de l’action (si vous n’utilisez pas les techniques spécifiques au langage décrites ci-dessus), définissez la propriété Progress , en lui fournissant le nom d’une méthode qui implémente le délégué AsyncActionProgressHandler<TProgress> .

Fonctions d’extension C++/WinRT

Notes

Des fonctions d’extension existent sur les types de projection C++/WinRT pour certaines API Windows Runtime. Par exemple, winrt ::Windows ::Foundation ::IAsyncAction est le type de projection C++/WinRT pour IAsyncAction. Les fonctions d’extension ne font pas partie de la surface d’interface binaire d’application (ABI) des types Windows Runtime réels. Elles ne sont donc pas répertoriées en tant que membres des API Windows Runtime. Mais vous pouvez les appeler à partir de n’importe quel projet C++/WinRT. Consultez Fonctions C++/WinRT qui étendent Windows Runtime API.

void get() const;

Attend de façon synchrone que l’action se termine. Lève une exception correspondante si l’action est annulée ou entre dans un état d’erreur. Vous ne devez pas l’appeler à partir d’un appartement à thread unique. Pour plus d’informations et pour obtenir des exemples de code montrant comment appeler get, consultez Écrire une coroutine.

AsyncStatus wait_for(TimeSpan const& timeout) const;

Attend de manière synchrone la fin de l’action ou le délai d’expiration spécifié. Retourne l’état de IAsyncActionWithProgress ou AsyncStatus ::Started si le délai d’expiration s’est écoulé. Si l’action n’a pas expiré, appelez GetResults pour obtenir les résultats de l’action. Pour plus d’informations et pour obtenir des exemples de code montrant comment appeler wait_for, consultez Délais d’expiration asynchrones simplifiés.

Héritage de l'interface

IAsyncActionWithProgress<TProgress hérite d’IAsyncInfo>. Les types qui implémentent IAsyncActionWithProgress TProgress<> implémentent également les membres d’interface d’IAsyncInfo :

• Cancel , méthode
• Close , méthode
• Propriété ErrorCode
• Id , propriété
• Propriété Status

Remarques aux implémenteurs

Comme pour appeler les méthodes existantes, il existe des méthodes spécifiques au langage pour définir des méthodes asynchrones qui n’utilisent pas directement IAsyncActionWithProgress<TProgress> . Si vous écrivez du code à l’aide de .NET, votre méthode peut retourner une tâche. Pour C++/CX, vous pouvez utiliser le runtime d’accès concurrentiel. Toutefois, si vous définissez un composant, vous pouvez utiliser tâche de/tâche en interne, mais vous devez retourner l’une des interfaces Windows Runtime pour vos méthodes publiques. Les types de prise en charge asynchrone spécifiques au langage (et de nombreux autres types spécifiques à la langue que vous pouvez utiliser conventionnellement dans le code) ne peuvent pas être utilisés pour la surface d’exposition publique d’un composant Windows Runtime.

Propriétés

Completed	Obtient ou définit le délégué appelé une fois l’action terminée.
ErrorCode	Obtient une chaîne qui décrit une condition d’erreur de l’opération asynchrone. (Hérité de IAsyncInfo)
Id	Obtient le handle de l’opération asynchrone. (Hérité de IAsyncInfo)
Progress	Obtient ou définit la méthode de rappel qui reçoit une notification de progression.
Status	Obtient une valeur qui indique le status de l’opération asynchrone. (Hérité de IAsyncInfo)

Méthodes

Cancel()	Annule l’opération asynchrone. (Hérité de IAsyncInfo)
Close()	Ferme l’opération asynchrone. (Hérité de IAsyncInfo)
GetResults()	Retourne les résultats de l’action.

Voir aussi

• IAsyncInfo
• IAsyncAction