Appeler des API asynchrones en C# ou Visual BasicCall asynchronous APIs in C# or Visual Basic

La plateforme Windows universelle (UWP) comporte de nombreuses API asynchrones qui permettent à votre application de rester réactive lorsqu’elle exécute des opérations potentiellement longues.The Universal Windows Platform (UWP) includes many asynchronous APIs to ensure that your app remains responsive when it does work that might take an extended amount of time. Cette rubrique décrit comment utiliser les méthodes asynchrones de l’UWP, en C# ou Microsoft Visual Basic.This topic discusses how to use asynchronous methods from the UWP in C# or Microsoft Visual Basic.

Les API asynchrones évitent à votre application d’attendre la fin d’opérations d’envergure pour poursuivre son exécution.Asynchronous APIs keep your app from waiting for large operations to complete before continuing execution. Par exemple, une application qui télécharge des informations à partir d’un site Internet peut passer plusieurs secondes à attendre que les informations arrivent.For example, an app that downloads info from the Internet might spend several seconds waiting for the info to arrive. Si vous utilisez une méthode synchrone pour récupérer les informations, l’application reste bloquée jusqu’à ce que la méthode renvoie un résultat.If you use a synchronous method to retrieve the info, the app is blocked until the method returns. L’application ne répond alors plus aux interactions utilisateur, ce qui peut constituer une gêne pour l’utilisateur.The app won't respond to user interaction and because it seems non-responsive, the user might become frustrated. En fournissant des API asynchrones, l’UWP contribue à ce que votre application reste réactive aux interactions utilisateur pendant les opérations nécessitant un temps d’exécution plus long.By providing asynchronous APIs, the UWP helps to ensure that your app stays responsive to the user when it's performing long operations.

La plupart des API asynchrones UWP n’ayant pas d’équivalents synchrones, vous devez être certain de savoir comment utiliser les API asynchrones avec C# ou Visual Basic dans votre application de plateforme Windows universelle (UWP).Most of the asynchronous APIs in the UWP don't have synchronous counterparts, so you need to be sure to understand how to use the asynchronous APIs with C# or Visual Basic in your Universal Windows Platform (UWP) app. Nous allons vous montrer comment appeler des API asynchrones de l’UWP.Here we show how to call asynchronous APIs of the UWP.

Utilisation d’API asynchronesUsing asynchronous APIs

Par convention, les noms attribués aux méthodes asynchrones se terminent par « Async ».By convention, asynchronous methods are given names that end in "Async". Vous appelez généralement des API asynchrones en réponse à une action de l’utilisateur, par exemple quand l’utilisateur clique sur un bouton.You typically call asynchronous APIs in response to a user's action, such as when the user clicks a button. L’appel d’une méthode asynchrone dans un gestionnaire d’événements est l’une des façons les plus simples d’utiliser des API asynchrones.Calling an asynchronous method in an event handler is one of the simplest ways of using asynchronous APIs. Prenons comme exemple l’opérateur await.Here we use the await operator as an example.

Supposons que votre application affiche la liste des titres de billets de blog publiés sur un site donné.Suppose that you have an app that lists the titles of blog posts from a certain location. L’application comporte un bouton (Button) sur lequel l’utilisateur doit cliquer pour obtenir la liste des titres.The app has a Button that the user clicks to get the titles. Les titres s’affichent dans un bloc de texte (TextBlock).The titles are displayed in a TextBlock. Lorsque l’utilisateur clique sur le bouton, il est important que l’application reste réactive pendant le téléchargement des informations provenant du site web du blog.When the user clicks the button, it is important that the app remains responsive while it waits for the info from the blog's website. Pour maintenir cette réactivité, l’UWP fournit la méthode asynchrone SyndicationClient.RetrieveFeedAsync qui télécharge le flux.To ensure this responsiveness, the UWP provides an asynchronous method, SyndicationClient.RetrieveFeedAsync, to download the feed.

L’exemple suivant obtient les titres des billets d’un blog en appelant la méthode asynchrone, SyndicationClient.RetrieveFeedAsync et en attendant le résultat.The example here gets the lists of blog posts from a blog by calling the asynchronous method, SyndicationClient.RetrieveFeedAsync, and awaiting the result.

