Skip to main content

Posts tagged with 'advent'

Merry Christmas! This is the last day of the C# Advent. Make sure to check out all of the other great posts from 2017 and 2018. If you want to be involved next year, look for C# Advent 2019 author sign ups at the end of October 2019, and look for blog posts to start showing up on December 1st, 2019.

What is a background job?

A background job is some code that runs apart from the normal flow of your program. It could be run asynchronously and/or on another thread. As an ASP.NET MVC developer, I tend to think of it as any task that runs outside of an MVC action being invoked.

There’s two kinds of background jobs that I’m aware of:

  • Scheduled - a task that runs every N minutes, or every Y hours, etc. This is what I’m going to show in this post today. It’s great for making periodic checks, ingesting data from some other source, etc.

  • Fire and forget - Some other piece of code kicks off a process to run in the background. It doesn’t block the code (fire), and the code doesn’t wait for a response (forget). This is great for potentially time consuming operations like checking inventory, sending emails, etc, that you don’t need a user to wait for.

What you usually need to do to create background jobs

In my experience, I’ve seen background jobs take a few different forms.

  1. Separate Windows service (or Linux daemon, whatever). A console/service program that’s running in addition to your ASP.NET program. This works fine for scheduled jobs.

  2. Queueing mechanisms like Kafka or Rabbit. The ASP.NET program will put messages into these queues, which will then be processed by some other program. This is fine for fire-and-forget.

  3. Background jobs running within the ASP.NET process itself. In my experience, I’ve used Quartz.NET, which can run within the ASP.NET process. There’s also FluentScheduler (which I’ve not used, and doesn’t seem to come with database integration out of the box?)

With all these options in the past, I’ve experienced deployment difficulties. The wrong version of the service gets deployed, or isn’t running, or fails silently, or needs to be deployed on multiple servers in order to provide scalability/availability etc. It’s totally possible to overcome these challenges, of course. (I should also note that in my experience with Quartz.NET, I never used it in embedded form, and the last time I used it was probably 6+ years ago).

But if I just need a handful of background jobs, I’d much rather just make them part of the ASP.NET system. Yes, maybe this goes against the whole 'microservice' idea, but I don’t think it would be too hard to refactor if you decided you need to go that route. I solve my deployment problems, and as you’ll see with Hangfire (with Couchbase), it’s very easy to scale.

How hangfire works

You can find more details and documentation about Hangfire at Hangfire.io. Really, there are only three steps to setting up Hangfire with ASP.NET Core:

  1. Tell ASP.NET Core about Hangfire

  2. Tell Hangfire which database to use

  3. Start firing off background jobs

In Startup.cs, in the ConfigureServices method:

services.AddHangfire(x => x.UseCouchbaseStorage(configuration, "familyPhotos_hangfire"));

Then, in Startup.cs, in the Configure method:

app.UseHangfireServer();

I’m using Couchbase in this example, but there are options for SQL Server and other databases too. I happen to think Couchbase is a great fit, because it can easily horizontally scale to grow with your ASP.NET Core deployments. It also has a memory-first architecture for low latency storage/retrieval of job data. Generally speaking, even if you use SQL Server as your "main" database, Couchbase makes a great companion to ASP.NET or ASP.NET Core as a cache, session store, or, in this case, backing for Hangfire.

The configuration variable is to tell Hangfire where to find Couchbase:

var configuration = new ClientConfiguration
{
    Servers = new List<Uri> { new Uri("http://localhost:8091") }
};
configuration.SetAuthenticator(new PasswordAuthenticator("hangfire", "password"));

(In my case, it’s just running locally).

Steps 1 and 2 are down. Next, step 3 is to create some background jobs for Hangfire to process. I’ve created an ASP.NET Core app to assist me in the cataloging of all my family photographs. I want my application to scan for new files every hour or so. Here’s how I create that job in Hangfire:

RecurringJob.AddOrUpdate("photoProcessor", () => processor.ProcessAll(), Cron.Hourly);

