Annuler une tâche asynchrone ou une liste de tâches (Visual Basic)Cancel an Async Task or a List of Tasks (Visual Basic)

Vous pouvez créer un bouton permettant d’annuler une application asynchrone que vous souhaitez interrompre avant la fin de son exécution.You can set up a button that you can use to cancel an async application if you don't want to wait for it to finish. Les exemples de cette rubrique vous montrent comment ajouter un bouton d’annulation à une application qui télécharge du contenu d’un site web ou une liste de sites web.By following the examples in this topic, you can add a cancellation button to an application that downloads the contents of one website or a list of websites.

Les exemples utilisent l’interface utilisateur que décrit pour ajuster votre application Async (Visual Basic) .The examples use the UI that Fine-Tuning Your Async Application (Visual Basic) describes.

Notes

Pour exécuter les exemples, Visual Studio version 2012 ou ultérieure et le .NET Framework version 4.5 ou ultérieure doivent être installés sur votre ordinateur.To run the examples, you must have Visual Studio 2012 or newer and the .NET Framework 4.5 or newer installed on your computer.

Annuler une tâcheCancel a Task

Le premier exemple associe le bouton Annuler à une tâche de téléchargement unique.The first example associates the Cancel button with a single download task. Si vous appuyez sur le bouton pendant que l’application télécharge du contenu, le téléchargement est annulé.If you choose the button while the application is downloading content, the download is canceled.

Téléchargement de l'exempleDownloading the Example

Téléchargez l’intégralité des projets Windows Presentation Foundation (WPF) à partir de la page Async Sample: Fine Tuning Your Application (Exemple Async  : Réglage précis de votre application), puis suivez ces étapes.You can download the complete Windows Presentation Foundation (WPF) project from Async Sample: Fine Tuning Your Application and then follow these steps.

  1. Décompressez le fichier que vous avez téléchargé, puis démarrez Visual Studio.Decompress the file that you downloaded, and then start Visual Studio.

  2. Dans la barre de menus, choisissez Fichier, Ouvrir, Projet/Solution.On the menu bar, choose File, Open, Project/Solution.

  3. Dans la boîte de dialogue Ouvrir le projet, ouvrez le dossier contenant l’exemple de code que vous avez décompressé, puis ouvrez le fichier de solution (.sln) pour AsyncFineTuningVB.In the Open Project dialog box, open the folder that holds the sample code that you decompressed, and then open the solution (.sln) file for AsyncFineTuningVB.

  4. Dans l’Explorateur de solutions, ouvrez le menu contextuel du projet CancelATask, puis choisissez Définir comme projet de démarrage.In Solution Explorer, open the shortcut menu for the CancelATask project, and then choose Set as StartUp Project.

  5. Appuyez sur la touche F5 pour exécuter le projet.Choose the F5 key to run the project.

    Appuyez sur les touches Ctrl+F5 pour exécuter le projet sans le déboguer.Choose the Ctrl+F5 keys to run the project without debugging it.

Si vous ne souhaitez pas télécharger le projet, vous pouvez consulter les fichiers MainWindow. Xaml. vb à la fin de cette rubrique.If you don't want to download the project, you can review the MainWindow.xaml.vb files at the end of this topic.

Génération de l’exempleBuilding the Example

Les modifications suivantes ajoutent un bouton Annuler à une application de téléchargement d’un site web.The following changes add a Cancel button to an application that downloads a website. Si vous ne voulez pas télécharger ou générer l’exemple, vous pouvez examiner le produit final dans la section « Exemples complets », à la fin de cette rubrique.If you don't want to download or build the example, you can review the final product in the "Complete Examples" section at the end of this topic. Les astérisques signalent les modifications du code.Asterisks mark the changes in the code.

Pour générer l’exemple vous-même, pas à pas, suivez les instructions de la section « Téléchargement de l’exemple », mais choisissez StarterCode comme Projet de démarrage au lieu de CancelATask.To build the example yourself, step by step, follow the instructions in the "Downloading the Example" section, but choose StarterCode as the StartUp Project instead of CancelATask.