// Put the keyword async on the declaration of the event handler.
private async void Button_Click_1(object sender, RoutedEventArgs e)
{

    Windows.Web.Syndication.SyndicationClient client = new SyndicationClient();

    Uri feedUri
        = new Uri("http://windowsteamblog.com/windows/b/windowsexperience/atom.aspx");

    try
    {
        SyndicationFeed feed = await client.RetrieveFeedAsync(feedUri);

        // The rest of this method executes after await RetrieveFeedAsync completes.
        rssOutput.Text = feed.Title.Text + Environment.NewLine;

        foreach (SyndicationItem item in feed.Items)
        {
            rssOutput.Text += item.Title.Text + ", " +
                             item.PublishedDate.ToString() + Environment.NewLine;
        }
    }
    catch (Exception ex)
    {
        // Log Error.
        rssOutput.Text =
            "I'm sorry, but I couldn't load the page," +
            " possibly due to network problems." +
            "Here's the error message I received: "
            + ex.ToString();
    }
}
' Put the keyword Async on the declaration of the event handler.
Private Async Sub Button_Click_1(sender As Object, e As RoutedEventArgs)

    Dim client As New Windows.Web.Syndication.SyndicationClient()

    Dim feedUri As New Uri("http://windowsteamblog.com/windows/b/windowsexperience/atom.aspx")

    Try

        Dim feed As SyndicationFeed = Await client.RetrieveFeedAsync(feedUri)

        ' The rest of this method executes after the await operation completes.
        rssOutput.Text = feed.Title.Text & vbCrLf

        For Each item In feed.Items

            rssOutput.Text += item.Title.Text & ", " &
                              item.PublishedDate.ToString() & vbCrLf

        Next item


    Catch ex As Exception

        ' Log Error.
        rssOutput.Text = "I'm sorry, but I couldn't load the page," &
                         " possibly due to network problems." &
                         "Here's the error message I received: " &
                          ex.ToString()


    End Try

End Sub

Plusieurs points importants sont à signaler dans cet exemple.There are a couple of important things about this example. En premier lieu, notez que la ligne SyndicationFeed feed = await client.RetrieveFeedAsync(feedUri) utilise l’opérateur await avec un appel à la méthode asynchrone RetrieveFeedAsync.First, the line, SyndicationFeed feed = await client.RetrieveFeedAsync(feedUri) uses the await operator with the call to the asynchronous method, RetrieveFeedAsync. Vous pouvez voir l’opérateur await comme un moyen d’indiquer au compilateur que vous appelez une méthode asynchrone, ce qui oblige le compilateur à effectuer des opérations supplémentaires à votre place.You can think of the await operator as telling the compiler that you are calling an asynchronous method, which causes the compiler to do some extra work so you don’t have to. En second lieu, notez que la déclaration du gestionnaire d’événements inclut le mot clé async.Next, the declaration of the event handler includes the keyword async. Vous devez inclure ce mot clé dans la déclaration de chaque méthode dans laquelle vous utilisez l’opérateur await.You must include this keyword in the method declaration of any method in which you use the await operator.

Dans cette rubrique, nous n’allons pas expliquer en détail la manière dont le compilateur utilise l’opérateur await. Nous allons plutôt nous attacher à comprendre comment votre application peut rester asynchrone et réactive.In this topic, we won't go into a lot of the details of what the compiler does with the await operator, but let's examine what your app does so that it is asynchronous and responsive. Observons ce qui se produit avec du code synchrone.Consider what happens when you use synchronous code. Par exemple, imaginons qu’il y ait une méthode synchrone appelée SyndicationClient.RetrieveFeed.For example, suppose that there is a method called SyndicationClient.RetrieveFeed that is synchronous. (Il n’existe pas de méthode de ce type, mais imaginez qu’il y en a.) Si votre application incluait la ligne SyndicationFeed feed = client.RetrieveFeed(feedUri), au lieu de SyndicationFeed feed = await client.RetrieveFeedAsync(feedUri), l’exécution de l’application s’arrêtera jusqu’à ce que la valeur de retour de RetrieveFeed soit disponible.(There is no such method, but imagine that there is.) If your app included the line SyndicationFeed feed = client.RetrieveFeed(feedUri), instead of SyndicationFeed feed = await client.RetrieveFeedAsync(feedUri), execution of the app would stop until the return value of RetrieveFeed is available. Pendant que l’application attend la fin de la méthode, elle ne peut plus répondre à d’autres événements (un deuxième événement Click, par exemple).And while your app waits for the method to complete, it can't respond to any other events, such another Click event. En clair, votre application resterait bloquée jusqu’au renvoi du résultat de RetrieveFeed.That is, your app would be blocked until RetrieveFeed returns.