Note that I didn’t have to implement an IJob interface or anything like that. Hangfire will take any expression that you give it (at least, every expression that I’ve thrown at it so far).

Step 3 done.

Hangfire is just a NuGet package and not a separate process. So no additional deployment is needed.

How do I know it’s working?

Another great thing about Hangfire is that is comes with a built-in dashboard for the web. Back in Startup.cs, in Configure, add this code:

app.UseHangfireDashboard("/hangfire", new DashboardOptions
{
    Authorization = new[] {new HangfireAuthorization()}
});

I’m using my own HangfireAuthorization implementation because Hangfire only gives permission to local users by default.

Then, you get a nice dashboard right out of the box, showing you a realtime and history graph.

Hangfire dashboard

From this dashboard, you can also look at a more detailed history of what’s run and what’s failed.

Succeeded jobs

You can even kick off recurring jobs manually.

Recurring jobs

This is only the start

If you’re thinking about adding background jobs to your ASP.NET Core solution, why not give Hangfire a try?

Some more things for you to explore:

  • Scaling: every ASP.NET Core site that gets deployed with Hangfire that points to the same database will be able to process jobs too. As your ASP.NET Core site scales out, hangfire scales out with it. This is another reason that Couchbase is a good fit, because it’s also easy to scale out as your site grows.

  • Cloud: If you are deploying your site as an app service, note that Azure will shut down ASP.NET processes if they haven’t been used in a while. This means Hangfire will shut down with them. There are a couple of ways to deal with this. Check out the Hangfire documentation.

  • Retries: Hangfire will retry failed jobs. Design your background job code to expect this.

  • Hangfire Pro: The commercial version of Hangfire is called Hangfire.Pro, and it comes with some interesting looking batch capabilities. I’ve not needed any of this functionality yet, but for more advanced cases you might need this.

  • Couchbase: a NoSQL data platform that has a built-in memory-first cache layer, SQL support, text search, analytics, and more. There are lots of options for working with Couchbase in .NET. For this post, I used the Hangfire.Couchbase library (available on NuGet).

Last year's C# Advent was a success beyond anything I expected. I was worried that I wouldn't get enough sign-ups, but I ended up turning some people away. I was worried that people wouldn't get their blog posts done on time, but every single author delivered on time. I was worried there would be too much overlap in topics. There was a tiny bit, but every author's post had a unique, quality perspective, even if there was some overlap.

So, I'm doubling down this year! Each day of the Advent calendar will have up to TWO blog posts. That means that there is a maximum of FIFTY slots! So, tell your C# friends and let's fill up this calendar.

A little history: I heard about the F# Advent Calendar, a tradition that's been carried on since 2010 (2014 in English) and is still going strong in 2018. I think this is a great idea, and so I organized one for C#! (I asked Sergey Tihon for permission!). Other Advent calendars: C# Advent Calendar (in Spanish)Q# Advent Calendar.

So, I need you to write a C# blog post!

