Modèle asynchrone basé sur les tâches (TAP)Task-based asynchronous pattern (TAP)

Le modèle asynchrone basé sur des tâches (TAP) est basé sur les types System.Threading.Tasks.Task et System.Threading.Tasks.Task<TResult> de l’espace de noms System.Threading.Tasks, qui sont utilisés pour représenter les opérations asynchrones arbitraires.The Task-based Asynchronous Pattern (TAP) is based on the System.Threading.Tasks.Task and System.Threading.Tasks.Task<TResult> types in the System.Threading.Tasks namespace, which are used to represent arbitrary asynchronous operations. Le TAP est le modèle de conception asynchrone recommandé pour le nouveau développement.TAP is the recommended asynchronous design pattern for new development.

Noms, paramètres et types de retourNaming, parameters, and return types

Le TAP utilise une méthode unique pour représenter le début et la fin d'une opération asynchrone.TAP uses a single method to represent the initiation and completion of an asynchronous operation. Ce fonctionnement le différencie du modèle de programmation asynchrone (APM ou IAsyncResult) et du modèle asynchrone basé sur les événements (EAP).This contrasts with both the Asynchronous Programming Model (APM or IAsyncResult) pattern and the Event-based Asynchronous Pattern (EAP). Les méthodes Begin et End sont nécessaires pour le modèle APM.APM requires Begin and End methods. Le modèle EAP a besoin d’une méthode comportant le suffixe Async, ainsi que d’un ou plusieurs événements, de types de délégués de gestionnaire d’événements et de types dérivés de EventArg.EAP requires a method that has the Async suffix and also requires one or more events, event handler delegate types, and EventArg-derived types. Les méthodes asynchrones du modèle TAP qui retournent des types compatibles await, comme Task, Task<TResult>, ValueTask et ValueTask<TResult>, comprennent le suffixe Async après le nom de l’opération.Asynchronous methods in TAP include the Async suffix after the operation name for methods that return awaitable types, such as Task, Task<TResult>, ValueTask, and ValueTask<TResult>. Par exemple, une opération Get asynchrone qui retourne une valeur Task<String> peut porter le nom GetAsync.For example, an asynchronous Get operation that returns a Task<String> can be named GetAsync. Si vous ajoutez une méthode TAP à une classe qui contient déjà un nom de méthode EAP avec le suffixe Async, utilisez plutôt le suffixe TaskAsync.If you're adding a TAP method to a class that already contains an EAP method name with the Async suffix, use the suffix TaskAsync instead. Par exemple, si la classe possède déjà une méthode GetAsync, utilisez le nom GetTaskAsync.For example, if the class already has a GetAsync method, use the name GetTaskAsync. Les méthodes qui lancent une opération asynchrone, mais ne retournent pas de type compatible await, doivent porter un nom qui commence par Begin, Start ou un autre verbe suggérant qu’elles ne retournent ni ne lèvent le résultat de l’opération.If a method starts an asynchronous operation but does not return an awaitable type, its name should start with Begin, Start, or some other verb to suggest that this method does not return or throw the result of the operation.  

Une méthode TAP retourne une System.Threading.Tasks.Task ou une System.Threading.Tasks.Task<TResult>, selon que la méthode synchrone correspondante retourne void ou un type TResult.A TAP method returns either a System.Threading.Tasks.Task or a System.Threading.Tasks.Task<TResult>, based on whether the corresponding synchronous method returns void or a type TResult.

Les paramètres d’une méthode TAP doivent correspondre à ceux de son équivalent synchrone, dans le même ordre.The parameters of a TAP method should match the parameters of its synchronous counterpart and should be provided in the same order. Toutefois, les paramètres out et ref sont exempts de cette règle et doivent être évités entièrement.However, out and ref parameters are exempt from this rule and should be avoided entirely. Les données qui auraient dû être retournées par un paramètre out ou ref doivent être retournées comme faisant partie du TResult retourné par Task<TResult>, et doivent utiliser un tuple ou une structure de données personnalisée pour s’adapter à plusieurs valeurs.Any data that would have been returned through an out or ref parameter should instead be returned as part of the TResult returned by Task<TResult>, and should use a tuple or a custom data structure to accommodate multiple values. Il peut rester intéressant d’ajouter un paramètre CancellationToken même si l’équivalent synchrone de la méthode TAP n’en offre pas.You should also consider adding a CancellationToken parameter even if the TAP method's synchronous counterpart does not offer one.