En revanche, si vous appelez client.RetrieveFeedAsync, la méthode initie la récupération et renvoie immédiatement le résultat.But if you call client.RetrieveFeedAsync, the method initiates the retrieval and immediately returns. Lorsque vous utilisez l’opérateur await avec RetrieveFeedAsync, l’application ferme temporairement le gestionnaire d’événements.When you use await with RetrieveFeedAsync, the app temporarily exits the event handler. Elle peut ensuite gérer d’autres événements en même temps que la méthode RetrieveFeedAsync s’exécute de manière asynchrone.Then it can process other events while RetrieveFeedAsync executes asynchronously. Ainsi, l’application reste réactive aux interactions utilisateur.This keeps the app responsive to the user. Lorsque la méthode RetrieveFeedAsync est terminée et que SyndicationFeed est disponible, l’application rouvre le gestionnaire d’événements là où elle l’avait fermé, après SyndicationFeed feed = await client.RetrieveFeedAsync(feedUri), et finit l’exécution de la méthode.When RetrieveFeedAsync completes and the SyndicationFeed is available, the app essentially reenters the event handler where it left off, after SyndicationFeed feed = await client.RetrieveFeedAsync(feedUri), and finishes the rest of the method.

Vous pouvez constater que le code obtenu avec l’opérateur await se présente à peu près de la même façon que le code obtenu avec la méthode fictive RetrieveFeed.The nice thing about using the await operator is that the code doesn't look much different from how the code looks if you used the imaginary RetrieveFeed method. Il est possible d’écrire du code asynchrone en C# ou Visual Basic sans utiliser l’opérateur await, mais le code obtenu a tendance à mettre en évidence les mécanismes de l’exécution de code asynchrone.There are ways to write asynchronous code in C# or Visual Basic without the await operator, but the resulting code tends to emphasize the mechanics of executing asynchronously. Cela rend l’écriture, la compréhension et la gestion du code asynchrone difficiles.This makes asynchronous code hard to write, hard to understand, and hard to maintain. En utilisant l’opérateur await, vous bénéficiez des avantages d’une application asynchrone, sans avoir l’inconvénient de voir votre code devenir plus complexe.By using the await operator, you get the benefits of an asynchronous app without making your code complex.

Types de retour et résultats des API asynchronesReturn types and results of asynchronous APIs

Si vous avez suivi le lien vers RetrieveFeedAsync, vous avez peut-être constaté que le type de retour de RetrieveFeedAsync n’est pas SyndicationFeed,If you followed the link to RetrieveFeedAsync, you might have noticed that the return type of RetrieveFeedAsync is not a SyndicationFeed. À la place, le type de retour est IAsyncOperationWithProgress<SyndicationFeed, RetrievalProgress>.Instead, the return type is IAsyncOperationWithProgress<SyndicationFeed, RetrievalProgress>. Du point de vue de la syntaxe brute, une API asynchrone retourne un objet qui contient le résultat.Viewed from the raw syntax, an asynchronous API returns an object that contains the result within it. Même s’il est courant, et parfois utile, de traiter une méthode asynchrone comme un élément « awaitable », l’opérateur await s’applique à la valeur renvoyée de la méthode, et pas à la méthode proprement dite.While it is common, and sometimes useful, to think of an asynchronous method as being awaitable, the await operator actually operates on the method’s return value, not on the method. Lorsque vous appliquez l’opérateur await, vous obtenez le résultat de l’appel à GetResult sur l’objet renvoyé par la méthode.When you apply the await operator, what you get back is the result of calling GetResult on the object returned by the method. Dans l’exemple, SyndicationFeed est le résultat de RetrieveFeedAsync.GetResult() .In the example, the SyndicationFeed is the result of RetrieveFeedAsync.GetResult().

Lorsque vous utilisez une méthode asynchrone, vous pouvez examiner la signature pour voir ce que vous obtiendrez après avoir attendu la valeur renvoyée par la méthode.When you use an asynchronous method, you can examine the signature to see what you’ll get back after awaiting the value returned from the method. Toutes les API asynchrones de l’UWP renvoient l’un des types suivants :All asynchronous APIs in the UWP return one of the following types:

