{"id":464,"date":"2014-06-04T22:36:00","date_gmt":"2014-06-04T22:36:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/webdev\/2014\/06\/04\/queuebackgroundworkitem-to-reliably-schedule-and-run-background-processes-in-asp-net\/"},"modified":"2022-08-08T07:28:32","modified_gmt":"2022-08-08T14:28:32","slug":"queuebackgroundworkitem-to-reliably-schedule-and-run-background-processes-in-asp-net","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/dotnet\/queuebackgroundworkitem-to-reliably-schedule-and-run-background-processes-in-asp-net\/","title":{"rendered":"QueueBackgroundWorkItem to reliably schedule and run background processes in ASP.NET"},"content":{"rendered":"

Stack Overflow is loaded with questions on how to reliably run a resource-intensive process on a background thread. See  so0<\/a>, so1<\/a>, so2<\/a>, so3<\/a>, so4<\/a>, so5<\/a>, so6<\/a>, so7<\/a>, so8<\/a>, so9<\/a>, so10<\/a> . Examples of long-running tasks include sending email, image processing, and generating a PDF file. When Phil Haack<\/a> was a program manager on the ASP.NET MVC team, he wrote the definitive blog on the inherent unreliability of running background tasks on ASP.NET<\/a>. While Phil\u2019s blog is a good read, there are now three supported approaches to launching long-running process on ASP.NET:<\/p>\n

    \n
  1. Cloud Services worker role is an environment<\/em> in which you can run code. It\u2019s basically a computer, really. You run whatever code you want (EXE, BAT, PS1, NodeJS, .NET, etc.)  An Azure worker role provides the most industrial strength and scalable solution to this problem.  For an excellent tutorial with this approach, see Tom Dykstra\u2019s Get Started with Azure Cloud Services and ASP.NET<\/a>. <\/li>\n
  2. WebJobs<\/a> (including the WebJobs SDK) are a way in Azure to run scheduled tasks or tasks that trigger on demand (given various types of triggers). Apps specifically written with the Azure Jobs SDK can be used to run code in any environment, including a local computer, Azure Web Site, Azure Worker Role, Azure VM, etc.  Although you can run them anywhere, they run most efficiently within Azure. For more information see Azure WebJobs – Recommended Resources<\/a>. <\/li>\n
  3. QueueBackgroundWorkItem (QBWI). This was specifically added to enable ASP.NET apps to reliably run short-lived background tasks. (With some limitations explained at the end of this blog.)    As of today, you can\u2019t use QBWI on an Azure Web Site or Cloud Services web role because QBWI requires .Net 4.5.2. We hope to have Azure Web\/Cloud running .Net 4.5.2 soon. <\/li>\n<\/ol>\n

    In addition to the three supported approaches above, the open source HangFire<\/a> package allows you to run background tasks.<\/p>\n

    QueueBackgroundWorkItem overview<\/h2>\n

    QBWI schedules a task which can run in the background, independent of any request. This differs from a normal ThreadPool work item in that ASP.NET automatically keeps track of how many work items registered through this API are currently running, and the ASP.NET runtime will try<\/em><\/strong> to delay AppDomain<\/a> shutdown until these work items have finished executing.<\/p>\n

    QueueBackgroundWorkItem API<\/h2>\n

    [SecurityPermission(SecurityAction.LinkDemand, Unrestricted =<\/span>true<\/span>)]
    <\/span>public static void <\/span>QueueBackgroundWorkItem(Action<CancellationToken> workItem);<\/span><\/p>\n

    Takes a void-returning callback; the work item will be considered finished when the callback returns.<\/p>\n

    [SecurityPermission(SecurityAction.LinkDemand, Unrestricted = <\/span>true<\/span>)] 
    <\/span>public static void <\/span>QueueBackgroundWorkItem(Func<CancellationToken, Task> workItem);<\/span><\/pre>\n
    Takes a Task<\/a> returning callback; the work item will be considered finished when the returned Task transitions to a terminal state.<\/p>\n
    Send email with attachment using QBWI<\/h2>\n
    To use QBWI (QueueBackgroundWorkItem) in Visual Studio, you\u2019ll need to install .Net 4.5.2<\/a>, then install the .Net 4.5.2 Developer Pack<\/a>. For my sample I created an MVC app and used SendGrid<\/a> to send an email with a large jpg attachment. To use QBWI, you\u2019ll need to right click the project in solution explore and select Properties<\/strong>. Select the Application<\/strong> tab on the left, then select .Net Framework 4.5.2<\/strong> in the Target Framework<\/strong> dropdown. If you don\u2019t see 4.5.2, you didn\u2019t install the .Net 4.5.2 Developer Pack<\/a> or you don\u2019t have .Net 4.5.2 installed.<\/p>\n
    \"netVers\"<\/a><\/p>\n
    The following code sends email with an image file attached:<\/p>\n
     <\/span>public <\/span>ActionResult <\/span>SendEmail2([<\/span>Bind<\/span>(Include = <\/span>"Name,Email"<\/span>)] <\/span>User <\/span>user)\r\n {\r\n    <\/span>if <\/span>(ModelState.IsValid)\r\n    {\r\n       <\/span>HostingEnvironment<\/span>.QueueBackgroundWorkItem(ct => SendMailAsync(user.Email));\r\n       <\/span>return <\/span>RedirectToAction(<\/span>"Index"<\/span>, <\/span>"Home"<\/span>);\r\n    }\r\n\r\n    <\/span>return <\/span>View(user);\r\n }   \r\n\r\n <\/span>private async <\/span>Task <\/span>SendMailAsync(<\/span>string <\/span>email)\r\n {\r\n    <\/span>var <\/span>myMessage = <\/span>new <\/span>SendGridMessage<\/span>();\r\n\r\n    myMessage.From = <\/span>new <\/span>MailAddress<\/span>(<\/span>"Rick@Contoso.com"<\/span>);\r\n    myMessage.AddTo(email);\r\n    myMessage.Subject = <\/span>"Using QueueBackgroundWorkItem"<\/span>;\r\n\r\n    <\/span>\/\/Add the HTML and Text bodies\r\n    <\/span>myMessage.Html = <\/span>"<p>Check out my new blog at "\r\n          <\/span>+ <\/span>"<a href="http:\/\/blogs.msdn.com\/b\/webdev\/">"\r\n          <\/span>+ <\/span>"http:\/\/blogs.msdn.com\/b\/webdev\/<\/a><\/p>"<\/span>;\r\n    myMessage.Text = <\/span>"Check out my new blog at http:\/\/blogs.msdn.com\/b\/webdev\/"<\/span>;\r\n\r\n    <\/span>using <\/span>(<\/span>var <\/span>attachmentFS = <\/span>new <\/span>FileStream<\/span>(<\/span>GH<\/span>.FilePath, <\/span>FileMode<\/span>.Open))\r\n    {\r\n       myMessage.AddAttachment(attachmentFS, <\/span>"My Cool File.jpg"<\/span>);\r\n    }\r\n\r\n    <\/span>var <\/span>credentials = <\/span>new <\/span>NetworkCredential<\/span>(\r\n       <\/span>ConfigurationManager<\/span>.AppSettings[<\/span>"mailAccount"<\/span>],\r\n       <\/span>ConfigurationManager<\/span>.AppSettings[<\/span>"mailPassword"<\/span>]\r\n       );\r\n\r\n    <\/span>\/\/ Create a Web transport for sending email.\r\n    <\/span>var <\/span>transportWeb = <\/span>new <\/span>Web<\/span>(credentials);\r\n\r\n    <\/span>if <\/span>(transportWeb != <\/span>null<\/span>)\r\n       <\/span>await <\/span>transportWeb.DeliverAsync(myMessage);\r\n }<\/span><\/pre>\n
    <\/a><\/p>\n
    I set the account and password on the Configure <\/strong>tab in the Azure portal to keep my credentials secure.<\/p>\n
    \"conTab\"<\/a><\/p>\n
    Using the cancellation token<\/h2>\n
    You can drop the following code in a new MVC app to test the cancellation token:<\/p>\n
    public class <\/span>HomeController <\/span>: <\/span>Controller\r\n<\/span>{\r\n   <\/span>static int <\/span>logCount = 0;\r\n   <\/span>public <\/span>ActionResult <\/span>Index()\r\n   {\r\n      <\/span>return <\/span>View();\r\n   }\r\n\r\n   <\/span>public <\/span>ActionResult <\/span>About()\r\n   {\r\n      ViewBag.Message = <\/span>"Your application description page."<\/span>;\r\n      <\/span>HostingEnvironment<\/span>.QueueBackgroundWorkItem(ct => workItemAction1(ct, <\/span>"About"<\/span>));\r\n      <\/span>return <\/span>View();\r\n   }\r\n\r\n   <\/span>public <\/span>ActionResult <\/span>Contact()\r\n   {\r\n      ViewBag.Message = <\/span>"Your contact page."<\/span>;\r\n      <\/span>string <\/span>info = <\/span>"Headers: " <\/span>+ HttpContext.Request.Headers.AllKeys.ToString()\r\n              + <\/span>"  URI: " <\/span>+ HttpContext.Request.Url.AbsoluteUri.ToString()\r\n              + <\/span>" User: " <\/span>+ HttpContext.User.ToString();\r\n\r\n      <\/span>HostingEnvironment<\/span>.QueueBackgroundWorkItem(ct => workItem1Async(ct, <\/span>"Contact"<\/span>));\r\n      <\/span>return <\/span>View();\r\n   }\r\n\r\n   <\/span>private void <\/span>workItemAction1(<\/span>CancellationToken <\/span>ct, <\/span>string <\/span>msg)\r\n   {\r\n      logCount++;\r\n      <\/span>int <\/span>currentLogCount = logCount;\r\n\r\n      ct = addLog(ct, currentLogCount, msg);\r\n   }\r\n\r\n   <\/span>private async <\/span>Task<\/span><<\/span>CancellationToken<\/span>> workItem1Async(<\/span>CancellationToken <\/span>ct, <\/span>string <\/span>msg)\r\n   {\r\n      logCount++;\r\n      <\/span>int <\/span>currentLogCount = logCount;\r\n\r\n      <\/span>await <\/span>addLogAsync(ct, currentLogCount, msg);\r\n      <\/span>return <\/span>ct;\r\n   }\r\n\r\n   <\/span>private <\/span>CancellationToken <\/span>addLog(<\/span>CancellationToken <\/span>ct, <\/span>int <\/span>currentLogCount, <\/span>string <\/span>msg)\r\n   {\r\n      <\/span>Trace<\/span>.TraceInformation(msg);\r\n\r\n      <\/span>for <\/span>(<\/span>int <\/span>i = 0; i < 5; i++)\r\n      {\r\n         <\/span>if <\/span>(ct.IsCancellationRequested)\r\n         {\r\n            <\/span>Trace<\/span>.TraceWarning(<\/span>string<\/span>.Format(<\/span>"{0} - signaled cancellation"<\/span>, \r\n               <\/span>DateTime<\/span>.Now.ToLongTimeString()));\r\n            <\/span>break<\/span>;\r\n         }\r\n         <\/span>Trace<\/span>.TraceInformation(<\/span>string<\/span>.Format(<\/span>"{0} - logcount:{1}"<\/span>, \r\n            <\/span>DateTime<\/span>.Now.ToLongTimeString(), currentLogCount));\r\n         <\/span>Thread<\/span>.Sleep(6000);\r\n      }\r\n      <\/span>return <\/span>ct;\r\n   }\r\n\r\n   <\/span>private async <\/span>Task<\/span><<\/span>CancellationToken<\/span>> addLogAsync(\r\n      <\/span>CancellationToken <\/span>ct, <\/span>int <\/span>currentLogCount, <\/span>string <\/span>msg)\r\n   {\r\n\r\n      <\/span>try\r\n      <\/span>{\r\n         <\/span>for <\/span>(<\/span>int <\/span>i = 0; i < 5; i++)\r\n         {\r\n            <\/span>if <\/span>(ct.IsCancellationRequested)\r\n            {\r\n               <\/span>Trace<\/span>.TraceWarning(<\/span>string<\/span>.Format(<\/span>"{0} - signaled cancellation : msg {1}"<\/span>,\r\n                  <\/span>DateTime<\/span>.Now.ToLongTimeString(), msg));\r\n               <\/span>break<\/span>;\r\n            }\r\n            <\/span>Trace<\/span>.TraceInformation(<\/span>string<\/span>.Format(<\/span>"{0} - msg:{1} - logcount:{2}"<\/span>,\r\n               <\/span>DateTime<\/span>.Now.Second.ToString(), msg, currentLogCount));\r\n\r\n            <\/span>\/\/ "Simulate" this operation took a long time, but was able to run without\r\n            \/\/ blocking the calling thread (i.e., it's doing I\/O operations which are async)\r\n            \/\/ We use Task.Delay rather than Thread.Sleep, because Task.Delay returns\r\n            \/\/ the thread immediately back to the thread-pool, whereas Thread.Sleep blocks it.\r\n            \/\/ Task.Delay is essentially the asynchronous version of Thread.Sleep:\r\n            <\/span>await <\/span>Task<\/span>.Delay(2000, ct);\r\n         }\r\n      }\r\n      <\/span>catch <\/span>(<\/span>TaskCanceledException <\/span>tce)\r\n      {\r\n         <\/span>Trace<\/span>.TraceError(<\/span>"Caught TaskCanceledException - signaled cancellation " <\/span>+ tce.Message);\r\n      }\r\n      <\/span>return <\/span>ct;\r\n   }\r\n}<\/span><\/pre>\n
    <\/a><\/p>\n
    Hit F5 to debug the app, then click on the About<\/strong> or Contact<\/strong> link. Right click on the IIS Express icon in the task notification area and select Exit<\/strong>.<\/p>\n
    \"iisX\"<\/a><\/p>\n
    The visual studio output window shows the task is canceled.<\/p>\n
    \"out\"<\/a><\/p>\n
    QueueBackgroundWorkItem limitations<\/h2>\n