{"id":88,"date":"2020-04-28T13:33:56","date_gmt":"2020-04-28T20:33:56","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/azure-sdk\/?p=88"},"modified":"2020-06-12T15:05:05","modified_gmt":"2020-06-12T22:05:05","slug":"how-to-use-cancellationtokens-to-cancel-tasks-in-the-azure-sdk-for-net","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/azure-sdk\/how-to-use-cancellationtokens-to-cancel-tasks-in-the-azure-sdk-for-net\/","title":{"rendered":"How to use CancellationTokens to cancel tasks in the Azure SDK for .NET"},"content":{"rendered":"

The ability to cancel long-running tasks is important to help keep applications responsive. Whether the network connection is slow or disconnects, or the user just wants to cancel a long task, using a CancellationToken<\/code><\/a> in .NET makes it easy to cancel those long tasks. Together with a CancellationTokenSource<\/code><\/a>, a developer can provide on-demand or timed cancellations of tasks that accept a CancellationToken<\/code>, like our client methods<\/a> in the Azure SDK for .NET.<\/p>\n

Using CancellationTokens<\/h2>\n

Prior to the introduction of the CancellationToken<\/code><\/a> structure in .NET Framework 4.0, it was common to use one or more WaitHandle<\/code> objects to synchronize threads. This same pattern has been used in native Windows applications for decades. When the asynchronous task pattern was introduced in .NET, a new, simpler pattern for cancelling tasks was also introduced. While a CancellationToken<\/code> can still provide a WaitHandle<\/code> to synchronize threads, creating tokens and passing them to methods is much easier:<\/p>\n

CancellationTokenSource cts = new CancellationTokenSource();\nKeyVaultSecret secret = await secretClient.GetSecretAsync(\"my-secret\", cts.Token);\n<\/code><\/pre>\n
CancellationTokenSource.Token<\/code> returns a CancellationToken<\/code> that can be passed to other methods further down the call stack, or even on other threads. When those tokens are canceled, any methods waiting on them should throw an OperationCanceledException<\/code>. Methods accepting a CancellationToken<\/code> don’t even have to be asynchronous. Our synchronous client methods in the Azure SDK for .NET also accept a CancellationToken<\/code>. In both synchronous or asynchronous code, you can simply call CancellationToken.ThrowIfCancellationRequested()<\/code> to immediately throw if the token was in a canceled state.<\/p>\n
public void DoWork(CancellationToken cancellationToken = default)\n{\n    cancellationToken.ThrowIfCancellationRequested();\n\n    \/\/ Start long-running task...\n}\n<\/code><\/pre>\n
Notice that we didn’t have to check if cancellationToken<\/code> was null. As a value type in .NET, it cannot be null and even defined as its default value, CancellationToken.ThrowIfCancellationRequested()<\/code> will simply do nothing.<\/p>\n
If you don’t want to throw an exception but still want to check if a token was cancelled, you can check the CancellationToken.IsCancellationRequested<\/code> property.<\/p>\n
Cancelling CancellationTokens<\/h2>\n
You’ve seen a few ways to pass and use a CancellationToken<\/code><\/a>, but how do you actually cancel them? That ability is supported by the CancellationTokenSource<\/code><\/a>. A CancellationTokenSource<\/code> can cancel tokens on demand or after a certain amount of time:<\/p>\n
CancellationTokenSource cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));\nConsole.CancelKeyPress += (source, args) =>\n{\n    Console.Error.WriteLine(\"Cancelling download...\");\n\n    args.Cancel = true;\n    cts.Cancel();\n};\n\nConsole.WriteLine(\"Downloading to {0}...\", path);\n\ntry\n{\n    using (Stream fs = File.Create(path))\n    await blobClient.DownloadToAsync(fs, cts.Token);\n}\ncatch (OperationCanceledException)\n{\n    Console.Error.WriteLine(\"Download canceled. Deleting {0}...\", path);\n    File.Delete(path);\n}\n<\/code><\/pre>\n
We created a CancellationTokenSource<\/code> that will cancel all its tokens after 30 seconds, and also hooked up a handler for pressing Ctrl+C<\/strong> in this sample console application. This way, we provide flexibility to the user to cancel the task whenever they want, and also cancel the task if it takes too long, which might indicate a network error if a suitable timeout is chosen. If the download is cancelled, we can handle the OperationCanceledException<\/code> to delete the file in case it was partially downloaded.<\/p>\n
Cancelling Long-running Operations in Azure SDK<\/h2>\n
A subtle but important distinction is that long-running operations (LROs) in Azure SDK often refer to specific classes like CertificateOperation<\/code><\/a>. After methods that return LROs like StartCreateCertificateAsync<\/code><\/a> have completed, canceling a CancellationToken<\/code> passed to any methods like CertificateOption.UpdateStatusAsync<\/code> only cancels waiting on that method. To cancel an LRO, you need to call Cancel<\/code> or CancelAsync<\/code> on the LRO to actually cancel the operation.<\/p>\n
CertificateOperation op = await certificateClient.StartCreateCertificateAsync(\"my-certificate\", certificatePolicy);\n\n\/\/ After some time, user decides to cancel certificate creation.\nawait op.CancelAsync();\n<\/code><\/pre>\n
These long-running operations (LROs) can often take longer than most programs are expected to run. Creating a certificate, for example, could take days of approvals. These LROs can be recreated – like in this example, using the pending certificate name – and code can continue to wait or cancel them later.<\/p>\n
Advanced uses<\/h2>\n
Despite its simple design, a CancellationToken<\/code><\/a> can be used in a number of other scenarios.<\/p>\n
Doing additional work when canceled<\/h3>\n
Canceling any current or pending work is a typical scenario when a CancellationToken<\/code> is canceled. In some scenarios, you might need to do some clean up only when canceled. For this reason, you can register a delegate to run only when the CancellationToken<\/code> is canceled. Registering a delegate returns an IDisposable<\/code> which can be disposed to unregister the delegate if no longer needed. We could log a message, for example, that a method was canceled without worrying where in code to write the message:<\/p>\n
public async Task DoWorkAsync(CancellationToken cancellationToken = default)\n{\n    using (CancellationTokenRegistration  cts = cancellationToken.Register(() =>\n    {\n        Console.Error.WriteLine(\"The task was cancelled.\");\n    }))\n    {\n        \/\/ Start long-running task...\n    }\n}\n<\/code><\/pre>\n
Linking CancellationTokens<\/h3>\n
There may be times when you have a group of tasks you want to cancel individually or all together, for example downloading as many files as possible and reporting on those that failed. You can link a CancellationToken<\/code> to a new CancellationTokenSource<\/code> so that when that original CancellationToken<\/code> is canceled, any tokens created from a linked CancellationTokenSource<\/code> are canceled:<\/p>\n
public async Task DownloadAsync(Uri uri, CancellationToken cancellationToken = default)\n{\n    using (CancellationTokenSource cts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken))\n    {\n        cts.CancelAfter(TimeSpan.FromSeconds(30));\n\n        \/\/ Download file ...\n    }\n}\n<\/code><\/pre>\n
It’s important to note that linked CancellationToken<\/code>s only work in one direction: canceling a CancellationToken<\/code> from a linked CancellationTokenSource<\/code> does not cancel the original CancellationToken<\/code>.<\/p>\n
Waiting on handles<\/h3>\n
You can also use a CancellationToken<\/code> with code that requires waiting on one or more WaitHandle<\/code><\/a> objects. This may be common for older applications or when interoperating with native code like with P\/Invoke. The CancellationToken.WaitHandle<\/code> can be used in calls like WaitHandle.WaitAny<\/code>:<\/p>\n
AutoResetEvent evt = new AutoResetEvent(false);\nThreadPool.QueueUserWorkItem(state => DoWork(state, evt));\n\nint which = WaitHandle.WaitAny(new WaitHandle[] { evt, cancellationToken.WaitHandle});\nif (which == 1)\n{\n    Console.Error.WriteLine(\"The task was canceled.\");\n}\n<\/code><\/pre>\n
Updating APIs for older applications to use newer classes like CancellationToken<\/code> may help when upgrading to newer components.<\/p>\n
Further reading<\/h2>\n