Une méthode asynchrone renvoie un résultat qui est du même type que le paramètre de type TResult.The result type of an asynchronous method is the same as the TResult type parameter. Les types sans TResult ne renvoient aucun résultat.Types without a TResult don't have a result. Vous pouvez considérer que le résultat est de type void.You can think of the result as being void. En Visual Basic, une procédure Sub est équivalente à une méthode ayant un résultat de type void.In Visual Basic, a Sub procedure is equivalent to a method with a void return type.

Le tableau ci-dessous donne quelques exemples de méthodes asynchrones, en indiquant leur type de retour et leur type de résultat respectifs.The table here gives examples of asynchronous methods and lists the return type and result type of each.

Méthode asynchroneAsynchronous method Type de retourReturn type Type de résultatResult type
SyndicationClient. RetrieveFeedAsyncSyndicationClient.RetrieveFeedAsync IAsyncOperationWithProgress @ no__t-2SyndicationFeed, RetrievalProgress @ no__t-3IAsyncOperationWithProgress<SyndicationFeed, RetrievalProgress> SyndicationFeedSyndicationFeed
FileOpenPicker. PickSingleFileAsyncFileOpenPicker.PickSingleFileAsync IAsyncOperation @ no__t-2StorageFile @ no__t-3IAsyncOperation<StorageFile> StorageFileStorageFile
XmlDocument. SaveToFileAsyncXmlDocument.SaveToFileAsync IAsyncActionIAsyncAction voidvoid
InkStrokeContainer. LoadAsyncInkStrokeContainer.LoadAsync IAsyncActionWithProgress @ no__t-2UInt64 @ no__t-3IAsyncActionWithProgress<UInt64> voidvoid
DataReader. LoadAsyncDataReader.LoadAsync DataReaderLoadOperation, classe de résultats personnalisée qui implémente IAsyncOperation @ no__t-3UInt32 @ no__t-4DataReaderLoadOperation, a custom results class that implements IAsyncOperation<UInt32> UInt32UInt32

 

Les méthodes asynchrones définies dans .NET for UWP apps ont le type de retour Task ou Task<TResult> .Asynchronous methods that are defined in .NET for UWP apps have the return type Task or Task<TResult>. Les méthodes qui renvoient Task sont similaires aux méthodes asynchrones dans l’UWP qui renvoient IAsyncAction.Methods that return Task are similar to the asynchronous methods in the UWP that return IAsyncAction. Dans chaque cas, le résultat de la méthode asynchrone est de type void.In each case, the result of the asynchronous method is void. Le type de retour Task<TResult> est similaire à IAsyncOperation<TResult> dans la mesure où le résultat de la méthode asynchrone lors de l’exécution de la tâche est du même type que le paramètre de type TResult.The return type Task<TResult> is similar to IAsyncOperation<TResult> in that the result of the asynchronous method when running the task is the same type as the TResult type parameter. Pour plus d’informations sur l’utilisation de .NET for UWP apps et des tâches, voir Présentation de .NET pour les applications Windows Runtime.For more info about using .NET for UWP apps and tasks, see .NET for Windows Runtime apps overview.

Gestion des erreursHandling errors

Quand vous utilisez l’opérateur await pour récupérer les résultats d’une méthode asynchrone, vous pouvez utiliser un bloc try/catch pour gérer les erreurs qui se produisent dans des méthodes asynchrones, exactement comme vous le faites pour les méthodes synchrones.When you use the await operator to retrieve your results from an asynchronous method, you can use a try/catch block to handle errors that occur in asynchronous methods, just as you do for synchronous methods. L’exemple précédent encapsule la méthode RetrieveFeedAsync et l’opération await dans un bloc try/catch pour gérer les erreurs quand une exception est levée.The previous example wraps the RetrieveFeedAsync method and await operation in a try/catch block to handle errors when an exception is thrown.

Quand des méthodes asynchrones appellent d’autres méthodes asynchrones, toute méthode asynchrone qui entraîne une exception est propagée aux méthodes externes.When asynchronous methods call other asynchronous methods, any asynchronous method that results in an exception will be propagated to the outer methods. Cela signifie que vous pouvez placer un bloc try/catch dans la méthode la plus externe pour détecter les erreurs relatives aux méthodes asynchrones imbriquées.This means that you can put a try/catch block on the outer-most method to catch errors for the nested asynchronous methods. À nouveau, cette opération est similaire à la façon dont vous détectez les exceptions pour les méthodes synchrones.Again, this is similar to how you catch exceptions for synchronous methods. Toutefois, vous ne pouvez pas utiliser await dans le bloc catch.However, you can't use await in the catch block.