Les méthodes qui sont consacrées exclusivement à la création, la manipulation ou la combinaison de tâches (où l’intention asynchrone de la méthode est clairement indiquée dans le nom de la méthode ou dans le nom du type auquel la méthode appartient) n’ont pas besoin de suivre ce modèle d’affectation de noms. Ces types de méthodes sont souvent appelés combinateurs.Methods that are devoted exclusively to the creation, manipulation, or combination of tasks (where the asynchronous intent of the method is clear in the method name or in the name of the type to which the method belongs) need not follow this naming pattern; such methods are often referred to as combinators. Les exemples de combinateurs incluent WhenAll et WhenAny, et sont traités dans la section Utilisation des combinateurs intégrés basés sur des tâches de l'article Utilisation du modèle asynchrone basé sur les tâches.Examples of combinators include WhenAll and WhenAny, and are discussed in the Using the Built-in Task-based Combinators section of the article Consuming the Task-based Asynchronous Pattern.

Pour obtenir des exemples de la façon dont la syntaxe du TAP diffère de celle utilisée dans les modèles de programmation asynchrones hérités tels que le modèle de programmation asynchrone (APM) et le modèle asynchrone basé sur des événements (EAP), consultez Modèles de programmation asynchrone.For examples of how the TAP syntax differs from the syntax used in legacy asynchronous programming patterns such as the Asynchronous Programming Model (APM) and the Event-based Asynchronous Pattern (EAP), see Asynchronous Programming Patterns.

Lancer une opération asynchroneInitiating an asynchronous operation

Une méthode asynchrone basée sur le TAP peut effectuer une petite quantité de travail de façon synchrone, comme valider les arguments et initialiser l’opération asynchrone, avant de retourner la tâche résultante.An asynchronous method that is based on TAP can do a small amount of work synchronously, such as validating arguments and initiating the asynchronous operation, before it returns the resulting task. Le travail synchrone doit être conservé au minimum afin que la méthode asynchrone puisse retourner rapidement.Synchronous work should be kept to the minimum so the asynchronous method can return quickly. Les raisons d'un retour rapide sont les suivantes :Reasons for a quick return include the following:

  • Les méthodes asynchrones peuvent être appelées par des threads d'interface utilisateur, et tout travail synchrone de longue durée peut nuire à la réactivité de l'application.Asynchronous methods may be invoked from user interface (UI) threads, and any long-running synchronous work could harm the responsiveness of the application.

  • Plusieurs méthodes asynchrones peuvent être lancées simultanément.Multiple asynchronous methods may be launched concurrently. Par conséquent, tout travail de longue durée dans la partie synchrone d'une méthode asynchrone risque de retarder l'initiation d'autres opérations asynchrones, réduisant ainsi les avantages offerts par l'accès concurrentiel.Therefore, any long-running work in the synchronous portion of an asynchronous method could delay the initiation of other asynchronous operations, thereby decreasing the benefits of concurrency.

Dans certains cas, la quantité de travail nécessaire pour terminer l'opération est inférieure à la quantité de travail nécessaire pour lancer l'opération de façon asynchrone.In some cases, the amount of work required to complete the operation is less than the amount of work required to launch the operation asynchronously. La lecture d'un flux où l'opération de lecture peut être satisfaite par les données déjà mises en mémoire tampon est un exemple de ce type de scénario.Reading from a stream where the read operation can be satisfied by data that is already buffered in memory is an example of such a scenario. Dans de tels cas, l'opération peut s'exécuter de façon synchrone et peut retourner une tâche qui a déjà été effectuée.In such cases, the operation may complete synchronously, and may return a task that has already been completed.