Ajoutez ensuite les modifications suivantes au fichier MainWindow. Xaml. vb de ce projet.Then add the following changes to the MainWindow.xaml.vb file of that project.

  1. Déclarez une variable CancellationTokenSource, cts, qui se trouve dans la portée de toutes les méthodes qui y accèdent.Declare a CancellationTokenSource variable, cts, that’s in scope for all methods that access it.

    Class MainWindow
    
        ' ***Declare a System.Threading.CancellationTokenSource.
        Dim cts As CancellationTokenSource
    
  2. Ajoutez le gestionnaire d’événements suivant pour le bouton Annuler.Add the following event handler for the Cancel button. Le gestionnaire d’événements utilise la méthode CancellationTokenSource.Cancel pour notifier à cts la demande d’annulation de l’utilisateur.The event handler uses the CancellationTokenSource.Cancel method to notify cts when the user requests cancellation.

    ' ***Add an event handler for the Cancel button.
    Private Sub cancelButton_Click(sender As Object, e As RoutedEventArgs)
    
        If cts IsNot Nothing Then
            cts.Cancel()
        End If
    End Sub
    
  3. Effectuez les modifications suivantes dans le gestionnaire d’événements pour le bouton Démarrer, startButton_Click.Make the following changes in the event handler for the Start button, startButton_Click.

    • Instanciez le CancellationTokenSource, cts.Instantiate the CancellationTokenSource, cts.

      ' ***Instantiate the CancellationTokenSource.
      cts = New CancellationTokenSource()
      
    • Dans l’appel à AccessTheWebAsync, qui télécharge le contenu d’un site web spécifié, envoyez la propriété CancellationTokenSource.Token de cts comme argument.In the call to AccessTheWebAsync, which downloads the contents of a specified website, send the CancellationTokenSource.Token property of cts as an argument. La propriété Token propage le message si l’annulation est demandée.The Token property propagates the message if cancellation is requested. Ajoutez un bloc catch qui affiche un message si l’utilisateur choisit d’annuler l’opération de téléchargement.Add a catch block that displays a message if the user chooses to cancel the download operation. Le code suivant illustre les modifications.The following code shows the changes.

      Try
          ' ***Send a token to carry the message if cancellation is requested.
          Dim contentLength As Integer = Await AccessTheWebAsync(cts.Token)
      
          resultsTextBox.Text &=
              String.Format(vbCrLf & "Length of the downloaded string: {0}." & vbCrLf, contentLength)
      
          ' *** If cancellation is requested, an OperationCanceledException results.
      Catch ex As OperationCanceledException
          resultsTextBox.Text &= vbCrLf & "Download canceled." & vbCrLf
      
      Catch ex As Exception
          resultsTextBox.Text &= vbCrLf & "Download failed." & vbCrLf
      End Try
      
  4. Dans AccessTheWebAsync, utilisez la surcharge HttpClient.GetAsync(String, CancellationToken) de la méthode GetAsync dans le type HttpClient pour télécharger le contenu d’un site web.In AccessTheWebAsync, use the HttpClient.GetAsync(String, CancellationToken) overload of the GetAsync method in the HttpClient type to download the contents of a website. Passez ct, le paramètre CancellationToken de AccessTheWebAsync, comme deuxième argument.Pass ct, the CancellationToken parameter of AccessTheWebAsync, as the second argument. Le jeton transmet le message si l’utilisateur choisit le bouton Annuler.The token carries the message if the user chooses the Cancel button.

    Le code suivant illustre les modifications dans AccessTheWebAsync.The following code shows the changes in AccessTheWebAsync.

    ' ***Provide a parameter for the CancellationToken.
    Async Function AccessTheWebAsync(ct As CancellationToken) As Task(Of Integer)
    
        Dim client As HttpClient = New HttpClient()
    
        resultsTextBox.Text &=
            String.Format(vbCrLf & "Ready to download." & vbCrLf)
    
        ' You might need to slow things down to have a chance to cancel.
        Await Task.Delay(250)
    
        ' GetAsync returns a Task(Of HttpResponseMessage).
        ' ***The ct argument carries the message if the Cancel button is chosen.
        Dim response As HttpResponseMessage = Await client.GetAsync("https://msdn.microsoft.com/library/dd470362.aspx", ct)
    
        ' Retrieve the website contents from the HttpResponseMessage.
        Dim urlContents As Byte() = Await response.Content.ReadAsByteArrayAsync()
    
        ' The result of the method is the length of the downloaded website.
        Return urlContents.Length
    End Function
    
  5. Si vous n’annulez pas le programme, il génère le résultat suivant.If you don’t cancel the program, it produces the following output.

    Ready to download.
    Length of the downloaded string: 158125.
    

    Si vous choisissez le bouton Annuler quand le programme est encore en train de télécharger du contenu, le programme génère le résultat suivant.If you choose the Cancel button before the program finishes downloading the content, the program produces the following output.

    Ready to download.
    Download canceled.
    

