Skip to content

Simplified Getting Started Guide #8737

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Sep 24, 2025
Merged

Simplified Getting Started Guide #8737

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d4d1405
Simplified Getting Started Guide
michaelstaib Sep 24, 2025
f33cfd1
Updated Template
michaelstaib Sep 24, 2025
565ef95
edits
michaelstaib Sep 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion templates/server/Types/Query.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
namespace HotChocolate.Template.Server.Types;

[QueryType]
public static class Query
public static partial class Query
{
public static Book GetBook()
=> new Book("C# in depth.", new Author("Jon Skeet"));
Expand Down
83 changes: 48 additions & 35 deletions website/src/docs/hotchocolate/v16/get-started-with-graphql-in-net-core.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "Getting started with GraphQL in .NET Core"
description: "In this tutorial, we will walk you through the basics of creating a GraphQL server with Hot Chocolate."
description: "In this tutorial, you will walk through the basics of creating a GraphQL server with Hot Chocolate."
---

import { InputChoiceTabs } from "../../../components/mdx/input-choice-tabs"
Expand All @@ -9,7 +9,7 @@ import { InputChoiceTabs } from "../../../components/mdx/input-choice-tabs"

## Install the Hot Chocolate templates

Hot Chocolate provides a set of templates that can be used to quickly get started. Run the following command to install the templates:
Hot Chocolate provides templates to help you get started quickly. Install them with:

```bash
dotnet new install HotChocolate.Templates
Expand All @@ -19,7 +19,7 @@ These templates are kept up to date with the latest .NET and Hot Chocolate featu

## Create a new Hot Chocolate GraphQL server project

Once you have installed the templates you can use them to bootstrap your next ASP.NET Core project with Hot Chocolate.
Once you have installed the templates, you can use them to bootstrap your next ASP.NET Core project with Hot Chocolate.

<InputChoiceTabs>
<InputChoiceTabs.CLI>
Expand All @@ -40,13 +40,13 @@ Create a new project from within Visual Studio using the `GraphQL Server` templa
</InputChoiceTabs.VisualStudio>
</InputChoiceTabs>

# Exploring the template files
# Exploring the GraphQL server files

## Types

The `Types` directory defines the types that our GraphQL schema should contain. These types and their fields define what consumers can query from our GraphQL API.
The `Types` directory in the generated project defines the types that your GraphQL schema should contain. These types and their fields define what consumers can query from your GraphQL server. In other words, this schema defines the shape of your GraphQL API that clients can query.

We define two object types that we want to expose through our schema.
It already includes two entities called `Book` and `Author`.

```csharp
public record Author(string Name);
Expand All @@ -56,72 +56,85 @@ public record Author(string Name);
public record Book(string Title, Author Author);
```

> Note: Regular classes may also be used to define object types.

We also define a `Query` type that exposes the types above through a field.
The template also includes a `Query` class, which defines the **root type** for read operations in your GraphQL server. In GraphQL, this type is called the **query type**, and every public method or property in this class becomes a **field** that clients can query.

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

> Note: The `Query` class is declared as `partial` so that the Hot Chocolate source generator can generate the resolvers at build time, instead of relying on reflection and runtime compilation.

The field in question is named `GetBook`, but the name will be shortened to just `book` in the resulting schema.

The `QueryType` attribute marks a class as an extension of the `query` operation type.

## Program

In the `Program.cs` file, we start by adding the services required by Hot Chocolate to our dependency injection container.
In the generated `Program.cs` file, the template has already added Hot Chocolate to your `WebApplicationBuilder`.

```csharp
builder.Services
.AddGraphQLServer()
builder.AddGraphQL()
```

`AddGraphQLServer` returns an `IRequestExecutorBuilder`, which has many extension methods, similar to an `IServiceCollection`, that can be used to configure the GraphQL server.
AddGraphQL returns an IRequestExecutorBuilder with extension methods for configuring your GraphQL server.

We then call `AddTypes`, a source-generated extension method that automatically registers all types in the assembly.
The template also calls AddTypes, a source-generated extension method that automatically registers all GraphQL types in the current assembly. The source generator looks for types that inherit Hot Chocolate base classes or are decorated with attributes such as [QueryType].

> Note: The name of the `AddTypes` method is based on the assembly name by default, but can be set using the `[Module]` assembly attribute, as seen in `ModuleInfo.cs`.

Next, we call `app.MapGraphQL()` to expose our GraphQL server at an endpoint with the default path `/graphql`. Hot Chocolate comes with an ASP.NET Core middleware that is used to serve up the GraphQL server.
It also calls `app.MapGraphQL()` to expose your GraphQL server at an endpoint with the default path `/graphql`. Hot Chocolate comes with an ASP.NET Core middleware that is used to serve up the GraphQL server.

Finally, the template includes `app.RunWithGraphQLCommands(args)` to start the server.

`RunWithGraphQLCommands(args)` works like `Run()`, but also adds handy developer commands. For example, you can export your schema as SDL with:

<InputChoiceTabs>
<InputChoiceTabs.CLI>

```bash
dotnet run -- schema export
```

</InputChoiceTabs.CLI>
</InputChoiceTabs>

Finally, we call `app.RunWithGraphQLCommands(args)` to start the server.
This command will dump a file called `schema.graphqls` into your project folder which represents the GraphQL schema.

And that is it – you have successfully set up a Hot Chocolate GraphQL server! 🚀

# Executing a query

First off we have to run the project.
First, run the generated project.

<InputChoiceTabs>
<InputChoiceTabs.CLI>

```bash
dotnet run --no-hot-reload
dotnet run
```

</InputChoiceTabs.CLI>
<InputChoiceTabs.VisualStudio>

The project can be started by either pressing `Ctrl + F5` or clicking the green `Debug` button in the Visual Studio toolbar.
You can start the project by either pressing `Ctrl + F5` or clicking the green `Debug` button in the Visual Studio toolbar.

</InputChoiceTabs.VisualStudio>
</InputChoiceTabs>

If you have set everything up correctly, you should be able to open <a href="http://localhost:5095/graphql" target="_blank" rel="noopener noreferrer">http://localhost:5095/graphql</a> in your browser and be greeted by our GraphQL IDE [Nitro](/products/nitro).
If you have set everything up correctly, you should be able to open <a href="http://localhost:5095/graphql" target="_blank" rel="noopener noreferrer">http://localhost:5095/graphql</a> in your browser and be greeted by the GraphQL IDE [Nitro](/products/nitro).

![GraphQL IDE](../../../images/getting-started-nitro.webp)

Next, click on `Create Document`. You will be presented with a settings dialog for this new tab, pictured below. Make sure the `HTTP Endpoint` input field has the correct URL under which your GraphQL endpoint is available. If it is correct you can just go ahead and click the `Apply` button.
Click Create Document, check that the HTTP Endpoint matches your server URL, then click Apply.

![GraphQL IDE: Setup](../../../images/getting-started-nitro-setup.webp)

Now you should be seeing an editor like the one pictured below. If your GraphQL server has been correctly set up you should see `Schema available` at the bottom right of the editor.
Now you should be seeing an editor like the one pictured below. If your GraphQL server has been correctly set up, you should see `Schema available` at the bottom right of the editor.

![GraphQL IDE: Editor](../../../images/getting-started-nitro-editor.webp)

Expand All @@ -130,15 +143,15 @@ The view is split into five panes.
1. `Builder`
- This is where you build operations with a visual editor.
1. `Request`
- This is where you enter operations that you wish to send to the GraphQL server.
- This is where you enter operations to send to the GraphQL server.
1. `Response`
- This is where results will be displayed.
1. `GraphQL Variables / HTTP Headers`
- This is where you modify variables and headers.
- This is where you edit variables and headers.
1. `Responses`
- This is where you view recent queries.
- This shows your recent queries.

Let's send a query to your GraphQL server. Paste the below query into the `Request` pane of the editor:
Paste the following query into the `Request` pane of the editor:

```graphql
{
Expand All @@ -151,24 +164,24 @@ Let's send a query to your GraphQL server. Paste the below query into the `Reque
}
```

To execute the query, simply press the `Run` button. The result should be displayed as JSON in the `Response` pane as shown below:
To execute the query, press the `Run` button. The result should be displayed as JSON in the `Response` pane as shown below:

![GraphQL IDE: Executing a query](../../../images/getting-started-nitro-query.webp)

You can also view and browse the schema from within Nitro. Click on the `Schema Reference` tab next to `Operation` in order to browse the schema. There's also a `Schema Definition` tab, pictured below, which shows the schema using the raw SDL (Schema Definition Language).
You can also view and browse the GraphQL schema from within Nitro. Click on the `Schema` tab next to `Operation` in order to browse the schema. There's also a `Schema Definition` tab, pictured below, which shows the schema using the raw SDL (Schema Definition Language).

![GraphQL IDE: Schema](../../../images/getting-started-nitro-schema.webp)

Congratulations, you've built your first Hot Chocolate GraphQL server and sent a query using the Nitro GraphQL IDE. 🎉🚀
🎉 Congratulations! You’ve built your first Hot Chocolate GraphQL server and run your first query with the Nitro GraphQL IDE. 🚀

# Additional resources

Now that you've set up a basic GraphQL server, what should your next steps be?
Now that your GraphQL server is running, here are some next steps:

If this is your first time using GraphQL, we recommend [this guide](https://graphql.org/learn/) that walks you through the basic concepts of GraphQL.
If this is your first time using GraphQL, it is recommended to read [this guide](https://graphql.org/learn/) that walks you through the basic concepts of GraphQL.

If you want to get an overview of Hot Chocolate's features, we recommend reading the _Overview_ pages in each section of the documentation. They can be found in the sidebar to your left.
If you want to get an overview of Hot Chocolate's features, read the _Overview_ pages in each section of the documentation. They can be found in the sidebar to your left.

For a guided tutorial that explains how you can set up your GraphQL server beyond this basic example, check out [our workshop](https://github.com/ChilliCream/graphql-workshop). Here we will dive deeper into several topics around Hot Chocolate and GraphQL in general.
For a guided tutorial that explains how you can set up your GraphQL server beyond this basic example, check out [our workshop](https://github.com/ChilliCream/graphql-workshop). This workshop dives deeper into several topics around Hot Chocolate and GraphQL in general.

You can also jump straight into our documentation and learn more about [Defining a GraphQL schema](/docs/hotchocolate/v16/defining-a-schema).
You can also jump straight into the documentation and learn more about [Defining a schema](/docs/hotchocolate/v16/defining-a-schema).
Loading