ExceptionsExceptions

Une méthode asynchrone doit lever une exception pour être rejetée de l'appel de méthode asynchrone uniquement en réponse à une erreur d'utilisation.An asynchronous method should raise an exception to be thrown out of the asynchronous method call only in response to a usage error. Les erreurs d'utilisation ne doivent jamais se produire dans le code de production.Usage errors should never occur in production code. Par exemple, si le fait de passer une référence null (Nothing en Visual Basic) comme arguments de la méthode provoque un état d’erreur (généralement représenté par une exception ArgumentNullException ), il est possible de modifier le code appelant pour vérifier qu’une référence null n’est jamais passée.For example, if passing a null reference (Nothing in Visual Basic) as one of the method’s arguments causes an error state (usually represented by an ArgumentNullException exception), you can modify the calling code to ensure that a null reference is never passed. Pour toutes les autres erreurs, les exceptions qui se produisent lorsqu'une méthode asynchrone est en cours d'exécution doivent être assignées à la tâche retournée, même si la méthode asynchrone se termine avant que la tâche ne soit retournée.For all other errors, exceptions that occur when an asynchronous method is running should be assigned to the returned task, even if the asynchronous method happens to complete synchronously before the task is returned. En général, une tâche contient au plus une exception.Typically, a task contains at most one exception. Toutefois, si la tâche représente plusieurs opérations (par exemple, WhenAll), plusieurs exceptions peuvent être associées à une tâche unique.However, if the task represents multiple operations (for example, WhenAll), multiple exceptions may be associated with a single task.

Environnement cibleTarget environment