Annuler une liste de tâchesCancel a List of Tasks

Vous pouvez étendre l’exemple précédent pour annuler de nombreuses tâches à la fois en associant la même instance CancellationTokenSource à chaque tâche.You can extend the previous example to cancel many tasks by associating the same CancellationTokenSource instance with each task. Si vous choisissez le bouton Annuler, vous annulez toutes les tâches qui ne sont pas encore terminées.If you choose the Cancel button, you cancel all tasks that aren’t yet complete.

Téléchargement de l'exempleDownloading the Example

Téléchargez l’intégralité des projets Windows Presentation Foundation (WPF) à partir de la page Async Sample: Fine Tuning Your Application (Exemple Async  : Réglage précis de votre application), puis suivez ces étapes.You can download the complete Windows Presentation Foundation (WPF) project from Async Sample: Fine Tuning Your Application and then follow these steps.

  1. Décompressez le fichier que vous avez téléchargé, puis démarrez Visual Studio.Decompress the file that you downloaded, and then start Visual Studio.

  2. Dans la barre de menus, choisissez Fichier, Ouvrir, Projet/Solution.On the menu bar, choose File, Open, Project/Solution.

  3. Dans la boîte de dialogue Ouvrir le projet, ouvrez le dossier contenant l’exemple de code que vous avez décompressé, puis ouvrez le fichier de solution (.sln) pour AsyncFineTuningVB.In the Open Project dialog box, open the folder that holds the sample code that you decompressed, and then open the solution (.sln) file for AsyncFineTuningVB.

  4. Dans l’Explorateur de solutions, ouvrez le menu contextuel du projet CancelAListOfTasks, puis choisissez Définir comme projet de démarrage.In Solution Explorer, open the shortcut menu for the CancelAListOfTasks project, and then choose Set as StartUp Project.

  5. Appuyez sur la touche F5 pour exécuter le projet.Choose the F5 key to run the project.

    Appuyez sur les touches Ctrl+F5 pour exécuter le projet sans le déboguer.Choose the Ctrl+F5 keys to run the project without debugging it.

Si vous ne souhaitez pas télécharger le projet, vous pouvez consulter les fichiers MainWindow. Xaml. vb à la fin de cette rubrique.If you don't want to download the project, you can review the MainWindow.xaml.vb files at the end of this topic.

Génération de l’exempleBuilding the Example

Pour étendre l’exemple vous-même, pas à pas, suivez les instructions de la section « Téléchargement de l’exemple », mais choisissez CancelATask comme Projet de démarrage.To extend the example yourself, step by step, follow the instructions in the "Downloading the Example" section, but choose CancelATask as the StartUp Project. Apportez les modifications suivantes au projet.Add the following changes to that project. Les astérisques signalent les modifications effectuées dans le programme.Asterisks mark the changes in the program.

  1. Ajoutez une méthode pour créer une liste des adresses web.Add a method to create a list of web addresses.

    ' ***Add a method that creates a list of web addresses.
    Private Function SetUpURLList() As List(Of String)
    
        Dim urls = New List(Of String) From
            {
                "https://msdn.microsoft.com",
                "https://msdn.microsoft.com/library/hh290138.aspx",
                "https://msdn.microsoft.com/library/hh290140.aspx",
                "https://msdn.microsoft.com/library/dd470362.aspx",
                "https://msdn.microsoft.com/library/aa578028.aspx",
                "https://msdn.microsoft.com/library/ms404677.aspx",
                "https://msdn.microsoft.com/library/ff730837.aspx"
            }
        Return urls
    End Function
    
  2. Appelez la méthode dans AccessTheWebAsync.Call the method in AccessTheWebAsync.

    ' ***Call SetUpURLList to make a list of web addresses.
    Dim urlList As List(Of String) = SetUpURLList()
    
  3. Ajoutez la boucle suivante dans AccessTheWebAsync pour traiter chaque adresse web dans la liste.Add the following loop in AccessTheWebAsync to process each web address in the list.

    ' ***Add a loop to process the list of web addresses.
    For Each url In urlList
        ' GetAsync returns a Task(Of HttpResponseMessage).
        ' Argument ct carries the message if the Cancel button is chosen.
        ' ***Note that the Cancel button can cancel all remaining downloads.
        Dim response As HttpResponseMessage = Await client.GetAsync(url, ct)
    
        ' Retrieve the website contents from the HttpResponseMessage.
        Dim urlContents As Byte() = Await response.Content.ReadAsByteArrayAsync()
    
        resultsTextBox.Text &=
            String.Format(vbCrLf & "Length of the downloaded string: {0}." & vbCrLf, urlContents.Length)
    Next
    
  4. Comme AccessTheWebAsync affiche les longueurs, la méthode n’a pas besoin de retourner une valeur.Because AccessTheWebAsync displays the lengths, the method doesn't need to return anything. Supprimez l’instruction return et changez le type de retour de la méthode de Task en Task<TResult>.Remove the return statement, and change the return type of the method to Task instead of Task<TResult>.

    Async Function AccessTheWebAsync(ct As CancellationToken) As Task
    

    Appelez la méthode à partir de startButton_Click à l’aide d’une instruction au lieu d’une expression.Call the method from startButton_Click by using a statement instead of an expression.

    Await AccessTheWebAsync(cts.Token)
    
  5. Si vous n’annulez pas le programme, il génère le résultat suivant.If you don’t cancel the program, it produces the following output.

    Length of the downloaded string: 35939.
    
    Length of the downloaded string: 237682.
    
    Length of the downloaded string: 128607.
    
    Length of the downloaded string: 158124.
    
    Length of the downloaded string: 204890.
    
    Length of the downloaded string: 175488.
    
    Length of the downloaded string: 145790.
    
    Downloads complete.
    

    Si vous choisissez le bouton Annuler avant la fin des téléchargements, la sortie contient les longueurs des chaînes ayant été téléchargées avant l’annulation.If you choose the Cancel button before the downloads are complete, the output contains the lengths of the downloads that completed before the cancellation.

    Length of the downloaded string: 35939.
    
    Length of the downloaded string: 237682.
    
    Length of the downloaded string: 128607.
    
    Downloads canceled.
    