Here are the rules:

  1. Reserve a slot on Twitter (with hash tag #csadvent) or leave a comment on this post. You do not have to announce your topic until the day you reserve.
  2. Prepare a blog post (in English).
  3. Add a link in your blog post that links back to here, so that your readers may find the entire advent.
  4. Publish your blog post on the specified date. Your post must be related to C# in some way, but otherwise the content is completely up to you. I've posted a few ideas below to get your creativity flowing.
  5. Share your post on Twitter with hashtags #csharp and #csadvent

Below are all the slots, and who has claimed each date.

I will do my best to keep this up to date. The slots will be first come first serve. I also allowed last year's authors to get first crack. I have already claimed one of the December 25th slots for myself, but I can be persuaded to change if you really want that date.

DateClaimed byBlog Posts
Dec 1, 2018 Lukáš Lánský Steve Smith Namespacer: lightweight spin on architecture validation Double Dispatch in C# and DDD
Dec 2, 2018 Hilary Weaver-Robb Shahed Chowdhuri Can I Put All Of My Smoke Tests For A REST API In One Test? Yes! Your First Razor UI Library with ASP.NET Core
Dec 3, 2018 Bill Sempf Luis Antonio Beltran Insecure Binary Deserialization Azure Blob Storage with Xamarin.Forms
Dec 4, 2018 Tim Corey Matthew Jones How to Be a Great C# Developer Using Stopwatch and ContinueWith to Measure Task Execution Time in C#
Dec 5, 2018 James Hickey Calvin Allen Scalable Task Scheduling In .NET Core With Coravel Using .editorconfig in Visual Studio to create discoverable standards
Dec 6, 2018 Brant Burnett Isaac Levin A Restful Job Pattern For A C# Microservice Six Opinionated Tips to be a Better .NET Developer
Dec 7, 2018 Ryan Overton James Hickey Native API Access in Xamarin.Forms .NET Core Dependency Injection: Everything You Ought To Know
Dec 8, 2018 Carl Layton Shahed Chowdhuri Create Formatted Text Files With csvhelper Exploring .NET Core 3.0 and the Future of C#
Dec 9, 2018 Jeremy Sinclair Ian Russell Secure Data Access with IdentityServer4 and Xamarin Forms Expressing intent with value objects
Dec 10, 2018 James Curran Caleb Jenkins Here, There and Everywhere - A Simple Look at .NET Memory Model [?]
Dec 11, 2018 Andrew Lock Simon Timms Why is string.GetHashCode() different each time I run my program in .NET Core? Linked lists in C#
Dec 12, 2018 Ed Charbeneau Andres Paz Razor Components for a JavaScript-Free FrontEnd in 2019 Implementing a quantum simulator for Q# in C#
Dec 13, 2018 Amber Race Brian Jackett WireMock.Net Introduction to Calling Microsoft Graph from a C# .Net Core Application
Dec 14, 2018 Lee Englestone Daniel Oliver English Language Word Analysis With .NET OpenTracing and C#
Dec 15, 2018 Michael Eaton Kevin Griffin Exercises for Programmers – Weather Checker in C# Introduction to SignalR Streaming
Dec 16, 2018 Barret Blake Doug Mair Flow & Function Together Quick Introduction to C# Span
Dec 17, 2018 Gérald Barré (aka Meziantou) David Pine  Writing a Roslyn analyzer C# all the thing: .NET Core global tools
Dec 18, 2018 Duane Newman Caio Proiete Keeping Observable Collections Up To Date [?]
Dec 19, 2018 Jonathan Danylko Huzaifa Asif 10 More C# Extension Methods For The Holiday Season Create a custom middleware pipeline using .NET Core
Dec 20, 2018 Baskar Rao Eric Potter Testing .Net Core API using Auth0 with VS Tests The code changes in Roslyn between 7 and 8
Dec 21, 2018 Takayoshi Tanaka (vacated) Using Kubernetes readiness and liveness probes for health checks with ASP.NET Core 2.2 on OpenShift  
Dec 22, 2018 Jim Wilcox Chris Bohatka C# and WebAssembly Hit the Ground Running: Create a Starter Kit
Dec 23, 2018 Damian Łączak Chris Sainty An extension that I cannot code without. Blazor Toast Notifications using only C#, HTML and CSS
Dec 24, 2018 Chris Woodruff Gregor Suttie Getting the Most Out of Entity Framework Core - Part 1 Azure Blobs from C# and Visual Studio
Dec 25, 2018 Matthew Groves Calvin Allen Hangfire with ASP.NET Core C#, .NET, and Visual Studio - 2018 Year in Review

Alternates:

  • IF ALL FIFTY SLOTS FILL UP, please leave a comment or tweet with #csadvent anyway!
  • I will put you on this 'standby' list in case someone drops out or can't deliver their post in time.
  • Standby list:
    • Corstiaan Hesselink

Some ideas/topics to help inspire you:

  1. Blazor - now's your chance to experiment with writing C# for the browser
  2. Your latest open source contribution - show the community how you contributed and why
  3. Your favorite C# language feature - it doesn't even have to be a new feature, just blog about something you love about C#
  4. Introduce your favorite NuGet package / library. Even if it's a library you take for granted, not everyone has heard about it.
  5. How to avoid a pitfall you found with performance/memory/etc
  6. Integration/deployment of a C# application with Jenkins, Docker, Kubernetes, TeamCity, Azure, etc
  7. Write a "how to" for one of the many tools discussed in an episode of the Cross Cutting Concerns podcast
  8. Create a video tutorial and embed it in your blog post.
  9. Interview someone about C# and embed an audio player in your blog post.
  10. Implement a simplified example of a design pattern in C#

Thanks to everyone who is participating!

If you were an author of a C# Advent blog post in 2017, you get a chance to sign up earlier than the general public.

Tweet #csadvent or leave a comment below with the date you want to blog on. Note that this year, each day has up to TWO slots. So if someone has already claimed the day you want, that day may still be available.

The general call for C# Advent authors will go out next week, so claim your dates as soon as possible. Just like last year, you do NOT have to pick a topic right now. If you DO want to pick a topic, I will pencil it in, but you are free to change it at any time up until the date you pick.

Swashbuckle is a handy library to easily bring Swagger support to your ASP.NET Core (or ASP.NET) application. It is especially handy when developing an HTTP based API. It creates a form of interactive documentation based on the OpenAPI Specification.

Before diving into Swashbuckle: Merry Christmas! This blog is being posted on December 25th, 2017. It’s the final post of the very first C# Advent Calendar. Please check out the other 24 posts in the series! This event has gone so well, that I’m already planning on doing it again in 2018. Thank you, again, to everyone who participated (whether you are a writer or you’ve just been following along).

The full source code used in this example is available on Github.

ASP.NET Core HTTP API

I’m going to assume some level of familiarity with ASP.NET Core and creating a REST API. Here’s an example of a GET and a POST. These endpoints are reading/writing from a JSON text file (in a way that is probably not thread-safe and definitely not efficient, but it’s fine for this example).

public class ValuesController : Controller
{
    [HttpGet]
    [Route("api/teams")]
    public IActionResult GetTeams()
    {
        var jsonFile = System.IO.File.ReadAllText("jsonFile.json");
        var teams = JsonConvert.DeserializeObject<List<Team>>(jsonFile);
        return Ok(teams);
    }

    [HttpPost]
    [Route("api/team")]
    public IActionResult PostTeam([FromBody]Team team)
    {
        var jsonFile = System.IO.File.ReadAllText("jsonFile.json");
        var teams = JsonConvert.DeserializeObject<List<Team>>(jsonFile);
        teams.Add(team);
        System.IO.File.WriteAllText("jsonFile.json",JsonConvert.SerializeObject(teams));
        return Ok(team);
    }

    // etc...

To try out the GET endpoint, the simplest thing I can do is open a browser and view the results. But to try out the POST endpoint, I need something else. I could install Postman or Fiddler (and you should). Here’s how that would look.

Postman

Postman is great for interacting with endpoints, but Postman alone doesn’t really tell us anything about the endpoint or the system as a whole. This is where Swagger comes in.

Swagger

Swagger is a standard way to provide specifications for endpoints. Usually, that specification is automatically generated and then used to generate an interactive UI.

We could write the Swagger spec out by hand, but fortunately ASP.NET Core provides enough information to generate a spec for us. Look at the PostTeam action above. Just from reading that we know:

  • It expects a POST

  • The URL for it is /api/team

  • There’s a Team class that we can look at to see what kind of body is expected

From that, we could construct a Swagger spec like the following (I used JSON, you can also use YAML).

{
	"swagger": "2.0",
	"info": { "version": "v1", "title": "Sports API" },
	"basePath": "/",
	"paths": {
		"/api/team": {
			"post": {
				"consumes": ["application/json"],
				"parameters": [{
					"name": "team",
					"in": "body",
					"required": false,
					"schema": { "$ref": "#/definitions/Team" }
				}]
			}
		}
	},
	"definitions": {
		"Team": {
			"type": "object",
			"properties": {
				"name": { "type": "string" },
				"stadiumName": { "type": "string" },
				"sport": { "type": "string" }
			}
		}
	}
}

But why on earth would you want to type that out? Let’s bring in a .NET library to do the job. Install Swashbuckle.AspNetCore with NuGet (there’s a different package if you want to do this with ASP.NET).

You’ll need to add a few things to Startup.cs:

In the ConfigureServices method:

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Info { Title = "Sports API", Version = "v1"});
});

