Types de retour Async (Visual Basic)Async Return Types (Visual Basic)

Les méthodes async ont trois types de retour possibles : Task<TResult>, Task et void.Async methods have three possible return types: Task<TResult>, Task, and void. En Visual Basic, le type de retour void est écrit sous forme de procédure Sub.In Visual Basic, the void return type is written as a Sub procedure. Pour plus d’informations sur les méthodes async, consultez programmation asynchrone avec Async et Await (Visual Basic).For more information about async methods, see Asynchronous Programming with Async and Await (Visual Basic).

Chaque type de retour est examiné dans l’une des sections suivantes, et vous trouverez un exemple complet qui utilise les trois types à la fin de la rubrique.Each return type is examined in one of the following sections, and you can find a full example that uses all three types at the end of the topic.

Notes

Pour exécuter l’exemple, vous devez avoir Visual Studio version 2012 ou ultérieure et .NET Framework version 4.5 ou ultérieure installés sur votre ordinateur.To run the example, you must have Visual Studio 2012 or newer and the .NET Framework 4.5 or newer installed on your computer.

Type de retour Task(T)Task(T) Return Type

Le Task<TResult> type de retour est utilisé pour une méthode async qui contient un retourner instruction dans laquelle l’opérande est de type TResult.The Task<TResult> return type is used for an async method that contains a Return statement in which the operand has type TResult.

Dans l’exemple suivant, la méthode async TaskOfT_MethodAsync contient une instruction return qui retourne un entier.In the following example, the TaskOfT_MethodAsync async method contains a return statement that returns an integer. La déclaration de méthode doit donc spécifier un type de retour Task(Of Integer).Therefore, the method declaration must specify a return type of Task(Of Integer).

' TASK(OF T) EXAMPLE  
Async Function TaskOfT_MethodAsync() As Task(Of Integer)  
  
    ' The body of an async method is expected to contain an awaited   
    ' asynchronous call.  
    ' Task.FromResult is a placeholder for actual work that returns a string.  
    Dim today As String = Await Task.FromResult(Of String)(DateTime.Now.DayOfWeek.ToString())  
  
    ' The method then can process the result in some way.  
    Dim leisureHours As Integer  
    If today.First() = "S" Then  
        leisureHours = 16  
    Else  
        leisureHours = 5  
    End If  
  
    ' Because the return statement specifies an operand of type Integer, the   
    ' method must have a return type of Task(Of Integer).   
    Return leisureHours  
End Function  

Quand TaskOfT_MethodAsync est appelé à partir d’une expression await, celle-ci récupère la valeur entière (la valeur de leisureHours) qui est stockée dans la tâche retournée par TaskOfT_MethodAsync.When TaskOfT_MethodAsync is called from within an await expression, the await expression retrieves the integer value (the value of leisureHours) that's stored in the task that's returned by TaskOfT_MethodAsync. Pour plus d’informations sur les expressions await, consultez opérateur Await.For more information about await expressions, see Await Operator.

Le code suivant appelle et attend la méthode TaskOfT_MethodAsync.The following code calls and awaits method TaskOfT_MethodAsync. Le résultat est assigné à la variable result1.The result is assigned to the result1 variable.

' Call and await the Task(Of T)-returning async method in the same statement.  
Dim result1 As Integer = Await TaskOfT_MethodAsync()  

Vous pouvez mieux comprendre comment cela se produit en séparant l’appel à TaskOfT_MethodAsync de l’application de Await, comme l’illustre le code suivant.You can better understand how this happens by separating the call to TaskOfT_MethodAsync from the application of Await, as the following code shows. Un appel à la méthode TaskOfT_MethodAsync qui n’est pas immédiatement attendue retourne un type Task(Of Integer), comme vous pourriez l’attendre de la déclaration de la méthode.A call to method TaskOfT_MethodAsync that isn't immediately awaited returns a Task(Of Integer), as you would expect from the declaration of the method. La tâche est assignée à la variable integerTask dans l’exemple.The task is assigned to the integerTask variable in the example. Comme integerTask est un Task<TResult>, il contient une propriété Result de type TResult.Because integerTask is a Task<TResult>, it contains a Result property of type TResult. Dans ce cas, TResult représente un type entier.In this case, TResult represents an integer type. Quand Await est appliqué à integerTask, l’expression await prend pour la valeur le contenu de la propriété Result de integerTask.When Await is applied to integerTask, the await expression evaluates to the contents of the Result property of integerTask. La valeur est assignée à la variable result2.The value is assigned to the result2 variable.

Avertissement

Result est une propriété bloquante.The Result property is a blocking property. Si vous essayez d’y accéder avant la fin de sa tâche, le thread actif est bloqué tant que la tâche n’est pas terminée et que la valeur n’est pas disponible.If you try to access it before its task is finished, the thread that's currently active is blocked until the task completes and the value is available. Dans la plupart des cas, vous devez accéder à la valeur avec Await au lieu d’accéder directement à la propriété.In most cases, you should access the value by using Await instead of accessing the property directly.

