3. Hot Chocolate
5m

Overview

We've got a better understanding of how works, it's time to implement it!

In this lesson, we will:

  • Explore the Hot Chocolate framework
  • Install and set up a Hot Chocolate server

Hot Chocolate, a .NET GraphQL framework

by itself is a specification, a language for APIs. To implement GraphQL in a server, we typically use a GraphQL framework.

For example, if you're a JavaScript/TypeScript developer, you might use Apollo Server.

In the .NET ecosystem, we can use Hot Chocolate, a framework developed and maintained by ChilliCream. Here's how they introduce themselves in their docs:

Hot Chocolate is an open-source for the Microsoft .NET platform that is compliant with the newest GraphQL October 2021 spec + Drafts, which makes Hot Chocolate compatible to all GraphQL compliant clients like Strawberry Shake, Relay, , and various other and tools.

Setting up Hot Chocolate

From your project directory, open up a new terminal. Let's install the Hot Chocolate package.

dotnet add package HotChocolate.AspNetCore --version 13.8.1

Note: We've chosen to include the specific version number here (which was the latest version at the time of course publication) to guarantee that the project works with the course instructions.

Next, open up the Program.cs file in the root of the repo. Currently, it's set up to return a simple "Hello World!" message from the root of where the server is running (which by default is http://localhost:5059).

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();


app.MapGet("/", () => "Hello World!");


app.Run();

In between the line instantiating the builder (line 1), and the line instantiating the app (line 2), let's add the Hot Chocolate to our web app's services.

builder.Services.AddGraphQLServer();

Then we'll replace the MapGet function with MapGraphQL().

app.MapGraphQL();

This function adds a endpoint to the endpoint configurations, which means our will be available at /graphql.

Building with Hot Chocolate

Hot Chocolate offers three different approaches to implementing a : annotation-based, code-first, and schema-first.

In the schema-first approach, we write the in (). Then, we need to write functions to populate each in the schema.

In both annotation-based and code-first approaches, we only write . The schema is generated automatically behind the scenes. The of C# and make this possible: C# types are mapped to types, so we don't need to learn or remember the specifics of syntax.

The code-first approach requires writing explicit code to define and wire up everything needed for a , like the name, field type, , descriptions, and more.

The annotation-based approach uses C# attributes, which are like tags for your code. Attributes are enclosed within square brackets and can take . Here's an example using the built-in ObsoleteAttribute:

Example from Microsoft .NET documentation
[Obsolete("ThisClass is obsolete. Use ThisClass2 instead.")]
public class ThisClass {}

Hot Chocolate comes with its own attributes we can use for development. These attributes are like a shortcut to the code that we would need to write if using the code-first approach.

You can mix and match approaches in the same project. Under the hood, both schema-first and annotation-based approaches will be translated into code-first by Hot Chocolate.

In this course, we'll be using the annotation-based approach. If you're just getting started with , it's helpful not to have to worry about learning syntax; we'll stick with familiar C# types and let Hot Chocolate do the work to generate the schema for us. Annotations also mean less boilerplate code for us!

Want to use a different approach? The Hot Chocolate documentation provides code snippets for each approach. In the next lesson, we'll provide an example of what the Hello World example might look like with schema-first and code-first, but we'll stick with annotation-based for the rest of the course.

Practice

What does the MapGraphQL() function do?

Key takeaways

  • Hot Chocolate is an open-source for the Microsoft .NET platform.
  • Hot Chocolate offers three development approaches: schema-first, code-first, and annotation-based.
  • In the code-first and annotation-based approaches, Hot Chocolate maps C# types to types, reducing the need to learn the specifics of the GraphQL () syntax.

Up next

Our is on standby, awaiting a schema. We'll give it what it wants in the next lesson!

Previous

Share your questions and comments about this lesson

This course is currently in

beta
. Your feedback helps us improve! If you're stuck or confused, let us know and we'll help you out. All comments are public and must follow the Apollo Code of Conduct. Note that comments that have been resolved or addressed may be removed.

You'll need a GitHub account to post below. Don't have one? Post in our Odyssey forum instead.