In the Configure method:

app.UseSwagger();

Aside: With ASP.NET, NuGet actually does all this setup work for you.

Once you’ve done this, you can open a URL like http://localhost:9119/swagger/v1/swagger.json and see the generated JSON spec.

Swagger spec in JSON

Swagger UI with Swashbuckle

That spec is nice, but it would be even nicer if we could use the spec to generate a UI.

Back in the Configure method, add this:

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Sports API v1");
});

Now, open your site and go to /swagger:

Swagger UI generated by Swashbuckle

Some cool things to notice:

  • Expand/collapse by clicking the URL of an endpoint (note that you must use Route attributes for Swashbuckle to work with ASP.NET Core).

  • "Try it out!" buttons. You can execute GET/POST right from the browser

  • The "parameter" of the POST method. Not only can you paste in some content, but you get an example value that acts like a template (just click it).

Giving some swagger to your Swagger

Swagger and Swashbuckle have done a lot with just a little bit. It can do even more if we add a little more information in the code.

  • Response: The ProducesResponseType attribute will let Swagger know what the response will look like (this is especially useful if you are using IActionResult and/or an endpoint could return different types in different situations).

  • Comments: If you are using XML comments, you can have these included with the Swagger output.

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Info { Title = "Sports API", Version = "v1" });
    var filePath = Path.Combine(PlatformServices.Default.Application.ApplicationBasePath, "swashbuckle-example.xml");
    c.IncludeXmlComments(filePath);
});