' Call and await in separate statements.  
Dim integerTask As Task(Of Integer) = TaskOfT_MethodAsync()  
  
' You can do other work that does not rely on resultTask before awaiting.  
textBox1.Text &= String.Format("Application can continue working while the Task(Of T) runs. . . . " & vbCrLf)  
  
Dim result2 As Integer = Await integerTask  

Les instructions d’affichage dans le code suivant vérifient que les valeurs de la variable result1, de la variable result2 et de la propriété Result sont identiques.The display statements in the following code verify that the values of the result1 variable, the result2 variable, and the Result property are the same. N’oubliez pas que Result est une propriété bloquante et que vous ne devez pas y accéder avant que sa tâche soit attendue.Remember that the Result property is a blocking property and shouldn't be accessed before its task has been awaited.

' Display the values of the result1 variable, the result2 variable, and  
' the resultTask.Result property.  
textBox1.Text &= String.Format(vbCrLf & "Value of result1 variable:   {0}" & vbCrLf, result1)  
textBox1.Text &= String.Format("Value of result2 variable:   {0}" & vbCrLf, result2)  
textBox1.Text &= String.Format("Value of resultTask.Result:  {0}" & vbCrLf, integerTask.Result)  

Type de retour TaskTask Return Type

Les méthodes async qui ne contiennent pas d’instruction return ou qui en contiennent une qui ne retourne pas d’opérande ont généralement un type de retour Task.Async methods that don't contain a return statement or that contain a return statement that doesn't return an operand usually have a return type of Task. Ces méthodes seraient Sub procédures si elles étaient écrites pour exécuter de façon synchrone.Such methods would be Sub procedures if they were written to run synchronously. Si vous utilisez un type de retour Task pour une méthode async, une méthode d’appel peut utiliser un opérateur Await pour suspendre l’achèvement de l’appelant jusqu’à ce que la méthode async soit terminée.If you use a Task return type for an async method, a calling method can use an Await operator to suspend the caller's completion until the called async method has finished.

Dans l’exemple suivant, la méthode async Task_MethodAsync ne contient pas d’instruction return.In the following example, async method Task_MethodAsync doesn't contain a return statement. Par conséquent, vous spécifiez le type de retour Task pour la méthode, ce qui permet à Task_MethodAsync d’être attendu.Therefore, you specify a return type of Task for the method, which enables Task_MethodAsync to be awaited. La définition du type Task n’inclut pas de propriété Result pour stocker une valeur de retour.The definition of the Task type doesn't include a Result property to store a return value.

' TASK EXAMPLE  
Async Function Task_MethodAsync() As Task  
  
    ' The body of an async method is expected to contain an awaited   
    ' asynchronous call.  
    ' Task.Delay is a placeholder for actual work.  
    Await Task.Delay(2000)  
    textBox1.Text &= String.Format(vbCrLf & "Sorry for the delay. . . ." & vbCrLf)  
  
    ' This method has no return statement, so its return type is Task.   
End Function  

Task_MethodAsync est appelé et attendu à l’aide d’une instruction await et non d’une expression await, à l’instar de l’instruction d’appel d’une méthode Sub synchrone ou d’une méthode qui retourne une valeur void.Task_MethodAsync is called and awaited by using an await statement instead of an await expression, similar to the calling statement for a synchronous Sub or void-returning method. L’application d’un Await opérateur dans ce cas ne produit pas une valeur.The application of an Await operator in this case doesn't produce a value.

Le code suivant appelle et attend la méthode Task_MethodAsync.The following code calls and awaits method Task_MethodAsync.

' Call and await the Task-returning async method in the same statement.  
Await Task_MethodAsync()  

Comme dans le précédent Task<TResult> exemple, vous pouvez séparer l’appel à Task_MethodAsync à partir de l’application d’un Await opérateur, comme le montre le code suivant.As in the previous Task<TResult> example, you can separate the call to Task_MethodAsync from the application of an Await operator, as the following code shows. Cependant, n’oubliez pas qu’un type Task n’a pas de propriété Result et qu’aucune valeur n’est générée quand un opérateur await est appliqué à un type Task.However, remember that a Task doesn't have a Result property, and that no value is produced when an await operator is applied to a Task.

Le code suivant sépare l’appel à Task_MethodAsync de l’attente de la tâche que retourne Task_MethodAsync.The following code separates calling Task_MethodAsync from awaiting the task that Task_MethodAsync returns.

' Call and await in separate statements.  
Dim simpleTask As Task = Task_MethodAsync()  
  
' You can do other work that does not rely on simpleTask before awaiting.  
textBox1.Text &= String.Format(vbCrLf & "Application can continue working while the Task runs. . . ." & vbCrLf)  
  