Conseil  Starting avec C# dans Microsoft Visual Studio 2005, vous pouvez utiliser await dans le bloc catch .Tip  Starting with C# in Microsoft Visual Studio 2005, you can use await in the catch block.

Récapitulatif et étapes suivantesSummary and next steps

Le modèle qui a été utilisé dans cette rubrique pour appeler une méthode asynchrone est le modèle le plus simple permettant d’appeler des API asynchrones dans un gestionnaire d’événements.The pattern of calling an asynchronous method that we show here is the simplest one to use when you call asynchronous APIs in an event handler. Vous pouvez également utiliser ce modèle pour appeler une méthode asynchrone dans une méthode remplacée qui renvoie void, ou Sub en Visual Basic.You can also use this pattern when you call an asynchronous method in an overridden method that returns void or a Sub in Visual Basic.

En ce qui concerne les méthodes asynchrones fournies dans l’UWP, il est important de garder à l’esprit les points suivants :As you encounter asynchronous methods in the UWP, it is important to remember:

  • Par convention, les noms attribués aux méthodes asynchrones se terminent par « Async ».By convention, asynchronous methods are given names that end in "Async".
  • Toute méthode qui utilise l’opérateur await doit avoir sa déclaration marquée avec le mot cléasync.Any method that uses the await operator must have its declaration marked with the async keyword.
  • Lorsqu’une application trouve l’opérateur await, elle demeure réactive aux interactions utilisateur pendant la durée d’exécution de la méthode asynchrone.When an app finds the await operator, the app remains responsive to user interaction while the asynchronous method executes.
  • L’attente de la valeur renvoyée par une méthode asynchrone renvoie un objet contenant le résultat.Awaiting the value returned by an asynchronous method returns an object that contains the result. Dans la plupart des cas, le résultat contenu dans la valeur renvoyée correspond à des informations utiles, pas à la valeur renvoyée proprement dite.In most cases, the result contained within the return value is what's useful, not the return value itself. Vous pouvez déterminer le type de la valeur contenue dans le résultat en observant le type de retour de la méthode asynchrone.You can find the type of the value that is contained inside the result by looking at the return type of the async method.
  • Les API asynchrones et les modèles async s’avèrent souvent utiles pour améliorer la réactivité de votre application.Using asynchronous APIs and async patterns is often a way to improve the responsiveness of your app.

L’exemple de cette rubrique produit un résultat similaire au texte ci-dessous.The example in this topic outputs text that looks like this.

Windows Experience Blog
PC Snapshot: Sony VAIO Y, 8/9/2011 10:26:56 AM -07:00
Tech Tuesday Live Twitter #Chat: Too Much Tech #win7tech, 8/8/2011 12:48:26 PM -07:00
Windows 7 themes: what’s new and what’s popular!, 8/4/2011 11:56:28 AM -07:00
PC Snapshot: Toshiba Satellite A665 3D, 8/2/2011 8:59:15 AM -07:00
Time for new school supplies? Find back-to-school deals on Windows 7 PCs and Office 2010, 8/1/2011 2:14:40 PM -07:00
Best PCs for blogging (or working) on the go, 8/1/2011 10:08:14 AM -07:00
Tech Tuesday – Blogging Tips and Tricks–#win7tech, 8/1/2011 9:35:54 AM -07:00
PC Snapshot: Lenovo IdeaPad U460, 7/29/2011 9:23:05 AM -07:00
GIVEAWAY: Survive BlogHer with a Sony VAIO SA and a Samsung Focus, 7/28/2011 7:27:14 AM -07:00
3 Ways to Stay Cool This Summer, 7/26/2011 4:58:23 PM -07:00
Getting RAW support in Photo Gallery & Windows 7 (…and a contest!), 7/26/2011 10:40:51 AM -07:00
Tech Tuesdays Live Twitter Chats: Photography Tips, Tricks and Essentials, 7/25/2011 12:33:06 PM -07:00
3 Tips to Go Green With Your PC, 7/22/2011 9:19:43 AM -07:00
How to: Buy a Green PC, 7/22/2011 9:13:22 AM -07:00
Windows 7 themes: the distinctive artwork of Cheng Ling, 7/20/2011 9:53:07 AM -07:00