(Also make sure you XML Documentation output for your project enabled)

Here’s an example of a GetTeams method with both XML comments and ProducesResponseType:

/// <summary>
/// Gets all the teams stored in the file
/// </summary>
/// <remarks>Baseball is the best sport</remarks>
/// <response code="200">List returned succesfully</response>
/// <response code="500">Something went wrong</response>
[HttpGet]
[Route("api/teams2")]
[ProducesResponseType(typeof(Team), 200)]
public IActionResult GetTeams2()
{
    var jsonFile = System.IO.File.ReadAllText("jsonFile.json");
    var teams = JsonConvert.DeserializeObject<List<Team>>(jsonFile);
    return Ok(teams);
}
  • Customize your info: there’s more to the Info class than just Title and Version. You can specify a license, contact, etc.

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Info
    {
        Title = "Sports API",
        Version = "v1",
        Description = "An API to list and add sports teams",
        TermsOfService = "This is just an example, not for production!",
        Contact = new Contact
        {
            Name = "Matthew Groves",
            Url = "https://crosscuttingconcerns.com"
        },
        License = new License
        {
            Name = "Apache 2.0",
            Url = "http://www.apache.org/licenses/LICENSE-2.0.html"
        }
    });
    var filePath = Path.Combine(PlatformServices.Default.Application.ApplicationBasePath, "swashbuckle-example.xml");
    c.IncludeXmlComments(filePath);
});

Here’s a screenshot of the UI that has all three of the above enhancements: response type, XML comments, and more customized info.

Swagger with more swagger

Summary

Working on HTTP-based APIs? Bring Swashbuckle and Swagger into your life!

More resources:

Thanks again for reading the 2017 C# Advent!

UPDATE: The calendar is full. You can sign up to be an alternate, in case someone drops out or fails to deliver. I can't give you a date though, so you'd essentially have to have a post ready to go as soon as December 1st. And please, don't let the lack of an advent date keep you from writing that C# blog post! Finally, due to the tremendous response, I will double up the slots next year (from 25 to 50), assuming this advent goes well :)

I heard about the F# Advent Calendar, a traditional that's been carried on since 2010 (2014 in English). I think this is a great idea, and there needs to be one for C# too!