Exemples completsComplete Examples

Les sections suivantes contiennent le code correspondant à chacun des exemples précédents.The following sections contain the code for each of the previous examples. Notez que vous devez ajouter une référence pour System.Net.Http.Notice that you must add a reference for System.Net.Http.

Vous pouvez télécharger les projets sur Async Sample: Fine Tuning Your Application (Exemple Async : Réglage précis de votre application).You can download the projects from Async Sample: Fine Tuning Your Application.

Exemple d’annulation d’une tâcheCancel a Task Example

Le code suivant est le fichier MainWindow. Xaml. vb complet pour l’exemple qui annule une seule tâche.The following code is the complete MainWindow.xaml.vb file for the example that cancels a single task.

' Add an Imports directive and a reference for System.Net.Http.
Imports System.Net.Http

' Add the following Imports directive for System.Threading.
Imports System.Threading

Class MainWindow

    ' ***Declare a System.Threading.CancellationTokenSource.
    Dim cts As CancellationTokenSource

    Private Async Sub startButton_Click(sender As Object, e As RoutedEventArgs)
        ' ***Instantiate the CancellationTokenSource.
        cts = New CancellationTokenSource()

        resultsTextBox.Clear()

        Try
            ' ***Send a token to carry the message if cancellation is requested.
            Dim contentLength As Integer = Await AccessTheWebAsync(cts.Token)

            resultsTextBox.Text &=
                String.Format(vbCrLf & "Length of the downloaded string: {0}." & vbCrLf, contentLength)

            ' *** If cancellation is requested, an OperationCanceledException results.
        Catch ex As OperationCanceledException
            resultsTextBox.Text &= vbCrLf & "Download canceled." & vbCrLf

        Catch ex As Exception
            resultsTextBox.Text &= vbCrLf & "Download failed." & vbCrLf
        End Try

        ' ***Set the CancellationTokenSource to Nothing when the download is complete.
        cts = Nothing
    End Sub

    ' ***Add an event handler for the Cancel button.
    Private Sub cancelButton_Click(sender As Object, e As RoutedEventArgs)

        If cts IsNot Nothing Then
            cts.Cancel()
        End If
    End Sub

    ' ***Provide a parameter for the CancellationToken.
    Async Function AccessTheWebAsync(ct As CancellationToken) As Task(Of Integer)

        Dim client As HttpClient = New HttpClient()

        resultsTextBox.Text &=
            String.Format(vbCrLf & "Ready to download." & vbCrLf)

        ' You might need to slow things down to have a chance to cancel.
        Await Task.Delay(250)

        ' GetAsync returns a Task(Of HttpResponseMessage).
        ' ***The ct argument carries the message if the Cancel button is chosen.
        Dim response As HttpResponseMessage = Await client.GetAsync("https://msdn.microsoft.com/library/dd470362.aspx", ct)

        ' Retrieve the website contents from the HttpResponseMessage.
        Dim urlContents As Byte() = Await response.Content.ReadAsByteArrayAsync()

        ' The result of the method is the length of the downloaded website.
        Return urlContents.Length
    End Function