Lorsque vous implémentez une méthode TAP, il est possible de déterminer où l'exécution asynchrone se produit.When you implement a TAP method, you can determine where asynchronous execution occurs. Il est possible de choisir d'exécuter la charge de travail dans le pool de threads, de l'implémenter à l'aide d'E/S asynchrones (sans être lié à un thread pour la majorité de l'exécution de l'opération), de l'exécuter sur un thread spécifique (tel que le thread d'interface utilisateur), ou d'utiliser plusieurs contextes potentiels.You may choose to execute the workload on the thread pool, implement it by using asynchronous I/O (without being bound to a thread for the majority of the operation’s execution), run it on a specific thread (such as the UI thread), or use any number of potential contexts. Une méthode TAP peut même ne rien avoir à exécuter et simplement retourner une Task qui représente l’occurrence d’une condition ailleurs dans le système (par exemple, une tâche qui représente des données reçues par une structure de données en file d’attente).A TAP method may even have nothing to execute, and may just return a Task that represents the occurrence of a condition elsewhere in the system (for example, a task that represents data arriving at a queued data structure).

L’appelant de la méthode TAP peut bloquer l’attente de l’exécution de la méthode TAP par une attente synchrone sur la tâche obtenue, ou il peut exécuter du code supplémentaire (continuation) quand l’opération asynchrone est terminée.The caller of the TAP method may block waiting for the TAP method to complete by synchronously waiting on the resulting task, or may run additional (continuation) code when the asynchronous operation completes. Le créateur du code de continuation a le contrôle sur l'endroit où ce code s'exécute.The creator of the continuation code has control over where that code executes. Il est possible de créer le code de continuation explicitement, via des méthodes sur la classe Task (par exemple, ContinueWith) ou implicitement, à l'aide de la prise en charge des langages par les continuations (par exemple, await en C#, Await en Visual Basic, AwaitValue en F#).You may create the continuation code either explicitly, through methods on the Task class (for example, ContinueWith) or implicitly, by using language support built on top of continuations (for example, await in C#, Await in Visual Basic, AwaitValue in F#).

État des tâchesTask status

La classe Task fournit un cycle de vie pour les opérations asynchrones, et ce cycle est représenté par l'énumération TaskStatus.The Task class provides a life cycle for asynchronous operations, and that cycle is represented by the TaskStatus enumeration. Pour prendre en charge les cas extrêmes de types qui dérivent de Task et de Task<TResult>, et pour prendre en charge la séparation de la construction et de la planification, la classe Task expose une méthode Start.To support corner cases of types that derive from Task and Task<TResult>, and to support the separation of construction from scheduling, the Task class exposes a Start method. Les tâches créées par les constructeurs Task publics sont connues sous le nom de tâches passives, car elles démarrent leur cycle de vie dans l'état Created non planifié et sont planifiées uniquement quand la méthode Start est appelée sur ces instances.Tasks that are created by the public Task constructors are referred to as cold tasks, because they begin their life cycle in the non-scheduled Created state and are scheduled only when Start is called on these instances.

Toutes les autres tâches démarrent leur cycle de vie dans un état réactif, ce qui signifie que les opérations asynchrones qu’elles représentent ont déjà été initialisées et que leur état de tâche est une valeur d’énumération autre que TaskStatus.Created.All other tasks begin their life cycle in a hot state, which means that the asynchronous operations they represent have already been initiated and their task status is an enumeration value other than TaskStatus.Created. Toutes les tâches qui sont retournées par les méthodes TAP doivent être activées.All tasks that are returned from TAP methods must be activated. Si une méthode TAP utilise en interne le constructeur d’une tâche pour instancier la tâche à retourner, la méthode TAP doit appeler Start sur l’objet Task avant de la retourner.If a TAP method internally uses a task’s constructor to instantiate the task to be returned, the TAP method must call Start on the Task object before returning it. Les consommateurs d’une méthode TAP peuvent sans risque supposer que la tâche retournée est active et ne doivent pas essayer d’appeler la méthode Start sur une Task qui est retournée à partir d’une méthode TAP.Consumers of a TAP method may safely assume that the returned task is active and should not try to call Start on any Task that is returned from a TAP method. L'appel de la méthode Start sur une tâche active entraîne la levée d'une exception InvalidOperationException.Calling Start on an active task results in an InvalidOperationException exception.

Annulation (facultatif)Cancellation (optional)

Dans le TAP, l'annulation est facultative pour les implémenteurs de méthodes asynchrones et les consommateurs de méthodes asynchrones.In TAP, cancellation is optional for both asynchronous method implementers and asynchronous method consumers. Si une opération autorise l'annulation, elle expose une surcharge de la méthode asynchrone qui accepte un jeton d'annulation (instance de CancellationToken).If an operation allows cancellation, it exposes an overload of the asynchronous method that accepts a cancellation token (CancellationToken instance). Par convention, le paramètre est nommé cancellationToken.By convention, the parameter is named cancellationToken.

public Task ReadAsync(byte [] buffer, int offset, int count, 
                      CancellationToken cancellationToken)
Public Function ReadAsync(buffer() As Byte, offset As Integer, 
                          count As Integer, 
                          cancellationToken As CancellationToken) _ 
                          As Task

L'opération asynchrone surveille ce jeton en cas de demandes d'annulation.The asynchronous operation monitors this token for cancellation requests. Si elle reçoit une demande d'annulation, elle peut choisir d'honorer cette demande et d'annuler l'opération.If it receives a cancellation request, it may choose to honor that request and cancel the operation. Si la demande d’annulation provoque l’arrêt prématuré du travail, la méthode TAP retourne une tâche qui se termine dans l’état Canceled ; il n’existe aucun résultat disponible et aucune exception n’est levée.If the cancellation request results in work being ended prematurely, the TAP method returns a task that ends in the Canceled state; there is no available result and no exception is thrown. L’état Canceled est considéré comme un état final (terminé) pour une tâche, il en est de même pour les états Faulted et RanToCompletion.The Canceled state is considered to be a final (completed) state for a task, along with the Faulted and RanToCompletion states. Par conséquent, si une tâche est dans l'état Canceled, sa propriété IsCompleted retourne la valeur true.Therefore, if a task is in the Canceled state, its IsCompleted property returns true. Lorsqu'une tâche se termine dans l'état Canceled, toutes les continuations enregistrées avec la tâche sont planifiées ou exécutées, sauf si une option de continuation telle que NotOnCanceled a été spécifiée pour quitter la continuation.When a task completes in the Canceled state, any continuations registered with the task are scheduled or executed, unless a continuation option such as NotOnCanceled was specified to opt out of continuation. Tout code qui attend de façon asynchrone une tâche annulée via l'utilisation de fonctionnalités de langage continue de s'exécuter mais reçoit une exception OperationCanceledException ou une exception qui en dérive.Any code that is asynchronously waiting for a canceled task through use of language features continues to run but receives an OperationCanceledException or an exception derived from it. Le code qui est bloqué de manière synchrone en attendant la tâche via des méthodes telles que Wait et WaitAll continue également de s’exécuter avec une exception.Code that is blocked synchronously waiting on the task through methods such as Wait and WaitAll also continue to run with an exception.

Si un jeton d’annulation a demandé l’annulation avant que la méthode TAP qui accepte le jeton ne soit appelée, la méthode TAP doit retourner une tâche Canceled.If a cancellation token has requested cancellation before the TAP method that accepts that token is called, the TAP method should return a Canceled task. Toutefois, si l'annulation est demandée alors que l'opération asynchrone est en cours d'exécution, l'opération asynchrone n'a pas besoin d'accepter la demande d'annulation.However, if cancellation is requested while the asynchronous operation is running, the asynchronous operation need not accept the cancellation request. La tâche retournée doit se terminer dans l’état Canceled uniquement si l’opération se termine à la suite de la demande d’annulation.The returned task should end in the Canceled state only if the operation ends as a result of the cancellation request. Si l'annulation est demandée mais qu'un résultat (ou une exception) est tout de même produit, la tâche doit se terminer dans l'état RanToCompletion ou Faulted.If cancellation is requested but a result or an exception is still produced, the task should end in the RanToCompletion or Faulted state.

Pour les méthodes asynchrones souhaitant exposer la capacité d’annulation en priorité, vous ne devez pas fournir de surcharge n'acceptant pas de jeton d'annulation.For asynchronous methods that want to expose the ability to be cancelled first and foremost, you don't have to provide an overload that doesn’t accept a cancellation token. Pour les méthodes qui ne peuvent pas être annulées, ne fournissez aucune surcharge acceptant un jeton d'annulation ; cela permet d'indiquer à l'appelant si la méthode cible est réellement annulable ou non.For methods that cannot be canceled, do not provide overloads that accept a cancellation token; this helps indicate to the caller whether the target method is actually cancelable. Le code de consommateur qui ne souhaite pas l’annulation peut appeler une méthode qui accepte un CancellationToken et fournit None comme valeur d’argument.Consumer code that does not desire cancellation may call a method that accepts a CancellationToken and provide None as the argument value. None est fonctionnellement équivalent au CancellationToken par défaut.None is functionally equivalent to the default CancellationToken.

Rapport de progression (facultatif)Progress reporting (optional)

Certaines opérations asynchrones tirent parti de la fourniture de notifications de progression ; elles sont généralement utilisées pour mettre à jour une interface utilisateur avec des informations sur la progression de l'opération asynchrone.Some asynchronous operations benefit from providing progress notifications; these are typically used to update a user interface with information about the progress of the asynchronous operation.

Dans le TAP, la progression est gérée via une interface IProgress<T>, qui est passée à la méthode asynchrone en tant que paramètre généralement nommé progress.In TAP, progress is handled through an IProgress<T> interface, which is passed to the asynchronous method as a parameter that is usually named progress. Le fait de fournir l'interface de progression lorsque la méthode asynchrone est appelée aide à éliminer les conditions de concurrence qui résultent d'une utilisation incorrecte (autrement dit, lorsque les gestionnaires d'événements enregistrés de façon incorrecte après le démarrage de l'opération sont susceptibles de manquer des mises à jour).Providing the progress interface when the asynchronous method is called helps eliminate race conditions that result from incorrect usage (that is, when event handlers that are incorrectly registered after the operation starts may miss updates). Plus important encore, l'interface de progression prend en charge diverses implémentations de progression, comme indiqué par le code de consommation.More importantly, the progress interface supports varying implementations of progress, as determined by the consuming code. Par exemple, le code de consommation peut uniquement s’intéresser à la dernière mise à jour de la progression, ou peut vouloir mettre en mémoire tampon toutes les mises à jour, ou peut vouloir appeler une action pour chaque mise à jour, ou peut vouloir vérifier si l’appel est marshalé à un thread particulier.For example, the consuming code may only care about the latest progress update, or may want to buffer all updates, or may want to invoke an action for each update, or may want to control whether the invocation is marshaled to a particular thread. Toutes ces options peuvent être réalisées en utilisant une implémentation différente de l'interface, personnalisée en fonction des besoins particuliers du consommateur.All these options may be achieved by using a different implementation of the interface, customized to the particular consumer’s needs. Comme pour l'annulation, les implémentations du TAP doivent fournir un paramètre IProgress<T> uniquement si l'API prend en charge les notifications de progression.As with cancellation, TAP implementations should provide an IProgress<T> parameter only if the API supports progress notifications.

Par exemple, si la méthode ReadAsync décrite précédemment dans cet article peut indiquer la progression intermédiaire sous la forme du nombre d'octets lus jusqu'ici, le rappel de progression peut être une interface IProgress<T> :For example, if the ReadAsync method discussed earlier in this article is able to report intermediate progress in the form of the number of bytes read thus far, the progress callback could be an IProgress<T> interface:

public Task ReadAsync(byte[] buffer, int offset, int count, 
                      IProgress<long> progress)
Public Function ReadAsync(buffer() As Byte, offset As Integer, 
                          count As Integer, 
                          progress As IProgress(Of Long)) As Task 

Si une méthode FindFilesAsync retourne une liste de tous les fichiers qui rencontrent un modèle de recherche spécifique, le rappel de progression peut fournir une estimation du pourcentage de travail effectué ainsi que de l’ensemble actuel des résultats partiels.If a FindFilesAsync method returns a list of all files that meet a particular search pattern, the progress callback could provide an estimate of the percentage of work completed as well as the current set of partial results. Elle peut effectuer ceci avec un tuple :It could do this either with a tuple:

public Task<ReadOnlyCollection<FileInfo>> FindFilesAsync(
            string pattern, 
            IProgress<Tuple<double, 
            ReadOnlyCollection<List<FileInfo>>>> progress)
Public Function FindFilesAsync(pattern As String, 
                               progress As IProgress(Of Tuple(Of Double, ReadOnlyCollection(Of List(Of FileInfo))))) _
                               As  Task(Of ReadOnlyCollection(Of FileInfo))

ou avec un type de données spécifique à l'API :or with a data type that is specific to the API:

public Task<ReadOnlyCollection<FileInfo>> FindFilesAsync(
    string pattern, 
    IProgress<FindFilesProgressInfo> progress)
Public Function FindFilesAsync(pattern As String, 
                               progress As IProgress(Of FindFilesProgressInfo)) _
                               As Task(Of ReadOnlyCollection(Of FileInfo))

Dans le second cas, le type de données particulier possède généralement le suffixe ProgressInfo.In the latter case, the special data type is usually suffixed with ProgressInfo.

Si les implémentations du TAP fournissent des surcharges qui acceptent un paramètre progress, elles doivent permettre à l’argument d’être null, dans ce cas aucune progression ne sera signalée.If TAP implementations provide overloads that accept a progress parameter, they must allow the argument to be null, in which case no progress will be reported. Les implémentations du TAP doivent signaler la progression vers l’objet Progress<T> de façon synchrone, ce qui permet à la méthode asynchrone de fournir rapidement la progression, et permettre au consommateur de la progression de déterminer où et comment gérer les informations.TAP implementations should report the progress to the Progress<T> object synchronously, which enables the asynchronous method to quickly provide progress, and allow the consumer of the progress to determine how and where best to handle the information. Par exemple, l'instance de progression peut choisir de marshaler les rappels et de déclencher des événements dans un contexte de synchronisation capturé.For example, the progress instance could choose to marshal callbacks and raise events on a captured synchronization context.

Implémentations IProgress<T>IProgress<T> implementations

.NET Framework 4.5 fournit une implémentation unique de IProgress<T> : Progress<T>.The .NET Framework 4.5 provides a single IProgress<T> implementation: Progress<T>. La classe Progress<T> est déclarée comme suit :The Progress<T> class is declared as follows:

public class Progress<T> : IProgress<T>  
{  
    public Progress();  
    public Progress(Action<T> handler);  
    protected virtual void OnReport(T value);  
    public event EventHandler<T> ProgressChanged;  
}  
Public Class Progress(Of T) : Inherits IProgress(Of T)  
    Public Sub New()  
    Public Sub New(handler As Action(Of T))  
    Protected Overridable Sub OnReport(value As T)  
    Public Event ProgressChanged As EventHandler(Of T>  
End Class  

Une instance de Progress<T> expose un événement ProgressChanged, qui est déclenché chaque fois que l'opération asynchrone signale une mise à jour de la progression.An instance of Progress<T> exposes a ProgressChanged event, which is raised every time the asynchronous operation reports a progress update. L'événement ProgressChanged est déclenché sur l'objet SynchronizationContext qui a été capturé lorsque l'instance de Progress<T> a été instanciée.The ProgressChanged event is raised on the SynchronizationContext object that was captured when the Progress<T> instance was instantiated. Si aucun contexte de synchronisation n’est disponible, un contexte par défaut qui cible le pool de threads est utilisé.If no synchronization context was available, a default context that targets the thread pool is used. Les gestionnaires peuvent être enregistrés avec cet événement.Handlers may be registered with this event. Un gestionnaire unique peut également être fourni au constructeur Progress<T> pour des raisons pratiques, et se comporter comme un gestionnaire d'événements pour l'événement ProgressChanged.A single handler may also be provided to the Progress<T> constructor for convenience, and behaves just like an event handler for the ProgressChanged event. Les mises à jour de progression sont déclenchées de façon asynchrone afin d'éviter de différer l'opération asynchrone alors que les gestionnaires d'événements s'exécutent.Progress updates are raised asynchronously to avoid delaying the asynchronous operation while event handlers are executing. Une autre implémentation de IProgress<T> peut choisir d'appliquer une sémantique différente.Another IProgress<T> implementation could choose to apply different semantics.

Choisir les surcharges à fournirChoosing the overloads to provide

Si une implémentation du TAP utilise des paramètres facultatifs CancellationToken et IProgress<T>, elle est susceptible de nécessiter jusqu'à quatre surcharges :If a TAP implementation uses both the optional CancellationToken and optional IProgress<T> parameters, it could potentially require up to four overloads:

public Task MethodNameAsync(…);  
public Task MethodNameAsync(…, CancellationToken cancellationToken);  
public Task MethodNameAsync(…, IProgress<T> progress);   
public Task MethodNameAsync(…,   
    CancellationToken cancellationToken, IProgress<T> progress);  
Public MethodNameAsync(…) As Task  
Public MethodNameAsync(…, cancellationToken As CancellationToken cancellationToken) As Task  
Public MethodNameAsync(…, progress As IProgress(Of T)) As Task   
Public MethodNameAsync(…, cancellationToken As CancellationToken,   
                       progress As IProgress(Of T)) As Task  

Toutefois, plusieurs implémentations du TAP ne fournissent ni capacité d'annulation ni capacité de progression, elles requièrent donc une méthode unique :However, many TAP implementations provide neither cancellation or progress capabilities, so they require a single method:

public Task MethodNameAsync(…);  
Public MethodNameAsync(…) As Task  

Si une implémentation du TAP prend en charge l'annulation ou la progression, mais pas les deux, elle peut fournir deux surcharges :If a TAP implementation supports either cancellation or progress but not both, it may provide two overloads:

public Task MethodNameAsync(…);  
public Task MethodNameAsync(…, CancellationToken cancellationToken);  
  
// … or …  
  
public Task MethodNameAsync(…);  
public Task MethodNameAsync(…, IProgress<T> progress);  
Public MethodNameAsync(…) As Task  
Public MethodNameAsync(…, cancellationToken As CancellationToken) As Task  
  
' … or …  
  
Public MethodNameAsync(…) As Task  
Public MethodNameAsync(…, progress As IProgress(Of T)) As Task  

Si une implémentation du TAP prend en charge l'annulation et la progression, elle peut exposer les quatre surcharges.If a TAP implementation supports both cancellation and progress, it may expose all four overloads. Toutefois, elle peut fournir uniquement les deux suivantes :However, it may provide only the following two:

public Task MethodNameAsync(…);  
public Task MethodNameAsync(…,   
    CancellationToken cancellationToken, IProgress<T> progress);  
Public MethodNameAsync(…) As Task  
Public MethodNameAsync(…, cancellationToken As CancellationToken,   
                       progress As IProgress(Of T)) As Task  

Pour compenser les deux combinaisons intermédiaires manquantes, les développeurs peuvent passer None ou un CancellationToken par défaut pour le paramètre cancellationToken et la valeur null pour le paramètre progress.To compensate for the two missing intermediate combinations, developers may pass None or a default CancellationToken for the cancellationToken parameter and null for the progress parameter.

Si vous vous attendez à ce que chaque utilisation de la méthode TAP prenne en charge l'annulation ou la progression, vous pouvez omettre les surcharges qui n'acceptent pas le paramètre approprié.If you expect every usage of the TAP method to support cancellation or progress, you may omit the overloads that don’t accept the relevant parameter.

Si vous décidez d'exposer plusieurs surcharges pour rendre l'annulation ou la progression facultative, les surcharges qui ne prennent pas en charge l'annulation ou la progression doivent se comporter comme si elles passaient None pour l'annulation ou null pour la progression à la surcharge qui ne prend pas en charge ces dernières.If you decide to expose multiple overloads to make cancellation or progress optional, the overloads that don’t support cancellation or progress should behave as if they passed None for cancellation or null for progress to the overload that does support these.

TitreTitle DescriptionDescription
Modèles de programmation asynchroneAsynchronous Programming Patterns Présente les trois modèles permettant d'effectuer des opérations asynchrones : le modèle asynchrone basé sur des tâches (TAP), le modèle de programmation asynchrone (APM) et le modèle asynchrone basé sur des événements (EAP).Introduces the three patterns for performing asynchronous operations: the Task-based Asynchronous Pattern (TAP), the Asynchronous Programming Model (APM), and the Event-based Asynchronous Pattern (EAP).
Implémentation du modèle asynchrone basé sur des tâchesImplementing the Task-based Asynchronous Pattern Décrit comment implémenter le modèle asynchrone basé sur des tâches (TAP) de trois façons : à l'aide des compilateurs C# et Visual Basic dans Visual Studio, manuellement, ou par une combinaison des méthodes du compilateur et des méthodes manuelles.Describes how to implement the Task-based Asynchronous Pattern (TAP) in three ways: by using the C# and Visual Basic compilers in Visual Studio, manually, or through a combination of the compiler and manual methods.
Consuming the Task-based Asynchronous PatternConsuming the Task-based Asynchronous Pattern Décrit comment utiliser des tâches et des rappels afin de terminer l’attente sans blocage.Describes how you can use tasks and callbacks to achieve waiting without blocking.
Interopérabilité avec d’autres types et modèles asynchronesInterop with Other Asynchronous Patterns and Types Décrit comment utiliser le modèle asynchrone basé sur des tâches (TAP) pour implémenter le modèle de programmation asynchrone (APM) et le modèle asynchrone basé sur des événements (EAP).Describes how to use the Task-based Asynchronous Pattern (TAP) to implement the Asynchronous Programming Model (APM) and Event-based Asynchronous Pattern (EAP).