--- title: "How to Implement Hot Chocolate in ASP.NET Core Web API for Beginners" description: "Exploring how to set up and configure Hot Chocolate within an ASP.NET Core Web API project, including schema definition, resolver setup, and testing with GraphiQL for newcomers to GraphQL." author: "Ravi Vishwakarma" published: 2026-09-22 updated: 2026-09-22 canonical: https://answers.mindstick.com/blog/632/how-to-implement-hot-chocolate-in-asp-net-core-web-api-for-beginners category: "Backend Development" tags: ["GraphQL", ".NET", "hot chocolate", "web api", "Backend", "Beginner"] reading_time: 6 minutes --- # How to Implement Hot Chocolate in ASP.NET Core Web API for Beginners If you are new to GraphQL and looking to build a strongly typed API with ASP.NET Core, you have probably heard about Hot Chocolate. It is one of the most mature and developer-friendly GraphQL server implementations for .NET. But jumping straight into a tutorial can feel overwhelming when you are still wrapping your head around what a schema actually is, or why you need a separate runtime package instead of just using System.Text.Json. This guide walks through the essentials step by step, assuming you have a basic [ASP.NET Core Web API](https://answers.mindstick.com/qa/117161/how-to-authenticate-aspnet-core-web-apis-using-azure-app-service-authentication-easy-auth) project up and running and you understand what an HTTP controller is. We will not skip the "why" behind each decision. By the end, you will have a working GraphQL endpoint that you can query with GraphiQL, and you will understand the pieces that make it tick. ## What Hot Chocolate actually gives you Before installing anything, it helps to know what problem Hot Chocolate solves. In a traditional REST API, you often end up with many endpoints: `/api/users`, `/api/users/5`, `/api/posts`, and so on. GraphQL flips that model. You expose a single endpoint, usually `/graphql`, and the client tells the server exactly which fields it wants. Hot Chocolate is the server-side engine that parses those queries, validates them against your schema, and resolves them to your .NET code. The library also gives you strongly typed schemas using C# classes, automatic validation, and excellent tooling like GraphiQL built in. For a beginner, that means less boilerplate around routing and serialization, and more focus on your business logic. ## Project setup and installation Start by creating a new ASP.NET Core Web API project. If you are using the .NET CLI, run: ```bash dotnet new webapi -n GraphQLDemo cd GraphQLDemo dotnet add package HotChocolate dotnet add package HotChocolate.AspNetCore ``` The `HotChocolate` package contains the core runtime, while `HotChocolate.AspNetCore` wires it into the ASP.NET Core pipeline. You will also want the `HotChocolate.AspNetCore.Tests` package if you plan to write unit tests later, but that is optional for now. ## Configuring the service and the endpoint Open `Program.cs`. In modern minimal API style, you register the GraphQL services with `builder.Services.AddGraphQL` and then map the endpoint with `app.MapGraphQL`. Here is what that looks like: ```cs // Register GraphQL services builder.Services.AddGraphQL(options => { // Configure default query and mutation types options.EnableMetrics = true; }); // Configure the ASP.NET Core pipeline var app = builder.Build(); // Map the GraphQL endpoint at /graphql app.MapGraphQL(); ``` That is the entire server-side setup. Notice there is no controller, no action method, and no JSON serialization logic to write. Hot Chocolate handles the HTTP layer, query parsing, and execution internally. If you are coming from a controller-based background, this shift can feel strange at first, but it is one of the reasons GraphQL feels so concise. ## Defining your first type and resolver In GraphQL, everything revolves around types. A type describes a shape of data, like a `User` or a `Product`. In Hot Chocolate, you define these as C# classes decorated with attributes. Let us model a simple `User`: ```cs using HotChocolate; public class User { // The Id field is the primary identifier public int Id { get; set; } // [GraphQLName] allows you to customize the exposed field name [GraphQLName("userId")] public string Username { get; set; } = string.Empty; // [GraphQLDescription] shows up in schema documentation [GraphQLDescription("The user's email address")] public string Email { get; set; } = string.Empty; } ``` Attributes like `[GraphQLName]` and `[GraphQLDescription]` are optional but incredibly useful when you want your schema to be self-documenting. Without them, Hot Chocolate exposes the exact C# property names as GraphQL field names. ## Creating the query root GraphQL needs a root query type that tells the server what top-level fields are available for clients to ask for. In Hot Chocolate, you create a class that inherits from `ObjectType`: ```cs using HotChocolate; public class Query { // [ExtendObjectType(typeof(Query))] marks this as the root query [ExtendObjectType(typeof(Query))] public class UserType { // [UseProjection] enables field selection by the client [UseProjection] public User GetUser( [Service] IUserRepository repository, int id) { return repository.GetById(id); } } } ``` Notice the `[UseProjection]` attribute. This is what allows a client to request only the fields it cares about, such as `{ getUser(id: 1) { userId email } }`. Without it, the server would return the entire `User` object regardless of what the client asked for. We also injected `IUserRepository` here. Hot Chocolate supports [dependency injection](https://www.mindstick.com/forum/159868/what-is-dependency-injection-and-how-can-i-implement-it-in-c) natively, so you can resolve services directly in your [resolver](https://www.mindstick.com/articles/13155/contact-mywifiext-support-team-to-resolver-network-issues)s. This keeps your data access logic separate from your GraphQL plumbing. ## Registering the schema So far we have defined types and a query root, but the server does not know about them yet. You need to tell Hot Chocolate to compile these into a schema. In `Program.cs`, add: ```cs builder.Services.AddGraphQL(options => { options.AddType(); options.AddType(); }); ``` The `AddType` method scans the assembly for classes decorated with GraphQL attributes and registers them. If you are working in a large solution with many projects, you may need to specify the assembly explicitly, but for a simple demo project, this automatic scanning is perfect. ## Testing with GraphiQL Hot Chocolate ships with GraphiQL, an in-browser IDE for exploring your schema. Once your application is running, navigate to `https://localhost:7123/graphql` (or whatever port your dev server uses). You will see a query editor on the left and a documentation pane on the right. Try running this query: ```graphql { getUser(id: 1) { userId email } } ``` If everything is wired correctly, you should see a JSON response matching the shape of your query. If you get an error, check three things first: that `Program.cs` has `app.MapGraphQL()`, that your types are registered with `AddType`, and that your resolver method signature matches the field name exactly. ## Common beginner pitfalls - **Forgetting `MapGraphQL`:** Without this call, requests to `/graphql` will 404 because ASP.NET Core does not know what middleware to run. - **Async vs sync resolvers:** Hot Chocolate prefers async methods for I/O-bound work, such as database calls. If you return a `Task`, decorate the method with `async` and use `await`. Mixing sync and async without care can lead to deadlocks in certain hosting scenarios. - **Circular references:** If your `User` type contains a `List` and `Post` contains a reference back to `User`, you will get infinite recursion during serialization. Use `[Ignore]` on the back-reference or implement a custom resolver that limits depth. ## Where to go next You now have a minimal but functional GraphQL server. From here, the natural next steps are adding mutations for writes, implementing pagination with cursor-based connections, and securing the endpoint with JWT bearer tokens. Hot Chocolate integrates cleanly with ASP.NET Core authentication middleware, so you do not need a separate GraphQL-specific auth library. Do not worry about mastering every advanced feature on day one. The goal was to see how little code is required to get a typed, queryable API running, and to understand the mental model shift from REST endpoints to a single schema-driven endpoint. Once that clicks, the rest of the ecosystem will feel much easier to navigate. --- Original Source: https://answers.mindstick.com/blog/632/how-to-implement-hot-chocolate-in-asp-net-core-web-api-for-beginners Copyright © MindStick Software Pvt. Ltd. This Markdown version is provided for developers, AI systems, and offline reading.