Await simpleTask  

Type de retour voidVoid Return Type

La principale utilisation de Sub procédures est dans les gestionnaires d’événements, où il n’existe aucun type de retour (également appelé un type de retour void dans d’autres langages).The primary use of Sub procedures is in event handlers, where there is no return type (referred to as a void return type in other languages). Le retour de type void peut aussi être utilisé pour remplacer les méthodes qui retournent void ou pour les méthodes qui effectuent des activités considérées comme autonomes après activation (« Fire and Forget ».A void return also can be used to override void-returning methods or for methods that perform activities that can be categorized as "fire and forget." Toutefois, vous devez retourner un type Task dans la mesure du possible, car une méthode async qui retourne un type void ne peut pas être attendue.However, you should return a Task wherever possible, because a void-returning async method can't be awaited. Tout appelant d’une telle méthode doit pouvoir continuer jusqu’à l’achèvement sans attendre que la méthode async soit terminée, et l’appelant doit être indépendant des valeurs ou des exceptions générées par la méthode async.Any caller of such a method must be able to continue to completion without waiting for the called async method to finish, and the caller must be independent of any values or exceptions that the async method generates.

L’appelant d’une méthode async qui retourne une valeur void ne peut pas intercepter les exceptions levées à partir de la méthode, et ces exceptions non gérées peuvent entraîner l’échec de votre application.The caller of a void-returning async method can't catch exceptions that are thrown from the method, and such unhandled exceptions are likely to cause your application to fail. Si une exception se produit dans une méthode asyn qui retourne Task ou Task<TResult>, l’exception est stockée dans la tâche retournée et est à nouveau levée pendant l’attente de la tâche.If an exception occurs in an async method that returns a Task or Task<TResult>, the exception is stored in the returned task, and rethrown when the task is awaited. Par conséquent, veillez à ce qu’une méthode async capable de générer une exception ait le type de retour Task ou Task<TResult> et que les appels à la méthode soient attendus.Therefore, make sure that any async method that can produce an exception has a return type of Task or Task<TResult> and that calls to the method are awaited.

Pour plus d’informations sur l’interception des exceptions dans les méthodes async, consultez la page Instruction Try...Catch...Finally.For more information about how to catch exceptions in async methods, see Try...Catch...Finally Statement.

Le code suivant définit un gestionnaire d’événements asynchrones.The following code defines an async event handler.

' SUB EXAMPLE  
Async Sub button1_Click(sender As Object, e As RoutedEventArgs) Handles button1.Click  
  
    textBox1.Clear()  
  
    ' Start the process and await its completion. DriverAsync is a   
    ' Task-returning async method.  
    Await DriverAsync()  
  
    ' Say goodbye.  
    textBox1.Text &= vbCrLf & "All done, exiting button-click event handler."  
End Sub  

Exemple completComplete Example

Le projet Windows Presentation Foundation (WPF) suivant contient les exemples de code de cette rubrique.The following Windows Presentation Foundation (WPF) project contains the code examples from this topic.

Pour exécuter le projet, procédez comme suit :To run the project, perform the following steps:

  1. Démarrez Visual Studio.Start Visual Studio.

  2. Dans la barre de menus, sélectionnez Fichier, Nouveau, Projet.On the menu bar, choose File, New, Project.

    La boîte de dialogue Nouveau projet s'affiche.The New Project dialog box opens.

  3. Dans le installé, modèles catégorie, choisissez Visual Basic, puis choisissez Windows.In the Installed, Templates category, choose Visual Basic, and then choose Windows. Choisissez Application WPF dans la liste des types de projets.Choose WPF Application from the list of project types.

  4. Entrez AsyncReturnTypes comme nom de projet, puis cliquez sur le bouton OK.Enter AsyncReturnTypes as the name of the project, and then choose the OK button.

    Le nouveau projet s’affiche dans l’Explorateur de solutions.The new project appears in Solution Explorer.

  5. Dans l'éditeur de code Visual Studio, choisissez l'onglet MainWindow.xaml .In the Visual Studio Code Editor, choose the MainWindow.xaml tab.

    Si l’onglet n’est pas visible, ouvrez le menu contextuel pour MainWindow.xaml dans l’Explorateur de solutions, puis choisissez Ouvrir.If the tab is not visible, open the shortcut menu for MainWindow.xaml in Solution Explorer, and then choose Open.

  6. Dans la fenêtre XAML de MainWindow.xaml, remplacez le code existant par le code suivant.In the XAML window of MainWindow.xaml, replace the code with the following code.

    <Window x:Class="MainWindow"  
            xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"  
            xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"  
            Title="MainWindow" Height="350" Width="525">  
        <Grid>  
            <Button x:Name="button1" Content="Start" HorizontalAlignment="Left" Margin="214,28,0,0" VerticalAlignment="Top" Width="75" HorizontalContentAlignment="Center" FontWeight="Bold" FontFamily="Aharoni" Click="button1_Click"/>  
            <TextBox x:Name="textBox1" Margin="0,80,0,0" TextWrapping="Wrap" FontFamily="Lucida Console"/>  
    
        </Grid>  
    </Window>  
    

    Une fenêtre simple contenant une zone de texte et un bouton apparaît dans la fenêtre Design de MainWindow.xaml.A simple window that contains a text box and a button appears in the Design window of MainWindow.xaml.

  7. Dans l’Explorateur de solutions, ouvrez le menu contextuel pour MainWindow.xaml.vb, puis choisissez afficher le Code.In Solution Explorer, open the shortcut menu for MainWindow.xaml.vb, and then choose View Code.

  8. Remplacez le code situé dans MainWindow.xaml.vb par le code suivant.Replace the code in MainWindow.xaml.vb with the following code.

    Class MainWindow  
    
        ' SUB EXAMPLE  
        Async Sub button1_Click(sender As Object, e As RoutedEventArgs) Handles button1.Click  
    
            textBox1.Clear()  
    
            ' Start the process and await its completion. DriverAsync is a   
            ' Task-returning async method.  
            Await DriverAsync()  
    
            ' Say goodbye.  
            textBox1.Text &= vbCrLf & "All done, exiting button-click event handler."  
        End Sub  
    
        Async Function DriverAsync() As Task  
    
            ' Task(Of T)   
            ' Call and await the Task(Of T)-returning async method in the same statement.  
            Dim result1 As Integer = Await TaskOfT_MethodAsync()  
    
            ' Call and await in separate statements.  
            Dim integerTask As Task(Of Integer) = TaskOfT_MethodAsync()  
    
            ' You can do other work that does not rely on resultTask before awaiting.  
            textBox1.Text &= String.Format("Application can continue working while the Task(Of T) runs. . . . " & vbCrLf)  
    
            Dim result2 As Integer = Await integerTask  
    
            ' Display the values of the result1 variable, the result2 variable, and  
            ' the resultTask.Result property.  
            textBox1.Text &= String.Format(vbCrLf & "Value of result1 variable:   {0}" & vbCrLf, result1)  
            textBox1.Text &= String.Format("Value of result2 variable:   {0}" & vbCrLf, result2)  
            textBox1.Text &= String.Format("Value of resultTask.Result:  {0}" & vbCrLf, integerTask.Result)  
    
            ' Task   
            ' Call and await the Task-returning async method in the same statement.  
            Await Task_MethodAsync()  
    
            ' Call and await in separate statements.  
            Dim simpleTask As Task = Task_MethodAsync()  
    
            ' You can do other work that does not rely on simpleTask before awaiting.  
            textBox1.Text &= String.Format(vbCrLf & "Application can continue working while the Task runs. . . ." & vbCrLf)  
    
            Await simpleTask  
        End Function  
    
        ' TASK(OF T) EXAMPLE  
        Async Function TaskOfT_MethodAsync() As Task(Of Integer)  
    
            ' The body of an async method is expected to contain an awaited   
            ' asynchronous call.  
            ' Task.FromResult is a placeholder for actual work that returns a string.  
            Dim today As String = Await Task.FromResult(Of String)(DateTime.Now.DayOfWeek.ToString())  
    
            ' The method then can process the result in some way.  
            Dim leisureHours As Integer  
            If today.First() = "S" Then  
                leisureHours = 16  
            Else  
                leisureHours = 5  
            End If  
    
            ' Because the return statement specifies an operand of type Integer, the   
            ' method must have a return type of Task(Of Integer).   
            Return leisureHours  
        End Function  
    
        ' TASK EXAMPLE  
        Async Function Task_MethodAsync() As Task  
    
            ' The body of an async method is expected to contain an awaited   
            ' asynchronous call.  
            ' Task.Delay is a placeholder for actual work.  
            Await Task.Delay(2000)  
            textBox1.Text &= String.Format(vbCrLf & "Sorry for the delay. . . ." & vbCrLf)  
    
            ' This method has no return statement, so its return type is Task.   
        End Function  
    
    End Class  
    
  9. Appuyez sur la touche F5 pour exécuter le programme, puis choisissez le bouton Démarrer.Choose the F5 key to run the program, and then choose the Start button.

    La sortie suivante doit s’afficher.The following output should appear.

    Application can continue working while the Task<T> runs. . . .   
    
    Value of result1 variable:   5  
    Value of result2 variable:   5  
    Value of integerTask.Result: 5  
    
    Sorry for the delay. . . .  
    
    Application can continue working while the Task runs. . . .  
    
    Sorry for the delay. . . .  
    
    All done, exiting button-click event handler.  
    

Voir aussiSee also