End Class

' Output for a successful download:

' Ready to download.

' Length of the downloaded string: 158125.

' Or, if you cancel:

' Ready to download.

' Download canceled.

Exemple d’annulation d’une liste de tâchesCancel a List of Tasks Example

Le code suivant est le fichier MainWindow. Xaml. vb complet pour l’exemple qui annule une liste de tâches.The following code is the complete MainWindow.xaml.vb file for the example that cancels a list of tasks.

' Add an Imports directive and a reference for System.Net.Http.
Imports System.Net.Http

' Add the following Imports directive for System.Threading.
Imports System.Threading

Class MainWindow

    ' Declare a System.Threading.CancellationTokenSource.
    Dim cts As CancellationTokenSource

    Private Async Sub startButton_Click(sender As Object, e As RoutedEventArgs)

        ' Instantiate the CancellationTokenSource.
        cts = New CancellationTokenSource()

        resultsTextBox.Clear()

        Try
            ' ***AccessTheWebAsync returns a Task, not a Task(Of Integer).
            Await AccessTheWebAsync(cts.Token)
            '  ***Small change in the display lines.
            resultsTextBox.Text &= vbCrLf & "Downloads complete."

        Catch ex As OperationCanceledException
            resultsTextBox.Text &= vbCrLf & "Downloads canceled." & vbCrLf

        Catch ex As Exception
            resultsTextBox.Text &= vbCrLf & "Downloads failed." & vbCrLf
        End Try

        ' Set the CancellationTokenSource to Nothing when the download is complete.
        cts = Nothing
    End Sub

    ' Add an event handler for the Cancel button.
    Private Sub cancelButton_Click(sender As Object, e As RoutedEventArgs)

        If cts IsNot Nothing Then
            cts.Cancel()
        End If
    End Sub

    ' Provide a parameter for the CancellationToken.
    ' ***Change the return type to Task because the method has no return statement.
    Async Function AccessTheWebAsync(ct As CancellationToken) As Task

        Dim client As HttpClient = New HttpClient()

        ' ***Call SetUpURLList to make a list of web addresses.
        Dim urlList As List(Of String) = SetUpURLList()

        ' ***Add a loop to process the list of web addresses.
        For Each url In urlList
            ' GetAsync returns a Task(Of HttpResponseMessage).
            ' Argument ct carries the message if the Cancel button is chosen.
            ' ***Note that the Cancel button can cancel all remaining downloads.
            Dim response As HttpResponseMessage = Await client.GetAsync(url, ct)

            ' Retrieve the website contents from the HttpResponseMessage.
            Dim urlContents As Byte() = Await response.Content.ReadAsByteArrayAsync()

            resultsTextBox.Text &=
                String.Format(vbCrLf & "Length of the downloaded string: {0}." & vbCrLf, urlContents.Length)
        Next
    End Function

    ' ***Add a method that creates a list of web addresses.
    Private Function SetUpURLList() As List(Of String)

        Dim urls = New List(Of String) From
            {
                "https://msdn.microsoft.com",
                "https://msdn.microsoft.com/library/hh290138.aspx",
                "https://msdn.microsoft.com/library/hh290140.aspx",
                "https://msdn.microsoft.com/library/dd470362.aspx",
                "https://msdn.microsoft.com/library/aa578028.aspx",
                "https://msdn.microsoft.com/library/ms404677.aspx",
                "https://msdn.microsoft.com/library/ff730837.aspx"
            }
        Return urls
    End Function

End Class

' Output if you do not choose to cancel:

' Length of the downloaded string: 35939.

' Length of the downloaded string: 237682.

' Length of the downloaded string: 128607.

' Length of the downloaded string: 158124.

' Length of the downloaded string: 204890.

' Length of the downloaded string: 175488.

' Length of the downloaded string: 145790.

' Downloads complete.

'  Sample output if you choose to cancel:

' Length of the downloaded string: 35939.

' Length of the downloaded string: 237682.

' Length of the downloaded string: 128607.

' Downloads canceled.

Voir aussiSee also