(I asked Sergey Tihon for permission!)

So, I need you to write a C# blog post!

Here are the rules:

  1. Reserve a slot on Twitter (with hash tag #csadvent) or leave a comment on this post. You do not have to announce your topic until the day you reserve.
  2. Prepare a blog post (in English).
  3. Add a link in your blog post that links back to here, so that your readers may find the entire advent.
  4. Publish your blog post on the specified date. Your post must be related to C# in some way, but otherwise the content is completely up to you. I've posted a few ideas below to get your creativity flowing.
  5. Post the link to your post on Twitter with hashtags #csharp and #csadvent

Below are all the slots, and who has claimed each date. I chose to go with 25 total slots (yes I know some advent calendars are 24).

I will do my best to keep this up to date. The slots will be first come first serve. I have already claimed December 25th for myself, since I assume that will be the least desirable date. But I'm happy to swap if you really really want that day.

DateClaimed byBlog Post
Dec 1, 2017 Hilary Weaver-Robb Combining Integration and UI Automation in C#
Dec 2, 2017 Jamie Rees Open Source, 2 years retrospective
Dec 3, 2017 Lucas Lansky Analyzing unit-ness of white-box tests using OpenCover
Dec 4, 2017 Andrei Ignat AOP with Roslyn–part 3–custom code at beginning of each method
Dec 5, 2017 Baskar rao Dsn Quick Actions in Visual Studio 2017
Dec 6, 2017 Bill Sempf Coding for an encrypted service
Dec 7, 2017 Brant Burnett Who says C# interfaces can't have implementations?
Dec 8, 2017 Lee Englestone Creating Alexa Skills with Web-API and hosting on Microsoft Azure
Dec 9, 2017 James Hickey Deck the Halls With Strategy Pattern Implementations in C#: Basic to Advanced
Dec 10, 2017 Carl Layton Using C# dynamic Keyword To Replace Data Transfer Objects
Dec 11, 2017 James Curran An Exercise in Refactoring - Specification Pattern
Dec 12, 2017 Andrew Lock Creating a .NET Standard Roslyn Analyzer in Visual Studio 2017
Dec 13, 2017 Jonathan Danylko 5 More C# Extension Methods for the Stocking! (plus a bonus method for enums)
Dec 14, 2017 Gérald Barré (aka Meziantou) Interpolated strings: advanced usages
Dec 15, 2017 Baskar rao Dsn Using BenchMarkDotNet for Performance BenchMarking
Dec 16, 2017 Chris Bohatka Breaking Down Dependency Injection and Inversion of Control in C# with SimpleInjector
Dec 17, 2017 David Pine C# Special Edition
Dec 18, 2017 Barret Blake Using C# and Azure Cognitive Services Text Analytics to Identify and Relate Text Documents
Dec 19, 2017 Ed Charbeneau 5 .NET Standard Features You Shouldn’t Miss
Dec 20, 2017 Kevin Miller Things you Should do with Strings While You’re Coworkers are on Holiday and No One is Checking the Production Code Branch
Dec 21, 2017 Angus Kinsey What makes C# great?
Dec 22, 2017 Jim Wilcox Unloading the UI Thread in C# on Windows 10 + UWP
Dec 23, 2017 Duane Newman All I want for Christmas is a C# Build System
Dec 24, 2017 Calvin Allen Live Unit Testing in Visual Studio 2017
Dec 25, 2017 Matthew D. Groves Swashbuckle and Swagger with ASP.NET Core

Alternates:

  • Leave a comment or tweet with #csadvent to be put on this list!

Some ideas:

  1. Introduction to [your favorite NuGet package]
  2. X C# Tricks and Tips
  3. JSON (De)serialization
  4. Streams
  5. The newer C# 6 and 7 features
  6. Async/await

Thanks to everyone who is participating! I hope this goes well and it can become an annual tradition.

Matthew D. Groves

About the Author

Matthew D. Groves lives in Central Ohio. He works remotely, loves to code, and is a Microsoft MVP.

Latest Comments

Twitter