In this tutorial, you will walk through the basics of creating a GraphQL server with Hot Chocolate.

By the end of this guide, you will have a running GraphQL server that responds to queries. You will use the Hot Chocolate project template, explore the generated code, and execute your first query in the Nitro GraphQL IDE.

Prerequisites: .NET 8 SDK or later.

Create the Project

Install the Hot Chocolate templates.

dotnet new install HotChocolate.Templates

Create a new project from the template.

dotnet new graphql --name GettingStarted

This creates a GettingStarted directory with the project files. Open it in your editor.

Explore the Generated Code

Domain Types

The Types directory contains two record types that represent the domain model.

// Types/Author.cs
public record Author(string Name);

// Types/Book.cs
public record Book(string Title, Author Author);

These are regular C# types. Hot Chocolate infers the GraphQL schema from them.

Query Type

The Query class defines the root type for read operations. Each public method becomes a field that clients can query.

// Types/Query.cs
[QueryType]
public static partial class Query
{
    public static Book GetBook()
        => new Book("C# in depth.", new Author("Jon Skeet"));
}

The [QueryType] attribute tells the source generator to register this class as part of the GraphQL Query type. The class must be partial so the source generator can add the registration code at build time.

The method GetBook becomes a field named book in the schema. Hot Chocolate strips the Get prefix by convention.

Program.cs

The generated Program.cs sets up the server.

builder.AddGraphQL()

AddGraphQL returns an IRequestExecutorBuilder for configuring the GraphQL server. The template also calls a source-generated AddTypes method that registers all types decorated with attributes like [QueryType] in the current assembly.

app.MapGraphQL()

MapGraphQL exposes the GraphQL endpoint at /graphql. This is where clients send queries and where Nitro (the built-in GraphQL IDE) is served.

app.RunWithGraphQLCommands(args)

RunWithGraphQLCommands works like Run() but adds developer commands. For example, you can export the schema as SDL.

dotnet run -- schema export

This writes a schema.graphqls file to your project directory.

Run the Server

dotnet run

If everything worked, the terminal output includes a line like this:

Now listening on: http://localhost:5095

Open http://localhost:5095/graphql in your browser. You should see the Nitro GraphQL IDE.

Click Create Document, verify the HTTP Endpoint matches your server URL, and click Apply.

You should see the editor with Schema available at the bottom right.

Execute a Query

Paste the following query into the Request pane.

{
  book {
    title
    author {
      name
    }
  }
}

Click Run. The Response pane should show:

{
  "data": {
    "book": {
      "title": "C# in depth.",
      "author": {
        "name": "Jon Skeet"
      }
    }
  }
}

You can browse the schema by clicking the Schema tab next to Operation. The Schema Definition tab shows the raw SDL.

Your GraphQL server is running and responding to queries.

Next Steps

• "I want to learn about the type system." See Defining a Schema for queries, mutations, subscriptions, and all the GraphQL types.

• "I want to fetch data from a database." See DataLoader for batched data fetching, or Entity Framework for EF Core integration.

• "I want a deeper tutorial." Check out the GraphQL Workshop for a hands-on walkthrough covering types, resolvers, DataLoaders, filtering, and more.

• "I'm new to GraphQL." Read the official GraphQL introduction to understand the concepts before diving deeper into Hot Chocolate.