graphql-platform Documentation

Mocha persists saga state, manages transitions, and supports compensation when steps fail. See Sagas for a full walkthrough.

In-process mediator Copy Chapter

For commands and queries that stay within a single service, the mediator provides CQRS dispatch with middleware - without a transport layer. Define your messages with marker interfaces, implement handlers, and the source generator wires everything at compile time:

// Define a command and its handler
public record PlaceOrderCommand(Guid ProductId, int Quantity)
    : ICommand<PlaceOrderResult>;

public class PlaceOrderCommandHandler(AppDbContext db)
    : ICommandHandler<PlaceOrderCommand, PlaceOrderResult>
{
    public async ValueTask<PlaceOrderResult> HandleAsync(
        PlaceOrderCommand command, CancellationToken cancellationToken)
    {
        // business logic
        return new PlaceOrderResult(true, Guid.NewGuid());
    }
}

// Register and use
builder.Services
    .AddMediator()
    .AddCatalog()
    .UseEntityFrameworkTransactions<AppDbContext>();

app.MapPost("/orders", async (ISender sender) =>
    await sender.SendAsync(new PlaceOrderCommand(productId, 2)));

The mediator supports commands (with and without responses), queries, notifications, middleware, and EF Core transaction wrapping (commands only by default, configurable via delegate). The source generator produces a typed registration method per assembly (e.g. AddCatalog()) that wires up all handlers and pre-compiled dispatch pipelines automatically. See Mediator for the full guide.

Learning paths

Choose an entry point based on how you learn best:

• Get something running first: Quick Start -zero to a working message bus in under five minutes with the InMemory transport.

• Understand the concepts first: Messages then Messaging Patterns - learn what flows through the system and what patterns govern how it flows.

• Evaluating Mocha for a specific broker: Transports - understand the transport abstraction and what is available.

• In-process CQRS: Mediator - dispatch commands, queries, and notifications within a single service using the source-generated mediator.

• See a real-world system: The Demo application is a complete e-commerce system with three services (Catalog, Billing, Shipping) that demonstrates event-driven communication, sagas, batch processing, the transactional outbox, and .NET Aspire orchestration.

Ready to build? Start with the Quick Start.

Website Content Docs Nitro Getting Started (`website/content/docs/nitro/getting-started.md`) Copy Section

title: "Getting Started" Copy Chapter

Ready to explore the features of Nitro? In this getting started guide, we'll show you how to get up and running with Nitro.
You have the option to choose between the convenience of the web app or the enhanced capabilities of the desktop version. We'll guide you through the setup process, so you can start enjoying all that Nitro has to offer.

Get ready to unlock the full potential of GraphQL with Nitro. Choose your preferred option and follow the setup instructions to start enjoying the features that Nitro has to offer.

Web App

To begin your exploration, simply visit nitro.chillicream.com and experience the convenience of Nitro's web-based version. This excellent starting point allows you to conveniently probe public GraphQL APIs and access most of the features that Nitro offers. For an even more immersive experience, you can also install the web app as a Progressive Web App (PWA) on your device, providing a native-like experience.

Desktop App

You can install the Nitro App directly from our download page. The download page provides DMG installers for macOS, x64 installers for Windows, and AppImage/Snap installers for Ubuntu and Ubuntu-based Linux distributions. Note that other Linux distributions or installer formats are currently unsupported.

Upon successful installation, follow the steps in the Your first Query guide to execute your first GraphQL query using Nitro.

Your First Query

Lets guide you through the process of creating your first GraphQL query document using Nitro.

Step 1: Start the Nitro application. You should see an interface similar to this:

Step 2: Click on the "Create Document" button to initiate the creation of your first query document.

Step 3: You'll see a new document called 'untitled 1' generated. Simultaneously, the connection settings dialog box will pop up automatically.
Now, input the following link into the 'HTTP Endpoint' field: https://workshop.chillicream.com/graphql
It should resemble this:

Step 4: Click on the 'Apply' button. This will save your settings and close the dialog box.

Step 5: At this point, your screen should look like this:

Take note of the following key elements:

1. Request Pane: This is where you will input your queries.
2. Response Pane: Here, you will see the output or response of your queries.
3. Variables Pane: This is where you can define variables for your query.

Step 6: The green circle at the top right next to the schema url indicates that you are connected to the GraphQL server and that your schema is fetched. You now have full intellisense for your queries. Copy the following GraphQL query and paste it into the 'Operations' editor area:

{
  sessionById(id: "U2Vzc2lvbgppMQ==") {
    title
    track {
      name
    }
    startTime
    endTime
  }
}

Step 7: Click on the 'Run' button. You should see a response with data in the 'Response' area. Congratulations, you have completed a GraphQL query!

Step 8:
Now, let's save your document.

Sign in to your account by clicking the 'Sign In' button on the user icon in the bottom left corner of the screen. If you don't have an account, you can create a new one.

Step 9: Once you are signed in, save your document by clicking the 'Save' button next to the tabs. Your documents are now synced between your devices.

Step 10: Great job! You've successfully created, executed, and saved your first GraphQL query using Nitro. To learn more about the Nitro User Interface, head over to the Explore the UI guide.

Happy querying!

Website Content Docs Nitro Index (`website/content/docs/nitro/index.md`) Copy Section

title: Nitro metaTitle: "Nitro: GraphQL IDE, Observability, and Governance" Copy Chapter

Nitro combines a collaborative GraphQL IDE, schema and client registries, and OpenTelemetry monitoring in one API platform. Use it to explore schemas, run operations, coordinate API changes, and understand production behavior throughout the API lifecycle.

Are you hungry yet? Let's get started!

Features

1. GraphQL IDE
   Whether you're building or consuming GraphQL APIs, Nitro simplifies the process by allowing you to effortlessly build and execute GraphQL queries and mutations. Its intuitive UI enables you to visualize and explore your GraphQL schemas, making it easier to understand and work with complex structures. The powerful editor provides syntax highlighting, auto-completion, and error highlighting, helping you write GraphQL queries and mutations with ease.

2. Collaboration
   Additionally, Nitro places a strong emphasis on collaboration. It offers seamless team collaboration features, allowing developers to share documents, API configurations, environment settings and lets you collaborate on projects, and synchronize your work across multiple team members. By facilitating effective communication, Nitro ensures that everyone on your team is on the same page, leading to more efficient and coordinated development efforts.

3. DevOps
   Nitro supports you during the entire lifecycle of an API. With its schema and client registry, Nitro ensures that your APIs are well-maintained and evolve seamlessly over time. Integrated into your development workflow, Nitro helps you manage your APIs effectively, making easy to build and maintain high-quality APIs.

4. Schema Registry
   Nitro's schema registry acts as a centralized repository for your GraphQL schemas. It allows you to store, version, and manage your schemas effectively. Whenever you make changes to your schema, Nitro tracks and documents those changes, making it easy to keep a history of modifications. This ensures that you have full visibility into the evolution of your API, making it easier to understand and troubleshoot issues that may arise during development.

5. Client Registry
   The client registry feature of Nitro complements the schema registry by providing a centralized location to manage and track the clients that consume your GraphQL APIs. It enables you to register and document all the client applications that interact with your APIs. By maintaining an up-to-date client registry, you can easily identify which clients may be affected by schema changes and take appropriate actions to ensure a smooth transition.

6. Intuitive Interface
   Nitro provides a user-friendly interface that is easy to navigate, even for those new to GraphQL. Its clean and intuitive design makes it a pleasure to work with, enabling developers to focus on their tasks without unnecessary distractions or complications.

Website Content Docs Skills Getting Started (`website/content/docs/skills/getting-started.md`) Copy Section

title: "Getting Started" Copy Chapter

By the end of this guide you will have run skills and added your first skill to your agent.

skills is a .NET CLI that installs, updates, and authors Agent Skills, the portable SKILL.md files that extend AI coding agents like Claude Code, Cursor, and GitHub Copilot. You point it at a source (a GitHub repo, a git URL, or a local folder), and it places the skill where your agent looks for it. Your agent then loads the skill on demand when a task matches it.

This page takes you from zero to one working skill. It takes about five minutes.

Prerequisites

Before you start, make sure you have the following:

These docs run skills with dnx, so there is nothing to install first. If you would rather have skills on your PATH, install the global tool instead (it needs only the .NET SDK 8.0 or newer). See Install as a global tool.

Run `skills`

These docs run skills with dnx, which needs no install. You can also install it as a global tool if you prefer skills on your PATH.

Run with dnx Copy Chapter

dnx ships with the .NET 10 SDK and runs a tool straight from NuGet, the way npx runs a package from npm. Nothing is installed up front.

dnx skills add anthropics/skills --agent claude-code

On the first run, dnx prompts you to confirm the package download before it proceeds:

Tool package skills@<version> will be downloaded from source https://api.nuget.org/v3/index.json.
Proceed? [y/n] (y):

After you confirm, the install proceeds and prints the summary shown in Add your first skill. The first run downloads the package into your NuGet cache; later runs reuse it and start immediately. dnx skills is shorthand for dotnet tool exec skills.

To skip the download prompt (for example in CI), pass --yes:

dnx --yes skills add anthropics/skills --agent claude-code

You can control the skills version that dnx runs and where it fetches it from:

If your repository has a .config/dotnet-tools.json manifest that lists skills, dnx honors the pinned version from the manifest, which keeps one-shot runs consistent with the version your team committed.

Install as a global tool Copy Chapter

If you would rather have skills on your PATH, install it as a global .NET tool. This needs the .NET SDK 8.0 or newer.

dotnet tool install -g skills

You can invoke the tool using the following command: skills
Tool 'skills' (version '0.3.0') was successfully installed.

With the global tool you run skills directly: drop the dnx prefix from every example in these docs (dnx skills add ... becomes skills add ...). Confirm the install with skills --version, which prints a value like 0.3.0+<git-sha> (the trailing suffix records the exact commit the build came from).

To pin skills to a version your whole team shares, install it as a local tool through a manifest instead. From the repository root:

dotnet new tool-manifest
dotnet tool install skills

Local tools are restored with dotnet tool restore and run through dotnet skills. Check the manifest (./.config/dotnet-tools.json) into source control so every collaborator uses the same version.

Add your first skill

You are ready to install a skill. The example below installs skills from anthropics/skills, Anthropic's reference repository, targeting Claude Code.

dnx skills add anthropics/skills --agent claude-code

Agent names are case-sensitive. Use claude-code, not claude or Claude. For GitHub Copilot the name is github-copilot.

The skills CLI fetches the source, discovers the skills, installs them, and prints a summary:

Source: https://github.com/anthropics/skills.git
Found 2 skill(s)

┌─Installation Summary─────────────────────────────────────────────────────────┐
│ Canonical: /your-project/.agents/skills                                      │
│ Symlinked:  Claude Code                                                      │
└──────────────────────────────────────────────────────────────────────────────┘
┌─Installed 2 skill(s)─────────────────────────────────────────────────────────┐
│ ✓ pdf                                                                        │
│   → /your-project/.claude/skills/pdf                                         │
│ ✓ docx                                                                       │
│   → /your-project/.claude/skills/docx                                        │
└──────────────────────────────────────────────────────────────────────────────┘

Done!  Review skills before use; they run with full agent permissions.

The trailing line is a deliberate safety nudge. A skill can include scripts that the agent runs with your agent's full permissions. Install skills only from sources you trust, and read a new skill before you use it.

If you omit --agent, the CLI runs interactively and lets you pick which agents to target from the ones it detects on your machine. To install only specific skills from a multi-skill source, add --skill <name> (repeatable). For the full set of source forms, scopes, and flags, see Installing Skills.

Checkpoint. If everything worked, you should see the Installed 2 skill(s) panel and the Done! line, with no error. If you saw an Invalid agents panel, you misspelled the agent name (it is case-sensitive). If you saw No valid skills found, the source had no SKILL.md with both a name and a description. See Troubleshooting for more.

See what is installed

To confirm what landed in your project, list the installed skills:

dnx skills list

Project Skills

Skill  Path                   Agents
pdf    ./.claude/skills/pdf   Claude Code
docx   ./.claude/skills/docx  Claude Code

The table shows each skill's name, where it lives on disk, and the agents linked to it (shown by their display name, Claude Code). To list global skills instead, add -g. For machine-readable output, add --json.

Use the skill

The skill now lives where your agent looks for it. You do not need to do anything else.

Your agent loads each installed skill's name and description at startup, then reads the full skill only when a task matches the description. This is progressive disclosure: the description is the trigger, and the body loads on demand. Start a task that matches the skill, and your agent picks it up automatically.

Update or remove the global tool

If you run skills with dnx, you never update it yourself: each run fetches the version you ask for. The commands below apply when you installed the global tool.

To update the global skills tool to the latest version:

dotnet tool update -g skills

Tool 'skills' was successfully updated from version '0.3.0' to version '<new>'.

To uninstall it:

dotnet tool uninstall -g skills

Tool 'skills' (version '0.3.0') was successfully uninstalled.

Note that dotnet tool update updates the skills CLI, not your installed skills. To check your skills for updates, use the dnx skills update command, covered in Installing Skills.

Next steps

• Installing Skills: every source form, project versus global scope, picking agents and skills, symlink versus copy, and checking for skill updates.
• Authoring Skills: scaffold a SKILL.md with dnx skills init, write a good description, and publish your skill.
• Reference: the complete command and flag surface.

Website Content Docs Skills Index (`website/content/docs/skills/index.md`) Copy Section

title: Skills metaTitle: "Skills: Agent Skills CLI for .NET" Copy Chapter

skills is the .NET CLI that installs, updates, and authors Agent Skills: portable SKILL.md files that teach an AI coding agent how you work. Stop re-explaining your conventions every session. Package the knowledge once, then hand the same skill to Claude Code, Cursor, GitHub Copilot, or another of the 55+ supported agents with a single command.

Run it with dnx, which ships with the .NET 10 SDK, so there is nothing to install first:

dnx skills add anthropics/skills --agent claude-code

Source: https://github.com/anthropics/skills.git
Found 2 skill(s)

┌─Installation Summary─────────────────────────────────────────────────────────┐
│ Canonical: /your-project/.agents/skills                                      │
│ Symlinked:  Claude Code                                                      │
└──────────────────────────────────────────────────────────────────────────────┘
┌─Installed 2 skill(s)─────────────────────────────────────────────────────────┐
│ ✓ pdf                                                                        │
│   → /your-project/.claude/skills/pdf                                         │
│ ✓ docx                                                                       │
│   → /your-project/.claude/skills/docx                                        │
└──────────────────────────────────────────────────────────────────────────────┘

Done!  Review skills before use; they run with full agent permissions.

The CLI detects the agents you have installed, then symlinks the skill into each one from a single canonical store. The agent loads the skill on its own when a task matches.

These docs show every command as dnx skills. Prefer skills on your PATH? Install the global tool with #!shell dotnet tool install -g skills, then drop the dnx prefix and run skills directly.

Need the prerequisites or a step-by-step walkthrough? See Get started. The source repository and skills package on NuGet are public.

What are Agent Skills

A skill is a folder with a single SKILL.md file. That file has YAML frontmatter (a name and a description) followed by a Markdown body of instructions. Optional subfolders carry supporting material the agent reads only when it needs it.

Think of a skill as an onboarding guide for a new team member. You write down a procedure once (how to run your test suite, how your commit messages are formatted, which API your team prefers), and the agent references the relevant section when a task calls for it. A general-purpose agent becomes a specialist in your codebase without bespoke prompt engineering on every request.

Skills differ from prompts. A prompt is conversation-level guidance you paste in for one task. A skill loads on demand across every conversation, so you never repaste the same instructions again.

The SKILL.md format is an open standard created by Anthropic and adopted across the ecosystem. The same file works in 55+ supported agents, including Claude Code, Cursor, and GitHub Copilot. To go deeper, read Anthropic's Agent Skills overview and the open specification at agentskills.io.

How skills load: progressive disclosure

Skills stay out of the agent's context window until they are needed. The format loads in three levels, each at a different time. This is the single most important idea to understand, because it is why you can install many skills without paying a context penalty.

At startup the agent loads only each skill's name and description. The description is what the agent matches against your request to decide whether to activate the skill, so write it to describe both what the skill does and when to use it. When a request matches, the agent reads the full body. Bundled resources never enter context until the body references them, which is why supporting material can be effectively unbounded.

The open standard frames the same flow as Discovery, Activation, and Execution. For the full model, see Anthropic's overview and the agentskills.io home page.

What a skill looks like

A skill is, at minimum, a folder containing one SKILL.md file. Everything else is optional and loaded only when referenced:

my-skill/
├── SKILL.md       # Required: frontmatter (name + description) + Markdown instructions
├── references/    # Optional: extra docs the agent reads on demand
├── scripts/       # Optional: code the agent runs via the shell
└── assets/        # Optional: templates, schemas, images, data files

The folder name should match the name in the frontmatter. Here is a minimal, valid SKILL.md with the two required fields:

---
name: roll-dice
description: Rolls one or more dice and returns the results. Use when the user asks to roll dice, flip for a decision, or pick a random number in a range.
---

# Roll dice

When the user asks to roll dice, parse the count and number of sides (default to one six-sided die),
then return each roll and the total.

The dnx skills init command scaffolds this layout for you; Authoring Skills walks through it with the generated SKILL.md and folder tree. The full field reference, including optional frontmatter, lives in the open specification and in Authoring Skills.

Why Skills

The skills CLI brings the install-once, run-anywhere skill workflow to the .NET SDK. Three things make it worth adding to your toolbox.

Project-scoped installs are recorded in a skills-lock.json file in your working directory. Commit it, and your whole team shares one reproducible skill set, the same way a lock file pins your package dependencies.

One install reaches every detected agent. The CLI materializes each skill once in a canonical store, then links it into the directory each installed agent expects. You do not manage per-agent copies by hand.

Personal skills install globally with --global. Those live outside any single project and follow you across every repository you work in.

The ecosystem

The Agent Skills world has three distinct layers. Knowing which is which helps you find what you need.

The skills CLI brings the npx skills workflow to the .NET SDK via dnx, so you can run it without a global install. The command surface deliberately mirrors what Node developers already know. The CLI has no registry of its own: you point dnx skills add at any git repository or local folder, and you discover skills to install from directories like skills.sh.

Next steps

• Get started: run skills and add your first skill end to end.
• Author a skill: scaffold a SKILL.md, write a strong description, and publish it.

Website Content Docs Strawberryshake Index (`website/content/docs/strawberryshake/index.md`) Copy Section

title: Strawberry Shake metaTitle: "Strawberry Shake: GraphQL Client for .NET" Copy Chapter

Strawberry Shake is an open-source GraphQL client for .NET. It generates strongly typed C# client code from your GraphQL operations and provides reactive APIs for working with local and remote data. It works with spec-compliant servers including Hot Chocolate, Apollo Server, and GraphQL Java.

You can use Strawberry Shake to:

• Generate a C# .NET client from your GraphQL queries.
• Interact with local and remote data through GraphQL.
• Use reactive APIs to interact with your state.

Follow the getting-started guide to configure a client and run your first operation.

Website Content Docs Hotchocolate Defining A Schema Index (`website/content/docs/hotchocolate/defining-a-schema/index.md`) Copy Section

title: "Type System" Copy Chapter

A GraphQL schema defines the contract that clients interact with. It specifies the available operations, selectable fields, accepted arguments, and the structure of responses.

Hot Chocolate enables you to define this contract in C# and review the resulting GraphQL SDL. This page serves as your guide: it introduces the main type system concepts, demonstrates how a C# model translates to SDL, and directs you to detailed pages for each modeling task.

Understanding the Schema as the API Contract

When working with GraphQL, everything starts with the schema. The schema defines the contract between your API and its clients, describing the available operations and the data that can be requested.

Clients interact with your API by sending GraphQL operations. They do not call your C# methods or classes directly. Instead, they rely on the schema to understand what is possible.

To introduce the main concepts of the GraphQL type system, consider the following example. This schema highlights the essential building blocks you will encounter:

type Query {
  bookById(id: ID!): Book
}

type Mutation {
  createBook(input: CreateBookInput!): Book!
}

type Book {
  id: ID!
  title: String!
  authors: [Author!]!
}

type Author {
  id: ID!
  name: String!
}

input CreateBookInput {
  title: String!
  authorIds: [ID!]!
}

This example presents queries, mutations, object types, input types, and scalar values. Each part of the schema plays a specific role in shaping how clients interact with your API. The table below breaks down these elements and explains their purpose within the type system.

If you are unsure how to identify the parts of your schema, start by looking at the SDL. Elements that a client can select in a query are fields. Values that a client supplies to those fields are arguments or input fields. When you see ! or [] wrapping another type, these are type modifiers that indicate non-nullability or lists.

For example, a client might send the following query and mutation:

query {
  bookById(id: "1") {
    title
    authors {
      name
    }
  }
}

mutation {
  createBook(input: { title: "New Book", authorIds: ["2"] }) {
    id
    title
  }
}

In these examples, bookById and createBook are fields. The id and input values are arguments. The selections inside the curly braces, such as title and authors, are fields on the returned types.

Schema Authoring Styles

Hot Chocolate offers two C# authoring styles, both of which produce GraphQL SDL.

Implementation-First Copy Chapter

The implementation-first approach allows you to define your GraphQL schema using standard C# types and attributes. This keeps your contract close to your domain code with minimal ceremony, provides compile-time feedback, and ensures a clear mapping between code and schema. This workflow is streamlined for most application schemas.

Common building blocks include:

• [QueryType], [MutationType], and [SubscriptionType] for operation root fields
• partial source-generator classes for annotated root type classes
• Attributes such as [GraphQLName], [GraphQLDescription], [GraphQLIgnore], [ID], [Node], [InterfaceType], [UnionType], and [OneOf] when the inferred schema needs guidance
• Generated dependency injection modules for GraphQL types

Code-First Copy Chapter

The code-first approach allows you to define GraphQL types and their structure directly in C# using the Hot Chocolate type descriptor API. This is useful when your GraphQL schema needs to differ from your C# model or when building reusable schema components.

using HotChocolate.Types;

public sealed class BookType : ObjectType<Book>
{
    protected override void Configure(IObjectTypeDescriptor<Book> descriptor)
    {
        descriptor
            .Field(t => t.Title)
            .Type<NonNullType<StringType>>()
            .Description("The title displayed to readers.");
    }
}

Navigating the Type System Map

The following map helps you select the next detailed page without needing to learn every rule here.

Root Types Copy Chapter

GraphQL defines a single root type for each operation kind. In C#, you can organize root fields across multiple semantic classes, and Hot Chocolate will merge them into the final root type.

Output Types Copy Chapter

Output types describe the shapes of data that clients can select after a field resolves.

Fields and Arguments Copy Chapter

Fields and arguments define how clients interact with your schema. Fields are selectable members on types, while arguments allow clients to supply values to those fields.

Not every C# method parameter becomes an argument. Service parameters, parent values, cancellation tokens, and resolver context parameters are resolver concerns.

Input Types Copy Chapter

Input types define the shapes of data that clients can send to your API, such as arguments and input objects for mutations and queries.

GraphQL separates input and output type systems. Input objects can use defaults, Optional<T>, and @oneOf, but those rules are detailed on the input pages.

Type Modifiers Copy Chapter

Type modifiers such as non-null and list indicate whether a field or argument is required or can accept multiple values.

Input optionality, default values, and output nullability are related but not identical. Refer to the type modifier and input object pages when the distinction matters.

Schema Organization and Advanced Modeling Copy Chapter

Organize your schema for maintainability and support advanced modeling scenarios using type extensions, Relay helpers, and dynamic schemas.

Contract Metadata and Lifecycle Copy Chapter

Metadata and lifecycle features help you document, annotate, and evolve your schema safely over time.

Use type extensions for static modularity. Choose dynamic schemas only when the schema must change based on external metadata or runtime configuration.

Next steps

• Build a read entry point with Queries.
• Learn how returned shapes are inferred and configured in Object Types.
• Add field inputs with Arguments and Input Object Types.
• Strengthen the contract with Lists and Non-Null.
• Move to runtime behavior with Resolvers and DataLoader after the schema shape is clear.

Website Content Docs Hotchocolate Fetching Data Index (`website/content/docs/hotchocolate/fetching-data/index.md`) Copy Section

title: Fetching Data Copy Chapter

Hot Chocolate provides data middleware that applies common operations directly to your IQueryable or IExecutable data sources. Instead of implementing pagination, filtering, sorting, and projections by hand, you declare them on your fields and Hot Chocolate generates the corresponding GraphQL types and applies the operations at execution time.

Pagination

Hot Chocolate provides cursor-based connection pagination out of the box. Connections follow the Relay Cursor Connections Specification, giving clients a standardized way to page through large datasets. When backed by IQueryable, pagination translates directly to native database queries.

Learn more about pagination

Filtering

When you return a list of entities, clients often need to filter them by operations like equals, contains, or startsWith. Hot Chocolate generates the necessary filter input types from your .NET models and translates applied filters into native database queries.

Learn more about filtering

Sorting

Hot Chocolate generates sort input types from your .NET models, allowing clients to specify which fields to sort by and in which direction. Like filtering, sort operations translate to native database queries when backed by IQueryable.

Learn more about sorting

Projections

Projections optimize database queries by selecting only the columns that match the fields requested in the GraphQL query. If a client requests name and id, Hot Chocolate queries only those columns from the database.

Learn more about projections

Batching

DataLoaders and batch resolvers solve the N+1 problem in GraphQL. When the execution engine resolves a list of objects and each needs related data, a DataLoader collects all individual requests and sends a single query for all keys at once.

• DataLoader for key-based batching with deduplication and caching.
• Batch Resolvers for simpler cases where caching is not needed.

Integrations

Hot Chocolate is not bound to a specific database. The data middleware works with any IQueryable provider. We provide specific guidance for the most common data sources:

• Entity Framework for EF Core DbContext patterns and pooling.
• MongoDB for the MongoDB driver integration.
• Marten for Marten document database support.
• Extending Filtering for building custom filter providers.

Website Content Docs Hotchocolate Performance Index (`website/content/docs/hotchocolate/performance/index.md`) Copy Section

title: Performance Copy Chapter

This section covers ways to improve the performance of your Hot Chocolate GraphQL server.

Startup Performance

Hot Chocolate constructs the schema eagerly at startup by default. You can register warmup tasks to pre-populate in-memory caches before the server begins accepting requests.

Learn more about server warmup

Trusted Documents

The size of individual GraphQL requests can become a significant bottleneck. This affects both the transport layer and the server, since large requests need to be parsed and validated repeatedly. Hot Chocolate supports persisted operations (also known as trusted documents) to address this. With persisted operations, you store operation documents on the server in a key-value store. When executing a persisted operation, the client sends the key under which the operation document is stored instead of the full document. This saves bandwidth and improves execution time because the server validates, parses, and compiles persisted operation documents only once.

Hot Chocolate supports two flavors of persisted operations.

Regular Persisted Operations Copy Chapter

The first approach stores operation documents ahead of time (before deployment). You extract the operations from your client applications at build time. This reduces the size of requests and the bundle size of your application because operations can be removed from the client code at build time and replaced with operation document hashes.

Strawberry Shake, Relay, and Apollo client all support this approach.

Learn more about persisted operations

Automatic Persisted Operations Copy Chapter

Automatic persisted operations let you store operation documents dynamically on the server at runtime. This approach gives your applications the same performance benefits as regular persisted operations without requiring a more complex build process.

However, you do not get bundle size improvements for your applications because the operations are still needed at runtime.

Both Strawberry Shake and Apollo client support this approach.

Learn more about automatic persisted operations

Website Content Docs Hotchocolate Resolvers Index (`website/content/docs/hotchocolate/resolvers/index.md`) Copy Section

title: Resolvers metaTitle: "GraphQL Resolvers in Hot Chocolate" Copy Chapter

Every field in a GraphQL schema is backed by a resolver function that produces the field's value. Understanding how resolvers compose into a tree is the key mental model for building efficient GraphQL APIs with Hot Chocolate.

The Resolver Tree

When Hot Chocolate receives a query, it builds a resolver tree that mirrors the shape of the request. Consider this query:

query {
  me {
    name
    company {
      id
      name
    }
  }
}

This produces the following resolver tree:

graph LR
  A(query: QueryType) --> B(me: UserType)
  B --> C(name: StringType)
  B --> D(company: CompanyType)
  D --> E(id: IdType)
  D --> F(name: StringType)

The execution engine traverses this tree starting from root resolvers. A child resolver can only execute after its parent has produced a value. Sibling resolvers at the same level run in parallel. Because of this parallel execution, resolvers (except top-level mutation field resolvers) must be free of side effects.

Execution completes when every resolver in the tree has produced a result.

Defining a Resolver

Resolvers can be defined in a way that should feel very familiar to C# developers, as they either translate to methods or delegates.

[QueryType]
public partial class Query
{
    public static string Foo() => "Bar";
}

type Query {
  foo: String!
}

[QueryType]
public partial class Query
{
    public static User User => new User("Ted");
}

public record User(string Name);

public class QueryType : ObjectType
{
    protected override void Configure(IObjectTypeDescriptor<Query> descriptor)
    {
        descriptor
            .Field("foo")
            .Type<NonNullType<StringType>>()
            .Resolve(ctx => "bar");
    }
}

public class Query
{
    public string Foo() => "Bar";
}

public class QueryType : ObjectType<Query>
{
    protected override void Configure(IObjectTypeDescriptor<Query> descriptor)
    {
        descriptor
            .Field(f => f.Foo())
            .Type<NonNullType<StringType>>();
    }
}

Async Resolver Copy Chapter

Resolvers can be synchronous or asynchronous. Most data fetching operations, such as calling a service or database, are asynchronous.

The most important aspect of async resolvers is to honor the CancellationToken. This allows execution to be cancelled if the client abandons the request, preventing unnecessary work and resource usage.

public class Query
{
    public async Task<Product> GetProductByIdAsync(
      int id,
      ProductService productService,
      CancellationToken cancellationToken)
      => await productService.GetAsync(cancellationToken);
}

descriptor
    .Field("foo")
    .Resolve(context =>
    {
        CancellationToken ct = context.RequestAborted;

        // Omitted code for brevity
    });

Arguments

In GraphQL, fields are conceptually similar to methods in C#. Just like methods, fields can have arguments, and you can access these argument values directly in your resolvers.

public class Query
{
    public async Task<Product> GetProductByIdAsync(
      int id,
      ProductService productService,
      CancellationToken cancellationToken)
      => await productService.GetAsync(cancellationToken);
}

descriptor
    .Field("foo")
    .Argument("id", a => a.Type<NonNullType<IntType>>())
    .Resolve(context =>
    {
        var id = context.ArgumentValue<int>("id");

        // Omitted code for brevity
    });

Learn more about arguments

Injecting Services

Hot Chocolate automatically recognizes types registered in the DI container and injects them into resolver parameters.

public class Query
{
    public List<User> GetUsers(UserService userService)
        => userService.GetUsers();
}

While you can take attributes to annotate services, you do not have to for non-keyed services.

public class Query
{
    public List<User> GetUsers([Service] UserService userService)
        => userService.GetUsers();
}

Learn more about dependency injection

Accessing parent values

Each field resolver has access to the value that was resolved for its parent type.

For example, consider the following schema:

type Query {
  me: User!;
}

type User {
  id: ID!;
  friends: [User!]!;
}

The User schema type is represented by a User runtime class. The id field is a property on this class.

public class User
{
    public string Id { get; set; }
}

The friends resolver, by contrast, is independent: it is not declared on the User type and uses the user's Id to compute its result.
From the friends resolver's perspective, the User runtime object is its parent.

Access the parent value like this:

[ObjectType<User>]
public static partial class UserNode
{
    public static Task<List<User>> GetFriendsAsync(
        [Parent] User user,
        UserService userService,
        CancellationToken cancellationToken)
    {
        // Omitted code for brevity
    }
}

[ObjectType<User>]
public static partial class UserNode
{
    public static Task<List<User>> GetFriendsAsync(
        [Parent(requires: nameof(User.Id))] User user,
        UserService userService,
        CancellationToken cancellationToken)
    {
        // Omitted code for brevity
    }
}

public class User
{
    public string Id { get; set; }
}

public class UserType : ObjectType<User>
{
    protected override void Configure(IObjectTypeDescriptor<User> descriptor)
    {
        descriptor
            .Field("friends")
            .Resolve(context =>
            {
                User parent = context.Parent<User>();

                // Omitted code for brevity
            });
    }
}

What's in This Section

• Dependency Injection explains how services are injected into resolvers, scoping behavior, keyed services, and switching the service provider.
• Errors covers how exceptions become GraphQL errors, error filters for mapping domain exceptions, and throwing GraphQLException for explicit errors.
• Field Middleware shows how to build reusable middleware that runs before or after resolvers, including ordering, class-based middleware, and attribute-based middleware.

Website Content Docs Hotchocolate Security Index (`website/content/docs/hotchocolate/security/index.md`) Copy Section

title: Securing Your API Copy Chapter

Securing a GraphQL API requires more than authentication and authorization. Unlike REST, where each endpoint has a predictable cost, a single GraphQL query can traverse deep relationships and request large datasets. You need a strategy that matches your API's threat model.

Hot Chocolate provides two golden paths depending on whether your API is public or private.

Public APIs: Cost Analysis

Public APIs face unpredictable clients. You do not control who sends queries or how complex those queries are. An attacker can craft a deeply nested query that consumes significant server resources.

Cost analysis is your primary defense for public APIs. It compiles each operation into a cost plan and evaluates that plan with the request's coerced variables. Queries that exceed a configured field-cost, type-cost, or response-size limit are rejected before execution.

Combine cost analysis with:

• Pagination limits to cap the number of items returned per connection.
• Execution depth limits to prevent deeply nested queries.
• Execution timeouts to abort long-running queries.

Learn more about cost analysis

Private APIs: Trusted Documents

Private APIs serve known clients that you control, such as your own web or mobile applications. For these APIs, trusted documents (also called persisted operations) provide the strongest security guarantee.

With trusted documents, you extract all GraphQL operations from your client at build time and register them with the server. At runtime, the server only accepts operations it recognizes. This eliminates the risk of arbitrary queries entirely.

Learn more about trusted documents

Defense in Depth

Regardless of whether your API is public or private, apply these additional protections:

Authentication Copy Chapter

Authentication determines who is making a request. Hot Chocolate integrates with the ASP.NET Core authentication system, supporting JWT, cookies, and other authentication schemes.

Learn more about authentication

Authorization Copy Chapter

Authorization controls what an authenticated user can access. Hot Chocolate provides the @authorize directive for field-level and type-level access control, integrating with ASP.NET Core roles and policies.

Learn more about authorization

Request Limits Copy Chapter

Hot Chocolate enforces limits during parsing, validation, and execution. These include limits on fields, directives, nesting depth, execution depth, and execution time.

Learn more about request limits

Introspection Copy Chapter

Introspection powers developer tools but can also reveal your schema to attackers. You can restrict or disable introspection in production.

Learn more about introspection

FIPS Compliance Copy Chapter

Hot Chocolate uses MD5 for document hashing by default. If you need FIPS compliance, switch to SHA256:

builder
    .AddGraphQL()
    .AddSha256DocumentHashProvider();

Learn more about hashing providers

Next Steps

• Building a public API? Start with Cost Analysis.
• Building a private API? Start with Trusted Documents.
• Need authentication? See Authentication.
• Need authorization? See Authorization.

Website Content Docs Hotchocolate Server Index (`website/content/docs/hotchocolate/server/index.md`) Copy Section

title: Server Copy Chapter

This section covers how you configure and operate a Hot Chocolate GraphQL server. You will find details on transport protocols, middleware, dependency injection, and runtime behavior.

Endpoints

Hot Chocolate provides ASP.NET Core endpoint middleware for accepting HTTP and WebSocket GraphQL requests, downloading the schema, and serving the Nitro GraphQL IDE.

Learn more about endpoints

HTTP Transport

Hot Chocolate implements the GraphQL over HTTP specification. The default incremental delivery format is v0.2, and clients can select the format through the Accept header.

Learn more about the HTTP transport

Cache Control

Cache control lets your GraphQL server emit Cache-Control and Vary response headers that CDNs, reverse proxies, and browsers can use for HTTP caching decisions.

Learn more about cache control

Interceptors

Interceptors let you intercept GraphQL requests before execution. There are interceptors for both HTTP requests and WebSocket sessions.

For WebSockets, the interceptor also handles lifecycle events such as when a client first connects.

Learn more about interceptors

Dependency Injection

Hot Chocolate recognizes services registered in your DI container and injects them into resolvers automatically. Services are resolved implicitly without requiring the [Service] attribute.

Learn more about dependency injection

Warmup

Hot Chocolate constructs the schema eagerly at startup. You can go further by registering warmup tasks that pre-populate caches before the server begins accepting traffic.

Learn more about warmup

Global State

Global State lets you define properties on a per-request basis and makes them available to all resolvers and middleware.

Learn more about global state

Introspection

Introspection lets you query the type system of your GraphQL server using regular GraphQL queries. While this powers developer tooling, it can also be an attack vector. You can control who is allowed to issue introspection queries.

Learn more about introspection

Files

Hot Chocolate provides file upload support through the Upload scalar, even though file handling is not traditionally a GraphQL server concern. You can also return presigned URLs for a hybrid approach.

Learn more about handling files

Instrumentation

Hot Chocolate exposes diagnostic events across the server, execution engine, and DataLoader layers. The built-in OpenTelemetry integration aligns with the proposed GraphQL semantic conventions.

Learn more about instrumentation

Batching

Batching lets you send and execute multiple GraphQL operations in a single request. Variable batching is enabled by default. Request batching is disabled by default and can be enabled through the AllowedBatching flags enum.

Learn more about batching

Command Line

The command-line interface lets you export your GraphQL schema from the terminal, which is useful for CI/CD pipelines.

Learn more about the command line

Website Content Docs Mocha Mediator Index (`website/content/docs/mocha/mediator/index.md`) Copy Section

title: Mediator Copy Chapter

builder.Services
    .AddMediator()
    .AddCatalog(); // source-generated from your assembly name

That registers the mediator infrastructure, discovers your handlers at compile time, and wires up the dispatch pipeline. .AddCatalog() is a source-generated extension method - it knows your handlers and message types at compile time and produces direct dispatch code with no reflection.

What the mediator is

The mediator sits between your application code and your handlers. Instead of injecting handler interfaces directly, you inject IMediator (or ISender / IPublisher) and dispatch messages through it. The mediator routes each message to the correct handler based on its type.

// Without mediator - tight coupling
app.MapPost("/orders", async (PlaceOrderCommandHandler handler) =>
    await handler.HandleAsync(new PlaceOrderCommand(...)));

// With mediator - decoupled dispatch
app.MapPost("/orders", async (ISender sender) =>
    await sender.SendAsync(new PlaceOrderCommand(...)));

The mediator provides three things your handlers cannot do alone: a middleware pipeline that wraps every handler invocation with cross-cutting concerns (logging, transactions, validation), polymorphic dispatch that routes messages by type at runtime, and a seam between your application layer and your domain logic. This is the Mediator pattern -- objects communicate through a central hub instead of referencing each other directly.

If you have used MediatR, the concepts are familiar. Mocha Mediator takes a different approach to performance: a Roslyn source generator analyzes your handler registrations at compile time and produces pre-compiled pipeline delegates. No MakeGenericType, no service provider lookups to resolve the pipeline, no reflection at runtime.

When to use the mediator vs. the message bus

Mocha has two dispatch mechanisms. Use the right one for the situation:

The mediator and the message bus complement each other. A common pattern is to use the mediator for in-process CQRS dispatch within a service, and the message bus for inter-service event-driven communication.

Messages

Messages are plain C# types that implement a marker interface. The marker interface tells the mediator how to route the message and what return type to expect.

Commands Copy Chapter

Commands represent actions that change state. Use imperative verb-noun naming: PlaceOrder, ProcessPayment.

// A command that returns no response
public record DeleteOrderCommand(Guid OrderId) : ICommand;

// A command that returns a response
public record PlaceOrderCommand(
    Guid ProductId,
    int Quantity,
    string CustomerId) : ICommand<PlaceOrderResult>;

public record PlaceOrderResult(bool Success, Guid? OrderId = null, string? Error = null);

Queries Copy Chapter

Queries represent read operations that return data without side effects. Use noun-based naming: GetProducts, GetOrderById.

public record GetProductsQuery : IQuery<List<Product>>;

public record GetProductByIdQuery(Guid Id) : IQuery<Product?>;

Notifications Copy Chapter

Notifications represent events that multiple handlers can observe. Use past-tense naming: OrderPlaced, PaymentCompleted.

public record OrderPlacedNotification(
    Guid OrderId,
    decimal Amount) : INotification;

Message type reference Copy Chapter

Handlers

Each message type has a corresponding handler interface. The mediator routes each message to exactly one handler - except notifications, which fan out to all registered handlers.

Command handlers Copy Chapter

// Handles a void command
public sealed class DeleteOrderCommandHandler(AppDbContext db)
    : ICommandHandler<DeleteOrderCommand>
{
    public async ValueTask HandleAsync(
        DeleteOrderCommand command, CancellationToken cancellationToken)
    {
        var order = await db.Orders.FindAsync(command.OrderId);
        if (order is not null)
        {
            db.Orders.Remove(order);
            await db.SaveChangesAsync(cancellationToken);
        }
    }
}

// Handles a command with a response
public sealed class PlaceOrderCommandHandler(AppDbContext db)
    : ICommandHandler<PlaceOrderCommand, PlaceOrderResult>
{
    public async ValueTask<PlaceOrderResult> HandleAsync(
        PlaceOrderCommand command, CancellationToken cancellationToken)
    {
        var order = new Order
        {
            Id = Guid.NewGuid(),
            ProductId = command.ProductId,
            Quantity = command.Quantity,
            CustomerId = command.CustomerId
        };

        db.Orders.Add(order);
        await db.SaveChangesAsync(cancellationToken);

        return new PlaceOrderResult(true, order.Id);
    }
}

Query handlers Copy Chapter

public sealed class GetProductsQueryHandler(AppDbContext db)
    : IQueryHandler<GetProductsQuery, List<Product>>
{
    public async ValueTask<List<Product>> HandleAsync(
        GetProductsQuery query, CancellationToken cancellationToken)
        => await db.Products.ToListAsync(cancellationToken);
}

Notification handlers Copy Chapter

Multiple handlers can subscribe to the same notification type. The mediator invokes all of them.

public sealed class SendOrderConfirmationEmail(IEmailService email)
    : INotificationHandler<OrderPlacedNotification>
{
    public async ValueTask HandleAsync(
        OrderPlacedNotification notification, CancellationToken cancellationToken)
    {
        await email.SendAsync(
            $"Order {notification.OrderId} confirmed", cancellationToken);
    }
}

public sealed class UpdateAnalyticsDashboard(IAnalytics analytics)
    : INotificationHandler<OrderPlacedNotification>
{
    public async ValueTask HandleAsync(
        OrderPlacedNotification notification, CancellationToken cancellationToken)
    {
        await analytics.RecordOrderAsync(
            notification.OrderId, notification.Amount);
    }
}

Handler interface reference Copy Chapter

Dispatching messages

Inject IMediator, ISender, or IPublisher from DI and call the appropriate method.

// Send a command with a response
app.MapPost("/orders", async (PlaceOrderRequest request, ISender sender) =>
{
    var result = await sender.SendAsync(
        new PlaceOrderCommand(request.ProductId, request.Quantity, request.CustomerId));

    return result.Success
        ? Results.Created($"/api/orders/{result.OrderId}", result)
        : Results.BadRequest(result.Error);
});

// Send a query
app.MapGet("/products", async (ISender sender) =>
    await sender.QueryAsync(new GetProductsQuery()));

// Publish a notification
app.MapPost("/orders/{id}/ship", async (Guid id, IPublisher publisher) =>
{
    await publisher.PublishAsync(new OrderShippedNotification(id));
    return Results.Ok();
});

ISender handles commands and queries. IPublisher handles notifications. IMediator combines both interfaces - inject it when you need both in the same class.

Untyped dispatch Copy Chapter

When the message type is not known at compile time, use the object-based overloads:

// Dispatch a command or query by runtime type
object message = GetMessageFromSomewhere();
object? result = await sender.SendAsync(message);

// Dispatch a notification by runtime type
object notification = GetNotificationFromSomewhere();
await publisher.PublishAsync(notification);

The runtime type of the message must implement one of the marker interfaces (ICommand, ICommand, IQuery, or INotification). An exception is thrown if it does not.

Registration and source generation

Register the mediator Copy Chapter

builder.Services
    .AddMediator()
    .AddCatalog(); // source-generated from assembly name "Demo.Catalog"

AddMediator() registers the core mediator infrastructure and the default notification publish mode. The source-generated Add{ModuleName}() method registers:

• All command, query, and notification handlers found in your assembly
• Pre-compiled terminal delegates for each message type (no reflection at runtime)

You do not register handlers manually unless you need to. The source generator discovers them by scanning for classes that implement handler interfaces.

Module naming Copy Chapter

The source generator names the registration method based on your assembly:

1. If you apply #!csharp [assembly: MediatorModule("Billing")], the method is AddBilling()
2. Otherwise, it uses the last segment of the assembly name: Demo.Catalog produces AddCatalog()

To set an explicit module name, add the attribute to any file in your project:

using Mocha.Mediator;

[assembly: MediatorModule("Billing")]

Manual handler registration with AddHandler Copy Chapter

When you need to register handlers outside the source generator's reach - from a plugin assembly, a dynamically loaded module, or in integration tests - use AddHandler<T>():

builder.Services
    .AddMediator()
    .AddHandler<PlaceOrderCommandHandler>()
    .AddHandler<GetProductsQueryHandler>()
    .AddHandler<OrderShippedEmailHandler>();

AddHandler<T>() inspects the type for handler interfaces (ICommandHandler, IQueryHandler, INotificationHandler), builds the pipeline configuration, and registers the handler in DI. It throws InvalidOperationException if T does not implement a handler interface.

You can mix source-generated and manual registration. If both register the same handler type, the configurations are composed:

builder.Services
    .AddMediator()
    .AddCatalog()                              // source-generated handlers
    .AddHandler<ExternalPaymentHandler>();      // additional handler from another assembly

Prefer the source generator. The source-generated registration path uses pre-compiled terminal delegates with no reflection. The source-generated output is designed for long-term stability across versions. Manual registration is available for edge cases but its internal behavior may change between releases.

Configure service lifetime Copy Chapter

By default, handlers are registered as Scoped. To change the default:

builder.Services
    .AddMediator()
    .ConfigureOptions(options =>
    {
        options.ServiceLifetime = ServiceLifetime.Transient;
    })
    .AddCatalog();

Call ConfigureOptions before Add{ModuleName}() so the source-generated method reads the updated lifetime.

Configuration options reference Copy Chapter

Named mediators

To run multiple independent mediator instances (each with its own handlers and middleware), use named mediators. Named mediators use .NET's keyed dependency injection.

// Register a named mediator
builder.Services
    .AddMediator("billing")
    .AddBilling();

// Register the default (unnamed) mediator
builder.Services
    .AddMediator()
    .AddCatalog();

Resolve a named mediator from DI:

app.MapPost("/payments", async (
    [FromKeyedServices("billing")] ISender sender,
    ProcessPaymentRequest request) =>
{
    var result = await sender.SendAsync(
        new ProcessPaymentCommand(request.Amount));
    return Results.Ok(result);
});

// Or resolve from IServiceProvider directly
var billingMediator = serviceProvider
    .GetRequiredKeyedService<IMediator>("billing");

Each named mediator has its own handler registrations, middleware pipeline, and runtime. The default mediator (registered with AddMediator() without a name) is resolved normally without keyed services.

Putting it together

Here is a complete minimal API application with commands, queries, and notifications:

/* Detailed source-code truncated for AI context efficiency. */

If everything worked, dotnet run starts the server and you can:

• POST /orders with a JSON body to place an order
• GET /products to list products
• #!http POST /orders/{id}/ship to publish a shipped notification

Troubleshooting

`InvalidOperationException: No pipeline registered for message type` Copy Chapter

The source generator did not find a handler for your message type. Verify:

• Your handler class implements the correct interface (e.g., ICommandHandler<YourCommand, YourResponse>)
• Your message type implements the correct marker interface (e.g., ICommand<YourResponse>)
• You called the source-generated .Add{ModuleName}() method on the mediator builder
• The handler is in the same project that the source generator can see
• The project references Mocha.Analyzers as an analyzer (not a regular project reference)

Handlers are not being called Copy Chapter

If dispatch succeeds but your handler code does not execute, check that:

• Your middleware calls the next delegate - a middleware that forgets to call next silently short-circuits the pipeline
• You are not accidentally registering handlers manually in addition to the source-generated method, which could result in duplicate registrations

The source-generated method does not appear Copy Chapter

If IntelliSense does not show Add{ModuleName}():

• Confirm the Mocha.Analyzers package is referenced with OutputItemType="Analyzer" in your .csproj
• Rebuild the project - source generators run during compilation
• Check the build output for analyzer warnings prefixed with MO

`InvalidOperationException` when calling `AddHandler()` Copy Chapter

The type you passed does not implement any handler interface. Make sure T implements one of: ICommandHandler<TCommand>, ICommandHandler<TCommand, TResponse>, IQueryHandler<TQuery, TResponse>, or INotificationHandler<TNotification>.

Named mediator returns wrong handlers Copy Chapter

Each named mediator resolves handlers from the same DI container. Make sure you register each module's handlers on the correct IMediatorHostBuilder instance - the one returned by the AddMediator("name") call for that name.

Next steps

You have a working mediator with CQRS dispatch. Here is where to go next:

• Customize the pipeline: Pipeline & Middleware - add validation, logging, transactions, and other cross-cutting concerns. Configure notification publish modes and OpenTelemetry instrumentation.

Website Content Docs Mocha Transports Index (`website/content/docs/mocha/transports/index.md`) Copy Section

title: "Transports" Copy Chapter

A transport is the infrastructure layer that connects Mocha to a message broker. It manages connections, provisions topology (exchanges, queues, bindings), and handles the low-level details of dispatching and receiving messages. You write handlers and publish messages. The transport handles the rest.

The transport abstraction means your handlers, patterns, and pipeline are identical regardless of which broker you use. Only the infrastructure changes. Swap .AddInMemory() for .AddPostgres(), .AddRabbitMQ(), or .AddAzureServiceBus() and your application code stays unchanged. This portability is the core value of the Message Channel pattern: the sender and receiver are decoupled from the physical infrastructure that carries the message.

Mocha ships with four transports:

Add a transport

Every transport implements the same MessagingTransport base class. The transport is always the last call in the builder chain:

// InMemory - zero configuration
builder.Services
    .AddMessageBus()
    .AddEventHandler<OrderPlacedEventHandler>()
    .AddInMemory();

// RabbitMQ - production-ready
builder.Services
    .AddMessageBus()
    .AddEventHandler<OrderPlacedEventHandler>()
    .AddRabbitMQ();

// PostgreSQL - database-backed transport
builder.Services
    .AddMessageBus()
    .AddEventHandler<OrderPlacedEventHandler>()
    .AddPostgres("Host=localhost;Database=mocha_messaging;Username=postgres;Password=postgres");

// Azure Service Bus - managed cloud messaging
builder.Services
    .AddMessageBus()
    .AddEventHandler<OrderPlacedEventHandler>()
    .AddAzureServiceBus(connectionString);

Each Add{Transport}() method registers a transport instance, applies default conventions, and wires up the middleware pipelines.

Choose a transport

Use this decision matrix to pick the right transport. Each column includes trade-offs - choose the one whose trade-offs you can accept:

InMemory limitations: Because all messages live in process memory, the InMemory transport cannot model multi-service fan-out, cannot survive process restarts, and does not exercise RabbitMQ-specific behavior like connection recovery, acknowledgement semantics, or topology conflicts.

PostgreSQL trade-offs: PostgreSQL is a good fit when you already operate PostgreSQL and want database-backed messaging without another broker. It favors operational simplicity and transactional consistency over dedicated broker throughput.

RabbitMQ operational cost: RabbitMQ requires expertise to operate in production - cluster management, disk and memory alarms, queue type selection, and monitoring. Use a managed broker (CloudAMQP, Amazon MQ) if you want to reduce operational burden.

Azure Service Bus trade-offs: Azure Service Bus is fully managed and durable, with native scheduling and cancellation. It is a strong fit for Azure-hosted workloads, while cost and available throughput depend on the namespace SKU.

Scope and middleware

Mocha uses a three-level feature scope: bus, transport, and endpoint. Features set at the bus level apply to all transports. Features set at the transport level override bus-level defaults for that transport. Features set at the endpoint level override both.

Bus scope (global defaults)
  └── Transport scope (transport-specific overrides)
       └── Endpoint scope (endpoint-specific overrides)

To add middleware at the transport level:

builder.Services
    .AddMessageBus()
    .AddRabbitMQ(transport =>
    {
        // Add dispatch middleware scoped to this transport
        transport.UseDispatch(myDispatchMiddleware);

        // Add receive middleware scoped to this transport
        transport.UseReceive(myReceiveMiddleware);

        // Insert middleware relative to existing ones
        transport.UseReceive(myMiddleware, after: "ConcurrencyLimiter");
        transport.UseDispatch(myMiddleware, before: "Serialization");
    });

This scoping model lets you run different middleware configurations per transport without affecting other transports in a multi-transport setup.

Customize queues and binding

Use transport.Queue("name") when you need to customize receive topology. The queue builder is the primary surface for custom queue names, multiple handlers on one queue, queue-level settings, and handler assignment.

builder.Services
    .AddMessageBus()
    .AddEventHandler<OrderPlacedEventHandler>()
    .AddRabbitMQ(transport =>
    {
        transport.BindExplicitly();

        transport.Queue("order-processing")
            .BindImplicitly()
            .Handler<OrderPlacedEventHandler>();
    });

Calling Queue("name") without a handler, consumer, or Receives<T>() declares only the queue. As soon as you add a handler, consumer, or received message type, Mocha materializes a receive endpoint for that queue.

Control implicit and explicit binding

By default, transports bind handlers implicitly using naming conventions:

builder.Services
    .AddMessageBus()
    .AddEventHandler<OrderPlacedEventHandler>()
    .AddRabbitMQ(transport =>
    {
        transport.BindImplicitly(); // This is the default
    });

With implicit transport binding, registered handlers are auto-discovered, assigned to convention-named queues, and connected to convention-derived exchange, topic, or subscription bindings.

Use BindExplicitly() at the transport scope when the queues you configure should be the complete receive topology:

builder.Services
    .AddMessageBus()
    .AddEventHandler<OrderPlacedEventHandler>()
    .AddRabbitMQ(transport =>
    {
        transport.BindExplicitly();

        transport.Queue("order-events")
            .BindImplicitly()
            .Handler<OrderPlacedEventHandler>();
    });

Use BindImplicitly() on the queue when you want a custom queue name but still want Mocha to generate the source bindings for that queue's handlers. Use BindExplicitly() on the queue when you provide those source bindings yourself, for example with BindFrom(...) or transport-specific topology declarations.

Claim handlers for a transport

When you need to keep the convention-derived queue name and only tune a single handler endpoint, use transport.Handler<T>() at the end of the transport configuration. This claims the handler for the transport and returns a descriptor that lets you configure the endpoint through ConfigureEndpoint():

builder.Services
    .AddMessageBus()
    .AddEventHandler<OrderPlacedEventHandler>()
    .AddRabbitMQ(transport =>
    {
        transport.Handler<OrderPlacedEventHandler>()
            .ConfigureEndpoint(e => e.MaxPrefetch(50).MaxConcurrency(10));
    });

The handler still gets a convention-named endpoint - Handler<T>() does not change the name. It gives you a handle to configure that endpoint without needing BindExplicitly() or knowing the endpoint name.

For raw IConsumer types, the equivalent is transport.Consumer<T>():

transport.Consumer<OrderAuditConsumer>()
    .ConfigureEndpoint(e => e.MaxConcurrency(3));

Handler<T>() and Consumer<T>() are the primary tool for multi-transport routing. When a handler is claimed by a transport, it is bound to that transport regardless of which transport is marked as the default.

Use multiple transports

You can register multiple transports and route specific handlers to specific transports. Mark one transport as the default with .IsDefaultTransport(). Any handler not explicitly claimed by another transport is bound to the default:

builder.Services
    .AddMessageBus()
    .AddEventHandler<OrderPlacedEventHandler>()
    .AddEventHandler<AuditHandler>()
    .AddRabbitMQ(r => r.IsDefaultTransport())       // default for unclaimed handlers
    .AddInMemory(m => m.Handler<AuditHandler>());   // AuditHandler claimed by InMemory
// OrderPlacedEventHandler → RabbitMQ (default, implicit)
// AuditHandler → InMemory (claimed)

You can also use the queue descriptor with explicit binding:

builder.Services
    .AddMessageBus()
    .AddEventHandler<OrderPlacedEventHandler>()
    .AddEventHandler<ClickStreamHandler>()
    // Default transport for most messages
    .AddRabbitMQ()
    // High-throughput transport for click-stream data
    .AddInMemory(transport =>
    {
        transport.BindExplicitly();

        transport.Queue("click-stream")
            .BindImplicitly()
            .Handler<ClickStreamHandler>();
    });

Each transport manages its own connections, topology, and middleware pipeline independently. A handler bound to one transport does not consume from another transport's endpoints.

Next steps

• InMemory Transport - Set up the InMemory transport for development and testing.
• PostgreSQL Transport - Configure database-backed messaging with PostgreSQL.
• RabbitMQ Transport - Configure the RabbitMQ transport for production deployments.
• Azure Service Bus Transport - Configure managed cloud messaging on Azure.

Runnable example: MultiTransport

Website Content Docs Nitro Apis Overview (`website/content/docs/nitro/apis/overview.md`) Copy Section

title: APIs Copy Chapter

An API within the context of Nitro, refers to a representation of your GraphQL Servers.
This representation is more than a mere conceptual framework — it serves as a practical tool that allows you to group your documents and share common settings like connection and authorization parameters among them.

Additionally, an API forms the foundation for your client registry, schema registry setup and the telemetry. For more detailed information on these features, refer to the Schema Registry guide
the Client Registry and the Telemetry guide.

API Types

API Collection Copy Chapter

A compilation of GraphQL Documents with shared connection settings, enabling the grouping of documents for sharing with your team.

API Service Copy Chapter

Incorporates all features of an API Collection and adds the capability to register your schema and clients in the schema registry. It also includes the use of telemetry for service monitoring. This type is ideal for representing a single deployment service or a subgraph.

API Gateway Copy Chapter

Encompasses all the features of the API Service, along with the ability to publish and manage fusion configuration. Additionally, it supports distributed telemetry for comprehensive monitoring of your Gateway.

Creating an API

Creating an API in Nitro is a user-friendly process. There are three methods available:

1. Click on the New API button located at the top of the document explorer toolbar.
2. Right-click within the document explorer and select New API from the context menu. This creates a new API within the currently selected folder. Note: APIs can be organized in folders but cannot be nested within each other.
3. Choose the API Type. Options include API Collection, API Service, or API Gateway.

Website Content Docs Nitro Documents Index (`website/content/docs/nitro/documents/index.md`) Copy Section

title: Documents Copy Chapter

The Document View is a feature that allows users to work with documents and API documents within the application. It provides functionality for executing queries, mutations, and subscriptions. This section describes the various components and functionalities available in the Document View.

1. Operation

The Operation section is where you can write and execute your queries, mutations, and subscriptions. It provides a convenient interface for interacting with the GraphQL API.

2. Schema Reference

The Schema Reference section allows you to explore the schema in a tree view or the explorer view. It provides detailed information about the available schema and its components. For more information on using the Schema Reference, refer to the Schema Reference guide.

3. Schema Definition

The Schema Definition section displays the schema definition in SDL (Schema Definition Language) format. It allows you to inspect the schema structure and understand its various types and fields. Refer to the Schema Definition guide for further details.

4. Document Status Indicator

The Document Status Indicator visually represents whether the current document is saved or not. A white dot indicates that the document is not saved, while a different icon may indicate a saved or modified state.

5. Query Editor

The Query Editor provides a dedicated space for writing your queries, mutations, and subscriptions. It offers features such as syntax highlighting, auto-completion, and error checking to assist in query composition. Learn more about using the query editor in the Operations guide.

6. Response Pane

The Response Pane displays the response of your queries, mutations, and subscriptions. It shows the data returned by the API and provides a structured view for easier analysis. Refer to the Response Pane guide for additional information.

7. Schema Indicator

The Schema Indicator is a visual cue that indicates the connection status with the GraphQL server and the successful retrieval of the schema. A green circle represents a connected state.

8. Connected Schema Endpoint

This section displays the currently connected schema endpoint, providing information about the GraphQL server being accessed.

9. Settings

The Document Settings section allows you to configure various settings specific to the document. Refer to the Connection Settings guide for detailed information about it. You can also configure the authentication settings for the document. Refer to the Authentication Settings guide for more details.

Website Content Docs Nitro Explore The Ui Index (`website/content/docs/nitro/explore-the-ui/index.md`) Copy Section

title: Explore the UI Copy Chapter

Let's explore the main components of the Nitro user interface:

1. Sidebar: The sidebar contains various icons representing different sections of the application. Interacting with these icons will alter the content displayed in the main area. For instance, in the current view, the highlighted icon indicates that we are in the Documents section. For detailed information, please refer to our guide on Documents.

2. Environments: This section is for managing environments.

3. History: This section displays the list of recently executed queries.

4. Settings: To modify application preferences, you can navigate to the Settings section. Learn more about it in our Settings Guide.

5. User Menu: This section allows users to sign in/out, manage their accounts, and handle billing. You can read more about account management and billing in the organization section Organizations.

6. Document Tree: Here you can manage files, folders, documents, and APIs. Read more about it in the Explorer.

7. Main Area: The main area showcases the content related to the selected section from the sidebar. In this instance, it displays the Documents section.

8. Status Bar: The status bar provides quick access to workspace, organization, and synchronization features. It also displays additional information. More details are provided in our Status Bar Guide.

Website Content Docs Nitro Organizations Index (`website/content/docs/nitro/organizations/index.md`) Copy Section

title: "Organizations" Copy Chapter

This guide will walk you through the features and functionalities of Nitro Organizations, a structure designed to help teams and individuals work efficiently and effectively on GraphQL related services.

What is an Organization

An organization typically represents an entire entity or a larger unit within an entity. Each organization can host multiple workspaces, allowing further categorization and organization of resources. A workspace might correspond to a specific project, a specific team within the organization, or a group of related APIs.

Each Nitro user has a personal organization. This is a private space for individual work or for projects that are not associated with any team or company organization. The personal organization is not visible to other users, is created by default and cannot be deleted.

Creating an Organization

Nitro allows for multiple organizations under one account. To add a new organization, navigate to the organization switcher in the status bar and click on the "Add Organization" button.

You will be redirected to the management portal. Here you can create a new organization by clicking the 'Create' button.

Each organization has a unique name and a display name which can be set during creation.
The name must be lowercase and may only include dashes (-) and underscores (_).

Managing Organizations

To manage your organizations, you have to open the management portal.

In the client app, you can do this by clicking 'Manage Organizations' and then 'Manage' on the organization that you'd like to manage.

You can also navigate to here to open the management portal and press 'Manage' on the organization that you like to manage.

Switching Organizations

In Nitro, you can be signed into multiple organizations at the same time and switch between them in the status bar. The organization switcher also allows you to create new organizations.

Managing Members

1. The count of members and the number of seats available in your subscription are displayed in the management overview section. (members/total seats)

2. This list show all the members of the organization and their role.

3. Members can be invited to join an organization via email. In the management overview section, the 'Invite User' section allows you to send an invitation email containing a join link.

4. Open invitations are displayed below. You can revoke an invitation by clicking on the 'Cancel' button. Once an invitation is expired, you can resend it by clicking on the 'Resend' button.

Joining an Organization Copy Chapter

Invited users can join an organization in two ways:

1. By clicking on the join link they received via email.
2. By opting to join during login on the sign in page.

During sign-in, the user can select into which organization (join orgs or personal) they want to sign in.

[Description of visualization: Screenshot showing the organization selection during sign-in]

User Roles and Access

There are three distinct roles within an organization: Owner, Admin, and Collaborator. Each role carries specific permissions:

• Owner: The owner can transfer ownership, delete the organization, and has all the permissions of an admin. Each organization can only have one owner.

• Admin: Admins can invite users to the organization, view subscriptions, and add redirect URLs. They also have all the permissions of a collaborator.

• Collaborator: Collaborators can log into the organization and leave the organization. They cannot add redirect URLs or invite new users.

Managing Permissions Copy Chapter

You can manage the permissions of each member in the member list.

1. Press the 'Edit' button on the right side of the member list to open the edit dialog.

2. Select the desired role for the member.

3. Press the 'Save' button to save the changes.

4. You can also remove a member from the organization by clicking on the 'Revoke Access' button.

Transferring Ownership

Ownership of the organization can be transferred to any existing member from the management portal.
In the danger zone section, click on the 'Transfer' button to transfer ownership.

Redirect URLs

Each time a user signs into an organization from a new origin, a redirect URL must be added to the organization.

This security measure is designed to prevent your access tokens from being leaked to any arbitrary site hosted by third parties.

If the user is a collaborator, they won't have the permissions to add the URL and will see an informative message. An admin, on the other hand, can directly add the URL to the organization.

You can add the redirect URL in two ways:

1. By signing in from the new origin. This will trigger a prompt to add the URL to the organization.

2. By adding the URL directly from the management portal.

In the portal you have more options to configure the allowed destinations. You can for example allow all localhost origins. Or disable the access to the web UI in the cloud

1. Configure the allowed types of origins.
2. Add redirect Urls to the organization.
3. Remove redirect Urls from the organization.

Website Content Docs Nitro Settings Index (`website/content/docs/nitro/settings/index.md`) Copy Section

title: Settings - Overview Copy Chapter

The Settings section provides users with various customization options. To access the settings, click on the cog icon located in the navigation bar on the left.

Currently, the most significant setting available is the Themes feature. This allows users to personalize the appearance and visual style of the application.

Please note that organization settings are exclusively accessible through the management portal. For more information about organization settings, refer to the Organizations documentation.

Website Content Docs Strawberryshake Caching Index (`website/content/docs/strawberryshake/caching/index.md`) Copy Section

title: "Caching" Copy Chapter

We are still working on the documentation for Strawberry Shake, so help us by finding typos, missing things, or write some additional docs with us.

StrawberryShake stores the result of GraphQL requests in a normalized entity store. The entity store allows your client to execute GraphQL requests with various strategies to reduce the need for network requests. Moreover, the normalized entities are updated by every request the client does, which means that you can build fully reactive components that change as the state in the store changes.

sequenceDiagram
    participant Generated Client
    participant Operation Store
    participant Entity Store
    participant GraphQL Server
    Generated Client->>Operation Store: Queries local store
    Operation Store->>GraphQL Server: Queries GraphQL server
    Note over Entity Store: Normalize response into entities
    GraphQL Server->>Entity Store: Returns GraphQL response
    Note over Operation Store: Builds operation result from entities
    Entity Store->>Operation Store: Returns entities for operation
    Operation Store->>Generated Client: Returns operation result

Strategies

We support three basic strategies to interact with the store and fetch data.

Network Only Copy Chapter

Network only is the simplest strategy and will fetch from the network and only then update the store. This means that our initial call will always get fresh data and at the same time update other request results watching the same entities.

If we use the reactive APIs in combination with network only we will still get updates whenever other requests fetch data for the entities we are watching.

Cache First Copy Chapter

Cache first is essentially the opposite of network only since it will first fetch from the store, and if the store has the data needed, it will not make any network requests. If the store does not have the data needed, it will go to the network and try to get the data and update the store.

Cache and Network Copy Chapter

The last strategy is a combination of the first two. The client will first try to get the data from the store. This gives us fast data response time if the store already has the data. After that the store will update that data for this request with data from the network which in consequence will trigger our subscription and serve us new data.

Configuration Copy Chapter

The global strategy default can be set on our dependency injection setup method.

builder.Services
    .AddConferenceClient(ExecutionStrategy.CacheFirst) // <----
    .ConfigureHttpClient(client => client.BaseAddress = new Uri("http://localhost:5050/graphql"))
    .ConfigureWebSocketClient(client => client.Uri = new Uri("ws://localhost:5050/graphql"));

The global strategy default can then be overwritten by any Watch method for a particular request.

storeSession =
    ConferenceClient
        .GetSessions
        .Watch(ExecutionStrategy.CacheFirst) // <----
        .Where(t => !t.Errors.Any())
        .Select(t => t.Data!.Sessions!.Nodes)
        .Subscribe(result =>
        {
            sessions = result;
            StateHasChanged();
        });

Website Content Docs Strawberryshake Get Started Index (`website/content/docs/strawberryshake/get-started/index.md`) Copy Section

title: "Get started with Strawberry Shake and Blazor" Copy Chapter

In this tutorial we will walk you through the basics of adding a Strawberry Shake GraphQL client to a Blazor for WebAssembly project. For this example we will create a Blazor for WebAssembly application and fetch some simple data from our demo backend.

Watch the video on YouTube

Strawberry Shake is not limited to Blazor and can be used with any .NET standard compliant library.

In this tutorial, we will teach you:

• How to add the Strawberry Shake CLI tools.
• How to generate source code from .graphql files, that contain operations.
• How to use the generated client to query data.

Step 1: Add the Strawberry Shake CLI tools

The Strawberry Shake tool will help you to set up your project to create a GraphQL client.

Open your preferred terminal and select a directory where you want to add the code of this tutorial.

1. Create a dotnet tool-manifest.

dotnet new tool-manifest

2. Install the Strawberry Shake tools.

dotnet tool install StrawberryShake.Tools --local

Step 2: Create a Blazor WebAssembly project

Next, we will create our Blazor project so that we have a little playground.

1. First, a new solution called Demo.sln.

dotnet new sln --name Demo

2. Create a new Blazor for WebAssembly application.

dotnet new blazorwasm --name Demo

3. Add the project to the solution Demo.sln.

dotnet sln add ./Demo

Step 3: Install the required package

Strawberry Shake supports multiple GraphQL transport protocols. In this example we will use the standard GraphQL over HTTP protocol to interact with our GraphQL server. All of this functionality comes packaged with the StrawberryShake.Blazor meta package.

1. Add the StrawberryShake.Blazor package to your project.

dotnet add Demo package StrawberryShake.Blazor

Step 4: Add a GraphQL client to your project using the CLI tools

To add a client to your project, you need to run #!shell dotnet graphql init {{ServerUrl}} --clientName {{ClientName}}.

In this tutorial we will use our ChilliCream demo project to create a list of cryptocurrencies that we will add to our Blazor application.

If you want to have a look at our demo GraphQL server head over here.

1. Add the crypto client to your Blazor application.

dotnet graphql init https://demo.chillicream.com/graphql/ --clientName CryptoClient --Path ./Demo

2. Customize the namespace of the generated client to be Demo.GraphQL. For this head over to the .graphqlrc.json and insert a namespace property in the StrawberryShake section.

{
  "schema": "schema.graphql",
  "documents": "**/*.graphql",
  "extensions": {
    "strawberryShake": {
      "name": "CryptoClient",
      "namespace": "Demo.GraphQL",
      "url": "https://demo.chillicream.com/graphql/",
      "records": {
        "inputs": false,
        "entities": false
      },
      "transportProfiles": [
        {
          "default": "Http",
          "subscription": "WebSocket"
        }
      ]
    }
  }
}

Now that everything is in place let us write our first query to ask for a list of session titles of the conference API.

3. Choose your favorite IDE and the solution. If your are using VSCode do the following:

code ./Demo

4. Create new query document GetSessions.graphql with the following content:

query GetAssets {
  assets {
    nodes {
      name
      price {
        lastPrice
      }
    }
  }
}

If you are working with Visual Studio on Windows edit the properties of GetSessions.graphql and set the build action for the GraphQL file to GraphQL compiler.

5. Compile your project.

dotnet build

With the project compiled the strawberry shake generator produced a client but also components that we can use in Blazor.

1. Head over to the Program.cs and add the new CryptoClient to the dependency injection.

In some IDEs it is still necessary to reload the project after the code was generated to update the IntelliSense. So, if you have any issues in the next step with IntelliSense just reload the project and everything should be fine.

using Microsoft.AspNetCore.Components.Web;
using Microsoft.AspNetCore.Components.WebAssembly.Hosting;
using Demo;

var builder = WebAssemblyHostBuilder.CreateDefault(args);
builder.RootComponents.Add<App>("#app");
builder.RootComponents.Add<HeadOutlet>("head::after");

builder.Services.AddScoped(sp => new HttpClient { BaseAddress = new Uri(builder.HostEnvironment.BaseAddress) });

builder.Services
    .AddCryptoClient()
    .ConfigureHttpClient(client => client.BaseAddress = new Uri("https://demo.chillicream.com/graphql"));

await builder.Build().RunAsync();

7. Go to _Imports.razor and add Demo.GraphQL to the common imports

@using System.Net.Http
@using System.Net.Http.Json
@using Microsoft.AspNetCore.Components.Forms
@using Microsoft.AspNetCore.Components.Routing
@using Microsoft.AspNetCore.Components.Web
@using Microsoft.AspNetCore.Components.Web.Virtualization
@using Microsoft.AspNetCore.Components.WebAssembly.Http
@using Microsoft.JSInterop
@using Demo
@using Demo.Shared // (from .NET 8, `Demo.Layout`)
@using Demo.GraphQL
@using Demo.GraphQL.Components
@using StrawberryShake

Step 5: Use the generated Razor component to display the data

In this section we will integrate the Razor component and print a simple list on our index page to display the crypto currencies.

1. Head over to Pages/Index.razor (from .NET 8, Home.razor).

2. Remove everything from your page but the @page "/"

@page "/"

3. Add the UseGetAssets component to your page.

@page "/"

<UseGetAssets Context="result">
    <ChildContent>

    </ChildContent>
    <ErrorContent>
        Something went wrong ...<br />
        @result.First().Message
    </ErrorContent>
    <LoadingContent>
        Loading ...
    </LoadingContent>
</UseGetAssets>

The query component allows you to handle the loading and the error state when fetching data. Both states can be handled but do not have to be.

4. With that done let's render the actual content.

@page "/"

<UseGetAssets Context="result">
    <ChildContent>
        <ul>
        @foreach (var item in result.Assets!.Nodes!)
        {
            <li>@item.Name (@item.Price.LastPrice)</li>
        }
        </ul>
    </ChildContent>
    <ErrorContent>
        Something went wrong ...<br />
        @result.First().Message
    </ErrorContent>
    <LoadingContent>
        Loading ...
    </LoadingContent>
</UseGetAssets>

5. Start the Blazor application with #!shell dotnet watch --project ./Demo and see if your code works.

Awesome! You have created your first application with Blazor and GraphQL.

Website Content Docs Strawberryshake Networking Index (`website/content/docs/strawberryshake/networking/index.md`) Copy Section

title: "Networking" Copy Chapter

Strawberry Shake supports multiple network protocols to communicate with your GraphQL server. Each transport integration is represented by a specific NuGet package to keep your client size as small as possible.

Protocols

Transport Profiles

In order to have a small client size and generate the optimized client for your use-case Strawberry Shake uses transport profiles. By default Strawberry Shake will generate a client that uses GraphQL over HTTP for queries and mutations and graphql-transport-ws for subscriptions. Meaning if you are only using queries and mutations you need to add the package StrawberryShake.Transport.Http.

There are cases in which we want to define specialized transport profiles where we define for each request type a specific transport. You can define those transport profiles in your .graphqlrc.json.

The following .graphqlrc.json can be copied into our getting started example and will create two transport profiles. The first is called Default and matches the internal default. It will use GraphQL over HTTP by default and use graphql-transport-ws for subscriptions. The second profile is called WebSocket and will also use GraphQL over HTTP by default but for mutations and subscriptions it will use graphql-transport-ws.

{
  "schema": "schema.graphql",
  "documents": "**/*.graphql",
  "extensions": {
    "strawberryShake": {
      "name": "ConferenceClient",
      "namespace": "Demo.GraphQL",
      "url": "http://localhost:5050/graphql",
      "transportProfiles": [
        {
          "name": "Default",
          "default": "HTTP",
          "subscription": "WebSocket"
        },
        {
          "name": "WebSocket",
          "default": "HTTP",
          "mutation": "WebSocket",
          "subscription": "WebSocket"
        }
      ]
    }
  }
}

The generator will generate the dependency injection code with a new enum called ConferenceClientProfileKind. The name of the enum is inferred from your GraphQL client name. The enum can be passed into the dependency injection setup method and allows you to switch between the two transport profiles through configuration.

builder.Services
    .AddConferenceClient(profile: ConferenceClientProfileKind.WebSocket)
    .ConfigureHttpClient(client => client.BaseAddress = new Uri("http://localhost:5050/graphql"))
    .ConfigureWebSocketClient(client => client.Uri = new Uri("ws://localhost:5050/graphql"));

Website Content Docs Strawberryshake Performance Index (`website/content/docs/strawberryshake/performance/index.md`) Copy Section

title: "Performance" Copy Chapter

In this section we will give you an overview on how to optimize the performance of your GraphQL client. We will put an emphasis on network performance since this is the most critical performance obstacle you are facing when developing fluent applications that also have to work over bad mobile network connections or even when the application becomes fully offline.

Persisted operations and automatic persisted operations

Improve performance by sending smaller requests and pre-compile operations

The size of individual GraphQL requests can become a major pain point. This is not only true for the transport but also introduces inefficiencies for the server since large requests need to be parsed and validated. Hot Chocolate implements for this problem persisted operations. With persisted operations, we can store operation documents on the server in a key-value store. When we want to execute a persisted operation, we can send the key under which the operation document is stored instead of the operation document itself. This saves precious bandwidth and also improves execution time since the server will validate, parse, and compile persisted operation documents just once.

There are two flavors of persisted operations that Strawberry Shake supports and that is also supported by our GraphQL server Hot Chocolate.

Persisted operations Copy Chapter

The first approach is to store operation documents ahead of time (ahead of deployment).
This is done by extracting the operations from your client application at build time. It will reduce the size of the requests and the bundle size of your application since operations can be completely removed from the client code at build time and are replaced with operation document hashes. Apart from performance, persisted operations can also be used for security by configuring Hot Chocolate to only accept persisted operations on production environments.

Read more on how to set up Strawberry Shake for persisted operations here.

Automatic persisted operations Copy Chapter

Automatic persisted operations allow us to store operation documents dynamically on the server at runtime. With this approach, we can give our application the same performance benefits as with persisted operations without having to opt in to a more complex build process.

We are currently still working on this feature so stay tuned on this one.

Persisted State

Apart from focusing on reducing network request size we also can optimize using the network less by using the stores more efficiently. If you are not yet familiar with the store concepts first head over to here.

One thing particular here is to persist the state that is aggregated in the stores to either the browsers IndexDB or to some small database like SQLite or LiteDB. When the user leaves the app and later returns to (closes the browser and reopens it) we can fill the state from our storage and have immediately data for the user while our store at the same time will start refreshing that data over the network if that is available.

Read more on how to set up Strawberry Shake for persisted state here.

Website Content Docs Hotchocolate Fetching Data Batching Index (`website/content/docs/hotchocolate/fetching-data/batching/index.md`) Copy Section

title: "Batching" metaTitle: "GraphQL Batching in Hot Chocolate: Solve the N+1 Problem" Copy Chapter

Batching groups many small data fetches into one call to your data source and is the standard answer to the N+1 problem in GraphQL. Because GraphQL resolves data field by field, you should plan for batching from the start: it determines whether your API issues one query per request or hundreds.

This chapter explains why the N+1 problem appears in GraphQL and introduces the two batching tools Hot Chocolate provides: DataLoader and batch resolvers.

[!NOTE]
This chapter is about batching data fetches inside a single GraphQL operation. If you are looking for a way to send multiple GraphQL operations in one HTTP request, see Server Batching.

Why the N+1 Problem Happens in Every API

The N+1 problem exists with any API technology. A REST client that fetches a list of products and then calls /brands/{id} for each product produces the exact same access pattern: one request for the list, plus N requests for related data. The same happens inside a REST backend that loads a list and then lazily loads a relation per item.

GraphQL does not make this problem worse. What GraphQL changes is where the problem lives. With REST, each client decides how to stitch resources together, so the N+1 pattern is distributed across every client and cannot be fixed centrally. With GraphQL, clients declare what they need in one query, and the server resolves it. The deliberate decision is to handle data fetching centrally in the backend, and the backend is exactly where it can be optimized well: it is one place, it is close to the data, and one fix helps every client.

Why Per-Field Resolvers Make N+1 Visible

Every field in a GraphQL schema is backed by a resolver, and the execution engine walks the query as a tree. Consider this query:

Client query

{
  products(first: 5) {
    nodes {
      name
      brand {
        name
      }
    }
  }
}

The products resolver runs once and returns five products. Then the brand resolver runs once per product. A naive brand resolver that queries the database directly issues five queries for five products, and fifty queries for fifty products:

1 query:  products(first: 5)
5 queries: brand for product 1..5   ← N+1

The per-field resolver model is what makes the N+1 pattern visible and measurable in GraphQL. That visibility is a feature: because all data fetching flows through resolvers, you can intercept it in one place and batch it.

DataLoader

A DataLoader batches by key. Resolvers ask the DataLoader for a value by key, the DataLoader collects all requested keys while the engine executes resolvers, and then fetches all of them in one call (for example a single #!sql WHERE id IN (...) query). DataLoaders also cache and deduplicate within a request: the same key requested from anywhere in the query tree is fetched once, and every resolver sees the same result.

DataLoaders are the default choice for batching in Hot Chocolate. Use them whenever data is loaded by key and may be requested from more than one place in a query.

Learn more about DataLoader

Batch Resolvers

A batch resolver batches by field. Instead of running a resolver once per parent object, the execution engine collects all parent objects that reach a specific field and calls your resolver once with the full list. You do not define a DataLoader class or a key: you receive the parents and return one result per parent.

Batch resolvers have no cache and no cross-field deduplication. They fit computed values, aggregations, and external services with native batch endpoints, where the result is specific to one field.

Learn more about Batch Resolvers

Next Steps

• Loading data by key? Start with DataLoader.
• Resolving one field for many parents? See Batch Resolvers.
• New to resolvers? See Resolvers for the resolver tree mental model.
• Using Entity Framework? See Entity Framework for integration patterns.
• Looking for HTTP request batching? See Server Batching.

Website Content Docs Hotchocolate Fetching Data Integrations Index (`website/content/docs/hotchocolate/fetching-data/integrations/index.md`) Copy Section

title: Integrations Copy Chapter

The IExecutable and IExecutable<T> interfaces abstract data sources in Hot Chocolate. Your data or domain layer can wrap a data source in an executable and pass it to the GraphQL layer. A resolver that returns IExecutable<T> is recognized as a list.

public class User
{
    public string Name { get; }
}

public interface IUserRepository
{
    public IExecutable<User> FindAll();
}

public class Query
{
    public IExecutable<User> GetUsers(IUserRepository repo) =>
        repo.FindAll();
}

type Query {
    users: [User!]!
}

This abstraction completely decouples the GraphQL layer from database-specific knowledge.

Filtering, sorting, and projections can pick up the executable and apply logic to it. A database-specific provider is still needed for these features, but it is opaque to the GraphQL layer.

The execution engine calls ToListAsync, FirstOrDefaultAsync, or SingleOrDefaultAsync on the executable. The executable runs these operations in the most efficient way for the database.

API

Source Copy Chapter

object Source { get; }

The Source property holds the current state of the executable. For Entity Framework, this holds the IQueryable. For MongoDB, it is the DbSet<T> or IAggregateFluent<T>. Source is read-only. If you have a custom IExecutable implementation and need to change the source, create a method that returns a new executable with the new source.

ToListAsync Copy Chapter

ValueTask<IList> ToListAsync(CancellationToken cancellationToken);

Returns a list of items.

FirstOrDefaultAsync Copy Chapter

ValueTask<object?> FirstOrDefaultAsync(CancellationToken cancellationToken);

Returns the first element of the sequence, or a default value if the sequence contains no elements.

SingleOrDefaultAsync Copy Chapter

ValueTask<object?> SingleOrDefaultAsync(CancellationToken cancellationToken);

Returns the only element of the sequence, or a default value if no element exists. Throws an exception if more than one element satisfies the condition.

Print Copy Chapter

string Print();

Prints the executable in its current state. This is useful for debugging and logging the generated query.

Example

The following shows the Entity Framework implementation:

public class EntityFrameworkExecutable<T> : QueryableExecutable<T>
{
    public IQueryable<T> Source { get; }

    object IExecutable.Source => Source;

    public EntityFrameworkExecutable(IQueryable<T> queryable) : base(queryable)
    {
    }

    public QueryableExecutable<T> WithSource(IQueryable<T> source)
    {
        return new QueryableExecutable<T>(source);
    }

    public override async ValueTask<IList> ToListAsync(
        CancellationToken cancellationToken) =>
        await Source.ToListAsync(cancellationToken).ConfigureAwait(false);

    public override async ValueTask<object?> FirstOrDefaultAsync(
        CancellationToken cancellationToken) =>
        await Source.FirstOrDefaultAsync(cancellationToken).ConfigureAwait(false);

    public override async ValueTask<object?> SingleOrDefaultAsync(
        CancellationToken cancellationToken) =>
        await Source.SingleOrDefaultAsync(cancellationToken).ConfigureAwait(false);

    public override string Print() => Source.ToQueryString();
}

Next Steps

• Entity Framework integration for EF Core executables
• MongoDB integration for MongoDB executables
• Filtering for applying filters to executables

Profiling (`docs/profiling.md`) Copy Section

Profiling

How to take CPU, allocation and memory snapshots of a .NET process that is running inside the dev container. The tools attach to a running process, so start the application and generate traffic the way you normally do.

Tools Copy Chapter

The dev container installs these tools, pinned in .devcontainer/dockerfile:

~/.dotnet/tools is on PATH for every process in the container, including non-interactive shells. JetBrains publishes the dotMemory console profiler only as a per-architecture NuGet package, not as a dotnet tool, so it is unpacked instead of installed with dotnet tool.

The application runs in the same container as the tools, so no /tmp or PID namespace sharing is needed. The runtime creates its diagnostics socket under $TMPDIR (default /tmp). If you override TMPDIR for the application, run the tools with the same value.

Output folder Copy Chapter

Write everything to perf/<label>-<git-short-sha>/ in the repository root. perf/ is ignored by git.

OUT=perf/fusion-gateway-$(git rev-parse --short HEAD)
mkdir -p "$OUT"

The workspace folder is mounted from the host, so Rider on the host can open the .dtp and .dmw files straight from that folder.

Find the process Copy Chapter

dotnet-trace ps

Use the PID of the application process, not of dotnet run that launched it. For a web application, lsof -nP -iTCP: -sTCP:LISTEN -t returns the same PID.

CPU sampling trace Copy Chapter

dotnet-trace collect -p <pid> --duration 00:00:00:30 --format speedscope -o "$OUT/cpu.nettrace"
dotnet-trace report "$OUT/cpu.nettrace" topN -n 25
dotnet-trace report "$OUT/cpu.nettrace" topN -n 25 --inclusive

This writes cpu.nettrace and cpu.speedscope.json. Open the speedscope file at https://www.speedscope.app, or analyze the nettrace with PerfView or dotnet-trace report.

Allocation trace Copy Chapter

dotnet-trace collect -p <pid> --profile gc-verbose --duration 00:00:00:15 -o "$OUT/alloc.nettrace"

gc-verbose records sampled allocation ticks with their call stacks and every GC. It is expensive, so keep the duration short. PerfView and the TraceEvent library read the GCAllocationTick events.

Heap snapshots Copy Chapter

dotnet-gcdump collect -p <pid> -o "$OUT/heap.gcdump"
dotnet-gcdump report "$OUT/heap.gcdump" > "$OUT/heap-report.txt"

The report lists live objects by type and size. Take two gcdumps a few minutes apart to find growth.

Live counters Copy Chapter

dotnet-counters monitor -p <pid> --counters System.Runtime,Microsoft.AspNetCore.Hosting,System.Net.Http
dotnet-counters collect -p <pid> --format json -o "$OUT/counters.json" --duration 00:00:00:20 --counters System.Runtime,Microsoft.AspNetCore.Hosting,System.Net.Http

monitor shows the values live in the terminal and has no file output. collect writes the same counters to a file, as JSON or CSV.

dotTrace Copy Chapter

dottrace attach supports the Sampling and Timeline profiling types. Tracing and Line-by-line are only available through dottrace start, which launches the process under the profiler.

Sampling, controlled through stdin. The profiler prints ##dotTrace["connected"], ##dotTrace["started"] and ##dotTrace["snapshot-saved"] as it goes, so send each command after the previous one was confirmed:

dottrace attach <pid> --profiling-type=Sampling --save-to="$OUT/dottrace-sampling.dtp" \
  --collect-data-from-start=off --service-input=stdin --service-output=on
##dotTrace["start"]
##dotTrace["get-snapshot"]
##dotTrace["disconnect"]

The same session from a script, waiting for the confirmations instead of typing:

LOG="$OUT/dottrace.log"; FIFO=$(mktemp -u); mkfifo "$FIFO"
dottrace attach <pid> --profiling-type=Sampling --save-to="$OUT/dottrace-sampling.dtp" --overwrite \
  --collect-data-from-start=off --service-input=stdin --service-output=on < "$FIFO" > "$LOG" 2>&1 &
exec 3>"$FIFO"
until grep -q '"connected"' "$LOG"; do sleep 1; done
printf '\n##dotTrace["start"]\r\n' >&3
sleep 30
printf '\n##dotTrace["get-snapshot"]\r\n' >&3
until grep -q '"snapshot-saved"' "$LOG"; do sleep 1; done
printf '\n##dotTrace["disconnect"]\r\n' >&3
wait; exec 3>&-; rm -f "$FIFO"

Tracing, for call counts, starts the application under the profiler instead of attaching. Point it at the application binary, not at dotnet run, so the profiled process is the application itself:

dottrace start --framework=NetCore --profiling-type=Tracing --save-to="$OUT/dottrace-tracing.dtp" \
  --collect-data-from-start=off --service-input=stdin --service-output=on \
  bin/Release/net10.0/<App>

A snapshot is the .dtp file plus its numbered .dtp.0000 companions. Keep them together.

dotMemory Copy Chapter

One snapshot now:

dotmemory get-snapshot <pid> --save-to-dir="$OUT/dotmemory"

Attach and take a snapshot every 30 seconds, at most three, then detach:

dotmemory attach <pid> --trigger-timer=30s --trigger-max-snapshots=3 --timeout=2m --save-to-dir="$OUT/dotmemory"

--trigger-mem-inc=50mb and --trigger-mem-limit=1gb trigger on memory growth instead of time. The result is a .dmw workspace that holds all snapshots of the session.

Dumps and symbols Copy Chapter

dotnet-dump collect -p -o "$OUT/full.dmp" writes a full process dump for dotnet-dump analyze. dotnet-symbol downloads the runtime symbols a dump from another machine needs; dumps taken inside the container already resolve.

Caveats Copy Chapter

• Profile Release builds. Debug builds disable optimizations and distort both time and allocations.
• Sampling gives time but not call counts. Use dotTrace Tracing mode for call counts, which means starting the process with dottrace start.
• On Linux, EventPipe samples measure thread time, so idle thread pool frames such as LowLevelLifoSemaphore.WaitForSignal, WaitHandle.WaitOneNoCheck, Monitor.Wait, the finalizer thread in GC.RunFinalizers, PollGCWorker and a blocked file watcher in Interop+Sys.Read dominate the exclusive time. Ignore them and read the frames below them. The speedscope export puts a synthetic CPU_TIME or UNMANAGED_CODE_TIME leaf under every sample, and ?!? stands for native frames without symbols, mostly GC threads. For the CPU a process really uses, read dotnet.process.cpu.time from dotnet-counters.
• Take the dotMemory snapshots last. In two sessions the profiled Fusion gateway crashed 45 seconds and two minutes after dotmemory attach had disconnected, under load, with a native fault that the runtime turned into a createdump minidump. Set DOTNET_DbgEnableMiniDump=1 on the application if you want that dump, and restart the application after a dotMemory session before measuring anything else.
• .dtp and .dmw snapshots are for Rider on the host. Agents should use the dotnet-trace and dotnet-gcdump outputs, which are readable in the container.
• Attaching needs no special container privileges. It only requires that the application was not started with DOTNET_EnableDiagnostics=0.

Updating Dotnet (`docs/updating-dotnet.md`) Copy Section

Updating .NET

What to check when TargetFrameworks in src/Directory.Build.props or the SDK version in global.json changes. Each section covers code that follows the source of ASP.NET Core or .NET, so an upstream change can call for the same change here.

Multipart form reader Copy Chapter

MultipartFormReader in src/HotChocolate/AspNetCore/src/AspNetCore.Pipeline/Parsers reads the form of a multipart request for HttpMultipartMiddleware. It follows the multipart branch of FormFeature.InnerReadFormAsync, and its antiforgery check, in src/Http/Http/src/Features/FormFeature.cs on dotnet/aspnetcore. MultipartReader, FileBufferingReadStream, FormFile, and header parsing stay the framework's, so their fixes reach applications through servicing releases.

The reader was last compared with these tags, whose multipart branches are identical:

To list the upstream changes between a recorded tag and a new one, here from v10.0.12 to v10.0.13:

git clone --filter=blob:none --no-checkout https://github.com/dotnet/aspnetcore.git
git -C aspnetcore log --oneline v10.0.12..v10.0.13 -- src/Http/Http/src/Features/FormFeature.cs

Apply a change to the section loop, its limits, the file buffering, or the antiforgery check to the reader, and record the new tag in the table.

The reader differs from FormFeature in these ways:

• Each limit has its own error code. MultipartBodyLengthLimit applies to every section (HC0135), and maxAllowedRequestSize also applies to the operations field (HC0010); whichever of the two is smaller limits operations and gives its code. BufferBodyLengthLimit, when BufferBody is set, applies to the whole body (HC0136). FormFeature does not apply maxAllowedRequestSize; it throws InvalidDataException for MultipartBodyLengthLimit and IOException for BufferBodyLengthLimit.
• With BufferBody set, it buffers the body even when an earlier component already made the body seekable, so BufferBodyLengthLimit applies in that case too.
• It refuses a request whose IAntiforgeryValidationFeature has IsValid set to false, without the HttpContext.Items keys that FormFeature checks first.
• It does not read URL-encoded forms, which never reach the multipart middleware.
• It does not apply endpoint IFormOptionsMetadata, which the public FormFeature constructor does not apply either.

Website Content Docs Fusion Adding A Subgraph (`website/content/docs/fusion/adding-a-subgraph.md`) Copy Section

title: "Adding a Subgraph" Copy Chapter

You have an existing Fusion project with a gateway, one or more subgraphs, and a working composition pipeline. Now you need to add a new subgraph. Maybe your team owns a new domain (shipping, billing, inventory), or you are splitting an existing subgraph into smaller services. Either way, the process is the same: create a new Hot Chocolate project, define your types and any entity extensions, export the schema, compose, and verify.

This page walks you through adding a Shipping subgraph to an existing project that already has Products and Reviews subgraphs. If you have not set up a Fusion project yet, start with the Getting Started tutorial first.

Prerequisites

Before you begin, you need:

• An existing Fusion project with at least one subgraph and a gateway
• The Nitro CLI installed (#!shell dotnet tool install -g ChilliCream.Nitro.CommandLine)
• The .NET 10 SDK or later

You should be able to compose and run your existing project successfully. If composition is currently broken, fix that first.

Subgraph Project Structure

Every Fusion subgraph follows the same layout:

src/
  Shipping/
    Types/
      Product.cs              # Entity stub
      ShipmentNode.cs         # Type extension (replaces foreign key with entity reference)
      ShippingQueries.cs      # Query resolvers (lookups)
    Shipment.cs               # Domain type
    ShipmentRepository.cs     # In-memory data
    Program.cs                # Server configuration
    Shipping.csproj           # Project file
    appsettings.json          # App settings
    schema-settings.json      # Fusion subgraph settings (created on first schema export)
    schema.graphqls           # Exported schema (generated, do not edit)

Your folder structure may differ, but the Fusion components are always the same: a GraphQL server, your type definitions, an exported schema, and a schema-settings.json.

Create the Subgraph Project

Create a new GraphQL server project from the template:

dotnet new graphql -n Shipping

The template creates sample files in Shipping/Types (Author.cs, Book.cs, Query.cs). Delete those files before continuing so your schema only contains your own types.

Your Shipping/Shipping.csproj should look like this:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup Condition="'$(ImplicitUsings)' == 'enable'">
    <Using Include="Shipping" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="HotChocolate.AspNetCore" />
    <PackageReference Include="HotChocolate.AspNetCore.CommandLine" />
    <PackageReference Include="HotChocolate.Types.Analyzers">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
  </ItemGroup>

</Project>

Configure the Port Copy Chapter

The dotnet new graphql template already defines a default port in launchSettings.json. Change it so the Shipping subgraph runs on port 5003. Edit Shipping/Properties/launchSettings.json and set launchUrl and applicationUrl under the http profile to:

"launchUrl": "http://localhost:5003/graphql",
"applicationUrl": "http://localhost:5003"

This ensures the subgraph runs on port 5003, which matches what you will configure in schema-settings.json later.

Define Your Types

The Shipping subgraph owns shipment data and contributes a shipments field to the existing Product type. It does not own Product. The Products subgraph does. The Shipping subgraph extends it with shipping information.

Define the Shipment Type Copy Chapter

Create Shipment.cs in the Shipping project:

namespace Shipping;

public class Shipment
{
    public int Id { get; set; }

    public int ProductId { get; set; }

    public required string TrackingNumber { get; set; }

    public required string Status { get; set; }
}

Each shipment has a ProductId that references a product from the Products subgraph.

Add In-Memory Data Copy Chapter

Create ShipmentRepository.cs:

namespace Shipping;

public static class ShipmentRepository
{
    private static readonly List<Shipment> Shipments =
    [
        new Shipment { Id = 1, ProductId = 1, TrackingNumber = "SH-001", Status = "Delivered" },
        new Shipment { Id = 2, ProductId = 1, TrackingNumber = "SH-002", Status = "In Transit" },
        new Shipment { Id = 3, ProductId = 2, TrackingNumber = "SH-003", Status = "Shipped" },
    ];

    public static Shipment? GetById(int id)
        => Shipments.FirstOrDefault(s => s.Id == id);

    public static List<Shipment> GetByProductId(int productId)
        => Shipments.Where(s => s.ProductId == productId).ToList();
}

Create the Entity Stub Copy Chapter

An entity stub is a lightweight declaration that says "I know this type exists in the graph and I want to add fields to it." Create Types/Product.cs:

namespace Shipping;

public sealed record Product(int Id)
{
    public List<Shipment> GetShipments()
        => ShipmentRepository.GetByProductId(Id);
}

This is not a duplicate of the Product type from the Products subgraph. It is an entity stub. The Shipping subgraph does not define name, price, or any other Product field. It only contributes the shipments field. When the gateway composes the schema, it merges this stub with the full Product type from the Products subgraph. Clients see one Product type with all fields from all subgraphs.

Add Query Resolvers Copy Chapter

Create Types/ShippingQueries.cs with a public lookup for Shipment and an internal lookup for Product:

namespace Shipping;

[QueryType]
public static partial class ShippingQueries
{
    [Lookup]
    public static Shipment? GetShipmentById(int id)
        => ShipmentRepository.GetById(id);

    [Internal, Lookup]
    public static Product? GetProductById(int id)
        => new(id);
}

• GetShipmentById is a public lookup. Clients can call it directly, and the gateway uses it for entity resolution.
• GetProductById is an internal lookup. It is hidden from the composite schema and exists only for the gateway to enter the Shipping subgraph's Product type during entity resolution. It constructs a stub from the ID without checking whether the product exists, which is safe because the gateway only calls internal lookups after another subgraph has already confirmed the entity exists.

For more on public vs. internal lookups and when to use each, see Entities and Lookups.

Replace Foreign Keys with Entity References Copy Chapter

The Shipment type currently exposes a raw ProductId. To expose shipment.product instead, add a type extension. Create Types/ShipmentNode.cs:

using HotChocolate.Types;

namespace Shipping;

[ObjectType<Shipment>]
public static partial class ShipmentNode
{
    [BindMember(nameof(Shipment.ProductId))]
    public static Product GetProduct([Parent] Shipment shipment)
        => new(shipment.ProductId);
}

[BindMember(nameof(Shipment.ProductId))] tells Hot Chocolate to replace the productId field on Shipment with the product field returned by this resolver. In the exported schema, clients see shipment.product (returning a full Product) instead of shipment.productId (a raw integer). The gateway resolves the full Product from whichever subgraph owns it.

Configure the Server

Set Program.cs to:

var builder = WebApplication.CreateBuilder(args);

builder
    .AddGraphQL("Shipping")
    .AddTypes();

var app = builder.Build();

app.MapGraphQL();
app.RunWithGraphQLCommands(args);

#!csharp AddGraphQL("Shipping") sets the subgraph name used during schema export. AddTypes() is source-generated and registers all types discovered by the analyzer. RunWithGraphQLCommands(args) enables CLI commands like schema export.

Export the Schema

From the project root, export the schema:

dotnet run --project ./Shipping -- schema export

This generates two files in the Shipping directory:

• schema.graphqls contains the subgraph's GraphQL schema.
• schema-settings.json contains the subgraph settings.

Because Program.cs uses #!csharp AddGraphQL("Shipping"), the generated schema-settings.json already contains "name": "Shipping". The transport URL defaults to http://localhost:5000/graphql, so update it to match port 5003:

{
  "name": "Shipping",
  "transports": {
    "http": {
      "url": "http://localhost:5003/graphql"
    }
  }
}

The name field identifies this subgraph within the composite schema and must be unique. The url is where the gateway sends requests to this subgraph at runtime.

Compose

Run composition with all subgraph schemas, including your new one:

nitro fusion compose \
  -s Products/schema.graphqls \
  -s Reviews/schema.graphqls \
  -s Shipping/schema.graphqls \
  -a gateway.far

If composition succeeds, copy the updated gateway.far to your gateway project directory:

cp gateway.far Gateway/gateway.far

If you already have a composed gateway.far with the Products and Reviews subgraphs, you can add the new subgraph to the existing archive:

nitro fusion compose \
  -s Shipping/schema.graphqls \
  -a gateway.far

Test Cross-Subgraph Queries

Start all services and the gateway. With the Shipping subgraph added, you can now query shipment data that crosses subgraph boundaries:

query {
  productById(id: 1) {
    name
    price
    shipments {
      trackingNumber
      status
    }
  }
}

This query touches two subgraphs:

1. The gateway calls the Products subgraph to fetch name and price.
2. The gateway uses the internal lookup to enter the Shipping subgraph and resolve shipments for the same product.

The client sees one unified response with fields from both subgraphs merged into a single Product.

You can also query in the other direction, starting from a shipment and navigating to the product:

query {
  shipmentById(id: 1) {
    trackingNumber
    status
    product {
      name
      price
    }
  }
}

Here the gateway resolves the shipment from the Shipping subgraph, then uses the Products subgraph to fetch name and price for the referenced product.

Troubleshooting Composition Errors

If composition fails after adding your new subgraph, the error messages point to specific issues.

Duplicate field without sharing Copy Chapter

"Field X is defined in multiple subgraphs". Your new subgraph defines a field that already exists in another subgraph. Key fields (like id) are automatically shareable, but all other duplicated fields need @shareable on every definition. See Field Ownership for details.

Missing lookup Copy Chapter

"No lookup found for entity X". Your subgraph references an entity type but no subgraph provides a lookup for it. Add a lookup resolver (public or internal) for that entity. See Entities and Lookups.

Incompatible field types Copy Chapter

"Incompatible field types for X". Two subgraphs define the same field with different types. The types must be compatible according to the composition merging rules.

Next Steps

• Need cross-subgraph field dependencies? See Data Requirements for the full range of @require patterns and FieldSelectionMap syntax.
• Composition failed? See Composition for the full merging rules, common errors, and fixes.
• Want to understand entities more deeply? See Entities and Lookups for the complete guide to entity stubs, public vs. internal lookups, and composite keys.
• Ready to deploy? See Deployment and CI/CD for setting up independent subgraph deployments with the Nitro CLI.

Website Content Docs Fusion Authentication And Authorization (`website/content/docs/fusion/authentication-and-authorization.md`) Copy Section

title: "Authentication and Authorization" Copy Chapter

The Fusion gateway builds on ASP.NET Core authentication and authorization. You can use the same features you use in any ASP.NET Core service, including JWT validation, cookie authentication, OpenID Connect, and mTLS.

Fusion does not add its own authentication or authorization mechanisms. It relies on ASP.NET Core, so you keep the same configuration model, extension points, and security-hardened framework you already use.

Authenticating clients at the gateway

The gateway authenticates incoming requests with the same APIs as any ASP.NET Core service. There is no Fusion-specific configuration; use AddAuthentication(...) and UseAuthentication() as usual.

A minimal JWT bearer setup for the gateway:

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = "https://login.example.com/";
        options.Audience = "https://api.example.com";
    });

builder.Services.AddAuthorization();

builder.Services
    .AddGraphQLGateway()
    .AddFileSystemConfiguration("./gateway.far");

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.MapGraphQL();

app.Run();

Everything in the AddJwtBearer callback is standard ASP.NET Core. For details on JWKS rotation, multi-issuer setups, custom audience validation, refresh policies, and clock skew handling, see the Microsoft Learn reference. You do not need to implement those features yourself.

The example above configures your service to validate JWT access tokens at the gateway. It does not reject requests when the token is missing or invalid. To require authentication, add authorization to the GraphQL endpoint.

Requiring authentication on the GraphQL endpoint Copy Chapter

To reject anonymous requests at the gateway before they reach the GraphQL pipeline, attach an authorization policy to the endpoint:

app.MapGraphQL().RequireAuthorization();

Or apply a named policy that requires a specific scope:

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("graphql:read", policy =>
        policy.RequireAuthenticatedUser()
              .RequireClaim("scope", "graphql:read"));
});

app.MapGraphQL().RequireAuthorization("graphql:read");

Without RequireAuthorization, anonymous requests reach the GraphQL pipeline, and any field not protected by the subgraphs is accessible without credentials. Whether this is acceptable depends on your API. For example, a public catalog with an authenticated checkout flow may leave the endpoint open and let subgraphs protect sensitive fields. An internal back-office gateway typically requires authentication at the edge.

Cookies Authentication & Browser Clients Copy Chapter

You can also use cookie authentication at the gateway and serve UI assets directly from it. For guidance, see Cookie Authentication in ASP.NET Core. If you are building a browser-based client, review UI and SPA considerations.

In general, we do NOT recommend serving SPA applications directly from the gateway. Instead, put a Backend for Frontend (BFF) in front of the gateway. You can build your own BFF or use Duende BFF. The BFF handles browser-specific authentication and session management, then calls the gateway with a token-based approach. This keeps the gateway focused on GraphQL traffic while the BFF manages browser authentication and session concerns.

Forwarding identity to subgraphs

By default, the gateway does not forward headers to subgraphs. This means subgraphs do not receive the caller's access token or other identity information. Because authorization is usually handled by the subgraph, you typically need to pass the access token or relevant identity data so the subgraph can authorize requests correctly.

Header propagation Copy Chapter

Most often, you want to forward the Authorization header containing the access token to the subgraph. The subgraph can then validate the JWT and run authorization checks.

Fusion uses the official ASP.NET Core header propagation mechanism to forward headers to subgraphs:

builder.Services.AddHeaderPropagation(options =>
{
    options.Headers.Add("Authorization");
    options.Headers.Add("GraphQL-Preflight");
});

See the Microsoft Learn documentation on header propagation for more details.

You must configure header propagation on each HTTP client individually. Otherwise, it will not take effect. By default, Fusion uses a named HTTP client called "fusion" to call subgraphs. You can change this name in the schema-settings.json of each subgraph. If you keep the default, configure header propagation on the "fusion" client:

{
  "transports": {
    "http": {
      "url": "http://products:5001/graphql",
      "clientName": "fusion"
    }
  }
}

Register header propagation for that client:

builder.Services
    .AddHttpClient("fusion")
    .AddHeaderPropagation();

Add the UseHeaderPropagation middleware before the GraphQL middleware in your pipeline so headers are forwarded:

// Later in the pipeline.
app.UseHeaderPropagation();

app.MapGraphQL();

Authentication termination Copy Chapter

In many enterprise scenarios, you may not want to forward the access token through the entire stack. With Fusion, you have full control over outgoing requests, so you can adapt the gateway to your authentication model and support custom authentication flows.

To intercept outgoing requests, add a DelegatingHandler to the HTTP client that calls subgraphs. This lets you derive headers from validated claims, exchange the incoming token for a new token with the correct audience, or call an external service to get additional caller information to forward.

public sealed class ClaimsHeaderHandler(IHttpContextAccessor httpContextAccessor)
    : DelegatingHandler
{
    protected override Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request,
        CancellationToken cancellationToken)
    {
        var user = httpContextAccessor.HttpContext?.User;

        var userId = user?.FindFirst(ClaimTypes.NameIdentifier)?.Value;
        if (!string.IsNullOrEmpty(userId))
        {
            request.Headers.TryAddWithoutValidation("X-User-Id", userId);
        }

        var tenantId = user?.FindFirst("tenant_id")?.Value;
        if (!string.IsNullOrEmpty(tenantId))
        {
            request.Headers.TryAddWithoutValidation("X-Tenant-Id", tenantId);
        }

        return base.SendAsync(request, cancellationToken);
    }
}

Register the handler and configure the client:

builder.Services.AddHttpContextAccessor();
builder.Services.AddTransient<ClaimsHeaderHandler>();

builder.Services
    .AddHttpClient("fusion")
    .AddHeaderPropagation()
    .AddHttpMessageHandler<ClaimsHeaderHandler>();

Client-to-gateway trust (mTLS)

In some scenarios, only trusted clients should be able to call your gateway. Mutual TLS (mTLS) supports this by requiring the client to present a certificate. The gateway validates that certificate against a trusted certificate authority (CA).

Kestrel supports mTLS directly, and you can configure it with the ConfigureKestrel API. For details, see the Microsoft Learn documentation.

Gateway-to-subgraph trust

Keep subgraphs private Copy Chapter

Subgraphs should not be public endpoints. GraphQL federation features like @internal assume subgraphs are not publicly accessible.

Place subgraphs on a private network, such as a VPC, Kubernetes cluster, or Azure VNet, that only the gateway can reach. This ensures all subgraph requests pass through the gateway and are subject to the gateway's composition, authentication, and authorization policies.

mTLS to subgraphs Copy Chapter

To ensure that only the gateway can call the subgraphs, use mutual TLS (mTLS) for gateway-to-subgraph communication.

Useful links:

• Certificate authentication
• Kestrel client certificates

Authorization

Authorization is a cross-cutting concern that involves both the gateway and the subgraphs. In internal or back-office scenarios, you usually want to reject unauthorized requests as early as possible at the gateway. In public scenarios, you may allow unauthorized requests to reach the subgraph and handle rejection there.

The subgraph ultimately decides whether a request can access specific data. Only the subgraph has the full context about the data and its business rules, so it is best suited to make authorization decisions.

For more information on subgraph-level authorization, @authorize, policies, and claims in Hot Chocolate subgraphs, see Hot Chocolate authorization.

Website Content Docs Fusion Batching (`website/content/docs/fusion/batching.md`) Copy Section

title: "Batching" Copy Chapter

One wave of a query plan can produce many calls to the same subgraph: one entity lookup per item of a list, or several distinct lookups that all target the same service. Batching collapses those calls into fewer round trips, without changing the query plan.

Where Batching Applies

Consider a query that reads a list of books from one subgraph and each book's rating from another:

{
  books {
    title
    rating
  }
}

The gateway fetches the books from the first subgraph, then needs rating for every book from the second. With two books that is two lookups, with two hundred books it is two hundred. Batching sends them as one request instead; the same lookups still happen, they just travel together.

The Three Batching Capabilities

Fusion knows three ways to put more than one call into one HTTP request. Each one is declared as a capability of the subgraph it is used against.

Variable Batching Copy Chapter

Variable batching sends one operation with many sets of variables in one request. The variables property carries an array instead of an object, and the subgraph runs the operation once per set:

{
  "query": "query($id: ID!) { bookById(id: $id) { rating } }",
  "variables": [{ "id": "1" }, { "id": "2" }]
}

Variable batching is a Hot Chocolate protocol extension, not part of the GraphQL over HTTP specification, so only subgraphs that implement it can be sent this shape.

Request Batching Copy Chapter

Request batching sends an array of independent requests in one HTTP request. Each element is a complete GraphQL request with its own query and its own variables, so a batch can carry different operations:

[
  {
    "query": "query($id: ID!) { bookById(id: $id) { rating } }",
    "variables": { "id": "1" }
  },
  {
    "query": "query($id: ID!) { authorById(id: $id) { name } }",
    "variables": { "id": "7" }
  }
]

When the subgraph supports request batching but not variable batching, the gateway flattens each operation's variable sets into one array element per set, so the batch still travels as a single request.

Request batching is also a protocol extension. Subgraphs that do not accept a JSON array as the request body cannot be sent this shape.

Alias Batching Copy Chapter

Alias batching needs no protocol extension. The gateway merges the calls into one plain GraphQL operation whose root selections are aliased per item, which any spec-compliant GraphQL server can answer.

For the two book lookups above, the gateway sends:

query Op_68b774cc_Batch_2963222070b1fe07(
  $_0___fusion_1_id: ID!
  $_1___fusion_1_id: ID!
) {
  _0_bookById: bookById(id: $_0___fusion_1_id) {
    ..._fusion_body_1
  }
  _1_bookById: bookById(id: $_1___fusion_1_id) {
    ..._fusion_body_1
  }
}

fragment _fusion_body_1 on Book {
  rating
}

{
  "_0___fusion_1_id": "1",
  "_1___fusion_1_id": "2"
}

The subgraph answers with one response, and the gateway splits it by alias:

{
  "data": {
    "_0_bookById": { "rating": "1" },
    "_1_bookById": { "rating": "2" }
  }
}

The merged operation follows three rules:

• Each item gets a prefix. The root selection is aliased with __, and the variables that vary per item are renamed with the same prefix.
• Shared variables are declared once. A variable the gateway forwards from the client request carries one value for the whole batch, so it keeps its name and appears once in the variable definitions.
• Repeated bodies become one fragment. When several items select the same body, the body is emitted once as a generated fragment and each item spreads it.

Only query operations are merged. Mutations and subscriptions are never merged, and a request that uploads files keeps its own multipart round trip while the remaining requests still share one.

How Fusion Chooses a Protocol

The gateway decides per subgraph, from the capabilities that subgraph declares. There are two independent dimensions.

Many variable sets of one operation. Variable batching wins whenever the subgraph declares it. Alias batching serves this dimension when variable batching is absent.

Distinct operations in one wave. Request batching wins whenever the subgraph declares it. Alias batching serves this dimension when request batching is absent. When neither is available, the gateway sends one HTTP request per operation.

The two decisions are taken independently, so a subgraph that declares only one of the two protocol extensions uses it for its own dimension and alias batching for the other. A batch that would merge fewer than two items is sent on the subgraph's native protocol instead.

Configuring Batching Capabilities

Batching capabilities live under capabilities.batching in a source schema's HTTP transport settings:

{
  "name": "Products",
  "transports": {
    "http": {
      "url": "http://products/graphql",
      "capabilities": {
        "batching": {
          "variableBatching": true,
          "requestBatching": true,
          "aliasBatching": true
        }
      }
    }
  }
}

All three flags are optional and independent. A flag you declare always wins; a flag you omit keeps its default.

Defaults Copy Chapter

The default depends on how the source schema is connected:

The default GraphQL connector assumes a subgraph that implements both protocol extensions, which a Hot Chocolate source schema does. An Apollo Federation subgraph is only assumed to speak plain GraphQL.

The connector kind only sets the starting value, so partial settings mix with it per flag:

• #!json { "requestBatching": true } on an Apollo Federation subgraph yields request batching and alias batching, and request batching is then preferred for distinct operations.
• #!json { "aliasBatching": false } on an Apollo Federation subgraph yields no batching at all.
• #!json { "variableBatching": false, "requestBatching": false } on an Apollo Federation subgraph still leaves alias batching on. Declare "aliasBatching": false as well to turn batching off completely.

[!NOTE]
The settings template a Hot Chocolate subgraph exports declares all three flags explicitly, so a gateway that uses it does not fall back to the defaults. variableBatching and requestBatching mirror the batching the subgraph's server options allow, which AddSourceSchemaDefaults() turns on, and aliasBatching is always true.

Apollo Federation Subgraphs

An Apollo Federation subgraph is entered through the _entities field, and the entity keys travel in its representations argument. One _entities operation therefore already resolves many entities with a single variable set, so variable batching never applies on this path.

That leaves distinct operations: several _entities calls with different sub-selections, or several different lookups against the same subgraph in one wave. For those, the gateway uses request batching if the subgraph declares it, alias batching otherwise, and one request per operation when neither is available.

By default only alias batching is on, so two _entities calls in one wave travel as one merged operation:

query Op_88f73202_Batch_d9cfb37825dbe30d(
  $_0_representations: [_Any!]!
  $_1_representations: [_Any!]!
) {
  _0__entities: _entities(representations: $_0_representations) {
    ... on Child {
      b: value(suffix: "!")
    }
  }
  _1__entities: _entities(representations: $_1_representations) {
    ... on Child {
      a: value
    }
  }
}

See the Apollo Federation Connector page for the connector-specific settings.

Errors in a Batched Request

A merged operation produces a single response, and the gateway attributes its errors by path: the first segment of an error path is the alias of the item, so the error is routed to that item and rewritten to the item's own field name. An error without a path applies to the whole request and is handed to every item of the batch.

The result is the same as if the calls had been sent separately. In the two-book example, an error on the second book's rating appears on that book alone:

{
  "data": {
    "books": [
      { "title": "C# in Depth", "rating": "1" },
      { "title": "The Lord of the Rings", "rating": null }
    ]
  },
  "errors": [
    {
      "message": "Rating unavailable.",
      "path": ["books", 1, "rating"]
    }
  ]
}

Independent of batching, the capabilities.onError setting selects the error handling mode the gateway asks a subgraph for ("propagate" or "null"). It is not set by default, so the gateway sends no onError value and the subgraph applies its own behavior.

Next Steps

• "I want to tune the transport itself": Performance Tuning covers the named HttpClient, HTTP/2, request deduplication, and concurrency limits.
• "I want to understand where the lookups come from": Entities and Lookups explains how the gateway enters a subgraph by key.
• "I run Apollo Federation subgraphs": Apollo Federation Connector covers the connector end to end.

Website Content Docs Fusion Cache Control (`website/content/docs/fusion/cache-control.md`) Copy Section

title: "Cache Control" Copy Chapter

Cache-Control is the HTTP header field that tells browsers, reverse proxies, and CDNs how they are allowed to store and reuse a response instead of sending the same request back to the server every time. Together with related headers such as Vary, it makes cached responses safe and predictable by defining whether a response may be reused, how long it may be reused, and which parts of the request affect that decision.

Why Cache Control Matters

Good cache rules help you:

• Reduce latency for users.
• Reduce load on your backend services.
• Keep cache behavior predictable.
• Protect user-specific data from shared caches.

To make caching work safely and predictably, you need two things:

1. A deterministic GET route so caches get a stable cache key.
2. Correct Cache-Control (and Vary) headers so caches know where and how long a response may be reused.

Why GraphQL Needs Extra Care

GraphQL usually exposes one endpoint, but each request can ask for different fields. Two requests to the same URL can therefore return very different response shapes and different data sensitivity.

A single GraphQL response can also mix public data and user-specific data. Since HTTP cache headers apply to the full response, the gateway has to compute one safe final policy that represents everything selected in that operation.

That means one response can include:

• Public data (safe for shared caches), and
• User-specific data (not safe for shared caches).

The GraphQL operation type matters. Query operations are side-effect free reads, so they are the primary target for HTTP and CDN caching. Mutations change data and should not be cached as shared HTTP responses. Subscriptions are long-running streams and are not HTTP-cacheable.

Deterministic GET Routes

The GraphQL over HTTP specification allows query operations to be sent over HTTP GET.

GET /graphql?query=query GetProducts{products{nodes{name}}}

The same applies when variables are included.

GET /graphql?query=query GetProducts($first:Int!){products(first:$first){nodes{name}}}&variables={"first":5}

In real requests, these values are URL-encoded, and for larger operations the query string quickly becomes difficult to work with. This is where persisted operations help.

Persisted Operation Routes Copy Chapter

In large first-party GraphQL APIs, a common approach used by companies such as Netflix, Meta, and X is to rely on trusted documents. Client operations are stored in an operation store, and clients send a stable operation identifier instead of the full query text.

You can read more in the First-Party API guide.

With trusted documents in place, persisted-operation routes become short and stable.

GET /graphql/persisted/GetProducts/123456789

Variables can then be sent as query parameters.

GET /graphql/persisted/GetProducts/123456789?variables={"first":5}

In order to use persisted-operation routes you need to add the middleware MapGraphQLPersistedOperations.

var app = builder.Build();

app.MapGraphQLPersistedOperations();

`@cacheControl` in GraphQL

A deterministic route alone is not enough. The gateway also needs policy metadata to decide whether a response is public or private, and how long it may be reused.

GraphQL provides the @cacheControl directive for this purpose. You can place it on fields and types to describe cache intent.

type Query {
  productById(id: ID!): Product @cacheControl(maxAge: 300, sharedMaxAge: 900)

  me: UserProfile
    @cacheControl(maxAge: 60, scope: PRIVATE, vary: ["Authorization"])
}

How Fusion Assembles the Final Headers

Fusion computes one effective response policy by traversing the planned operation tree. It starts at the selected root fields, reads @cacheControl metadata on each field, falls back to the field return type when values are missing, and continues recursively through child selections, including interfaces and unions.

All collected constraints are merged into one final policy. The merge is conservative: max-age and s-maxage take the lowest value, scope resolves to the strictest value (private over public), and vary values are merged, normalized, and deduplicated. Every GraphQL response already lists Accept in Vary, and the merged vary names are added to it. Some CDNs, Akamai by default, do not cache a response whose Vary lists anything other than Accept-Encoding. Configure the CDN to cache it anyway, or remove Accept from Vary in a custom formatter.

Fusion computes these cache constraints for query operations. Mutation requests, Subscription request, introspection requests, and operations with no cache constraints do not get cache-control headers.

Cache Policy Starts in Subgraphs

In Fusion, cache policy starts where data is resolved, which means your subgraphs define cache intent for their own fields.

type Product {
  id: ID!
  name: String!
}

type UserProfile {
  id: ID!
  email: String!
}

type Query {
  productById(id: ID!): Product @cacheControl(maxAge: 300, sharedMaxAge: 900)

  me: UserProfile
    @cacheControl(maxAge: 60, scope: PRIVATE, vary: ["Authorization"])
}

If your subgraph runs on Hot Chocolate, you can express the @cacheControl directive with the [CacheControl] attribute.

using HotChocolate.Caching;

[QueryType]
public static class Query
{
    [CacheControl(300, SharedMaxAge = 900)]
    public static Product? GetProductById(int id)
        => ProductRepository.GetById(id);

    [CacheControl(60, Scope = CacheControlScope.Private, Vary = ["Authorization"])]
    public static UserProfile GetMe()
        => UserProfileRepository.GetCurrent();
}

Enable cache-control metadata on the subgraph:

builder
    .AddGraphQL()
    .AddCacheControl();

Enable Cache Control in the Fusion Gateway

The gateway must be configured to read cache-control metadata during planning and to write the final HTTP headers on the response.

var builder = WebApplication.CreateBuilder(args);

builder
    .AddGraphQLGateway()
    .AddCacheControl()
    .UseQueryCache();

AddCacheControl() enables cache-constraint planning. UseQueryCache() writes the final Cache-Control and Vary headers to HTTP responses.

Skip Cache Control for a Specific Request

Use SkipQueryCaching() on OperationRequestBuilder to bypass cache-control for a specific request.

using HotChocolate.AspNetCore;
using HotChocolate.Execution;

public sealed class NoCacheHeaderInterceptor : DefaultHttpRequestInterceptor
{
    public override ValueTask OnCreateAsync(
        HttpContext context,
        IRequestExecutor requestExecutor,
        OperationRequestBuilder requestBuilder,
        CancellationToken cancellationToken)
    {
        if (context.Request.Headers.ContainsKey("X-Skip-Cache-Control"))
        {
            requestBuilder.SkipQueryCaching();
        }

        return base.OnCreateAsync(context, requestExecutor, requestBuilder, cancellationToken);
    }
}

Putting It Together

In day-to-day terms, the flow is simple:

• Subgraphs declare cache intent.
• Fusion composes that metadata.
• The gateway calculates one safe policy for each query result.
• HTTP caches enforce the resulting headers.

Website Content Docs Fusion Cli (`website/content/docs/fusion/cli.md`) Copy Section

title: "Nitro CLI Reference" Copy Chapter

The Nitro CLI provides the nitro fusion command group for composing, validating, publishing, and running Fusion gateway configurations. Use these commands for local development workflows and for publishing configurations to Nitro Cloud.

Installation

npm (recommended) Copy Chapter

npm install @chillicream/nitro

The npm package bundles platform-specific native binaries. Supported platforms: linux-x64, linux-musl-x64, linux-arm64, osx-x64, osx-arm64, win-x64, win-x86, win-arm64.

Homebrew (macOS) Copy Chapter

brew install ChilliCream/tools/nitro-cli

.NET tool Copy Chapter

Install globally:

dotnet tool install --global ChilliCream.Nitro.CommandLine

Or install per-project:

dotnet new tool-manifest
dotnet tool install ChilliCream.Nitro.CommandLine

Verify installation Copy Chapter

nitro --version

Commands Overview

Cloud Authentication Options

Commands that interact with Nitro Cloud (download, publish, upload, validate) accept these global options:

If --api-key is not provided and no NITRO_API_KEY environment variable is set, the CLI uses the session from nitro login.

nitro fusion compose

Composes source schemas into a Fusion archive (.far file).

Syntax Copy Chapter

nitro fusion compose [options]

Options Copy Chapter

Each local .graphql or .graphqls file must have a companion -settings.json file. For example, schema.graphqls requires schema-settings.json. Local files do not use --source-schema-settings-file.

For remote schemas, repeat --source-schema-url and --source-schema-settings-file the same number of times. Nitro pairs them by occurrence: the first URL uses the first settings file, the second URL uses the second settings file, and so on. Keep each pair adjacent in scripts. The settings file selects GET or Apollo _service.sdl acquisition as described in Getting the Subgraph Schema.

If no local file, remote URL, or source removal is specified, the CLI scans the working directory for all .graphql and .graphqls files.

When an archive has no stored setting, composition uses gateway for node resolution and source-local for shareable-field runtime type routing. If you recompose an existing archive without the corresponding flag, Nitro preserves the stored value. See Shareable Abstract Field Routing for the routing behavior.

Examples Copy Chapter

Compose from specific files:

nitro fusion compose \
  --source-schema-file ./Products/schema.graphqls \
  --source-schema-file ./Reviews/schema.graphqls \
  --archive gateway.far \
  --environment Development \
  --enable-global-object-identification

Compose two remote schemas and one local schema. Each remote settings option corresponds to the URL occurrence above it:

nitro fusion compose \
  --source-schema-url https://products.example.com/graphql \
  --source-schema-settings-file ./Products/schema-settings.json \
  --source-schema-url https://reviews.example.com/graphql \
  --source-schema-settings-file ./Reviews/schema-settings.json \
  --source-schema-file ./Inventory/schema.graphqls \
  --archive gateway.far

After a successful composition, Nitro prints:

✅ Composite schema written to '/absolute/path/to/gateway.far'.

Auto-discover and compose all schemas in the current directory:

nitro fusion compose --archive gateway.far

Watch mode for local development:

nitro fusion compose --watch

Watch mode observes local schema directories and paired remote settings files. A watched change triggers recomposition and fetches the remote schemas again. Nitro does not poll remote URLs.

Exclude fields tagged as experimental or internal:

nitro fusion compose \
  --exclude-by-tag experimental \
  --exclude-by-tag internal-only \
  --archive gateway.far

nitro fusion download

Downloads gateway configuration from Nitro Cloud.

Syntax Copy Chapter

nitro fusion download [options]

Options Copy Chapter

Examples Copy Chapter

nitro fusion download \
  --api-id QXBpCmcwMTk5MGUzNDVlMWU3MjMyYjc2MjYxYzFiNjRkMGQzYg== \
  --stage production \
  --output-file gateway.far

nitro fusion migrate

Migrates configuration files from v1 to v2 format.

Syntax Copy Chapter

nitro fusion migrate <TARGET> [options]

Arguments Copy Chapter

Options Copy Chapter

Behavior Copy Chapter

The subgraph-config target converts subgraph-config.json files to the schema-settings.json format. The migration maps subgraph to name and http.baseAddress to transports.http.url. If a schema-settings.json file already exists in the target directory, the migration skips that directory.

Examples Copy Chapter

Migrate all subgraph configs in the current directory:

nitro fusion migrate subgraph-config

Migrate configs in a specific directory:

nitro fusion migrate subgraph-config --working-directory ./subgraphs

nitro fusion publish

Publishes a Fusion configuration to a stage on Nitro Cloud. Three input modes are available (mutually exclusive).

Syntax Copy Chapter

nitro fusion publish [options]

Options Copy Chapter

Input Modes Copy Chapter

Mode 1: Pre-composed archive. Publish an existing .far file with --archive.

nitro fusion publish \
  --archive gateway.far \
  --tag v1.0.0 \
  --stage production \
  --api-id QXBpCmcwMTk5MGUzNDVlMWU3MjMyYjc2MjYxYzFiNjRkMGQzYg==

Mode 2: Source schema files. Compose and publish from local files with --source-schema-file.

nitro fusion publish \
  --source-schema-file ./Products/schema.graphqls \
  --source-schema-file ./Reviews/schema.graphqls \
  --tag v1.0.0 \
  --stage production \
  --api-id QXBpCmcwMTk5MGUzNDVlMWU3MjMyYjc2MjYxYzFiNjRkMGQzYg==

Mode 3: Uploaded schema references. Reference previously uploaded schemas by name and version with --source-schema.

nitro fusion publish \
  --source-schema [email protected] \
  --source-schema [email protected] \
  --tag v1.0.0 \
  --stage production \
  --api-id QXBpCmcwMTk5MGUzNDVlMWU3MjMyYjc2MjYxYzFiNjRkMGQzYg==

Sub-Commands for Advanced Orchestration Copy Chapter

For complex deployment scenarios such as blue-green deployments or manual validation gates, use the publish sub-commands.

nitro fusion publish begin Copy Section

Request a deployment slot.

nitro fusion publish begin \
  --stage production \
  --tag v1.0.0 \
  --api-id QXBpCmcwMTk5MGUzNDVlMWU3MjMyYjc2MjYxYzFiNjRkMGQzYg==

nitro fusion publish start Copy Section

Start composition for the deployment.

nitro fusion publish start

nitro fusion publish validate Copy Section

Validate the configuration before committing.

nitro fusion publish validate --archive gateway.far

nitro fusion publish commit Copy Section

Finalize the deployment.

nitro fusion publish commit --archive gateway.far

nitro fusion publish cancel Copy Section

Cancel the deployment.

nitro fusion publish cancel

Orchestrated Workflow Copy Section

A typical advanced deployment follows this sequence:

1. nitro fusion publish begin -- reserve a deployment slot
2. nitro fusion publish start -- start composition
3. nitro fusion publish validate -- validate the configuration
4. nitro fusion publish commit -- finalize the deployment

To abort at any point, run nitro fusion publish cancel.

nitro fusion run

Starts a local Fusion gateway from an archive file.

Syntax Copy Chapter

nitro fusion run <ARCHIVE_FILE> [options]

Options Copy Chapter

The gateway auto-opens a browser with the Nitro IDE. CORS is enabled, and GraphQL-Preflight and Authorization headers are propagated.

Examples Copy Chapter

Start a gateway on a specific port:

nitro fusion run gateway.far --port 5000

Start a gateway on a random port:

nitro fusion run gateway.far

nitro fusion settings set

Modifies composition settings in a Fusion archive.

Syntax Copy Chapter

nitro fusion settings set <SETTING_NAME> <SETTING_VALUE> [options]

Options Copy Chapter

Available Settings Copy Chapter

Examples Copy Chapter

Enable source-schema node resolution on an existing archive:

nitro fusion settings set global-object-identification true --archive gateway.far
nitro fusion settings set node-resolution source-schema --archive gateway.far

Use common-runtime-types routing on an existing archive:

nitro fusion settings set shareable-field-runtime-type-routing common-runtime-types \
  --archive gateway.far

For the behavior of each routing value, see Shareable Abstract Field Routing.

Configure cache control merging:

nitro fusion settings set cache-control-merge-behavior include --archive gateway.far

Exclude tagged fields:

nitro fusion settings set exclude-by-tag experimental,internal-only --archive gateway.far

nitro fusion upload

Uploads a source schema to Nitro Cloud for later composition.

Syntax Copy Chapter

nitro fusion upload [options]

Options Copy Chapter

Examples Copy Chapter

Upload a source schema:

nitro fusion upload \
  --source-schema-file ./src/Products/schema.graphqls \
  --tag v1.2.3 \
  --api-id QXBpCmcwMTk5MGUzNDVlMWU3MjMyYjc2MjYxYzFiNjRkMGQzYg==

Upload with a git commit SHA as the tag:

nitro fusion upload \
  --source-schema-file ./schema.graphqls \
  --tag $(git rev-parse --short HEAD) \
  --api-id QXBpCmcwMTk5MGUzNDVlMWU3MjMyYjc2MjYxYzFiNjRkMGQzYg==

nitro fusion validate

Validates a schema against a stage on Nitro Cloud. Two input modes are available (mutually exclusive).

Syntax Copy Chapter

nitro fusion validate [options]

Options Copy Chapter

Examples Copy Chapter

Validate from source schema files:

nitro fusion validate \
  --source-schema-file ./Products/schema.graphqls \
  --stage production \
  --api-id QXBpCmcwMTk5MGUzNDVlMWU3MjMyYjc2MjYxYzFiNjRkMGQzYg==

Validate from an archive:

nitro fusion validate \
  --archive gateway.far \
  --stage production \
  --api-id QXBpCmcwMTk5MGUzNDVlMWU3MjMyYjc2MjYxYzFiNjRkMGQzYg==

Schema Settings File Reference

Each source schema requires a schema-settings.json file alongside its .graphqls schema file. This file configures the source schema name, transport settings, and per-environment variable substitutions.

{
  "name": "products-api",
  "transports": {
    "http": {
      "url": "{{API_URL}}"
    }
  },
  "environments": {
    "development": {
      "API_URL": "http://localhost:5110/graphql"
    },
    "production": {
      "API_URL": "https://api.example.com/graphql"
    }
  }
}

Fields Copy Chapter

`name` Copy Section

Type: string (required)

The unique source schema name used in composition. Must match the name used in #!csharp builder.AddGraphQL("products-api").

`transports.http.url` Copy Section

Type: string (required)

The URL template for the subgraph's GraphQL endpoint. Use {{VARIABLE_NAME}} for environment-specific substitution.

`transports.http.devUrl` Copy Section

Type: string (optional)

The URL a local development environment reaches this source schema at. It supports the same {{VARIABLE_NAME}} substitution as url.

devUrl is only consulted for source schemas that do not run in the local AppHost when composing for a local Aspire run. Every other composition ignores it, including nitro fusion compose, publish, and upload. It never survives composition either: the composed configuration always carries a url only.

{
  "name": "products-api",
  "transports": {
    "http": {
      "url": "https://products.example.com/graphql",
      "devUrl": "http://localhost:5110/graphql"
    }
  }
}

When such a source schema defines no devUrl, composition falls back to its url and logs the warning SOURCE_SCHEMA_DEV_URL_MISSING, because a deployed URL is often not reachable from a developer machine. When the URL that is selected for such a source schema references a variable that its environment does not define, composition logs the warning SOURCE_SCHEMA_URL_VARIABLE_UNRESOLVED, falls back from an unresolvable devUrl to the url, and composes an unresolvable url as it is. Neither case fails the composition.

`transports.websockets.devUrl` Copy Section

Type: string (optional)

The same as transports.http.devUrl, for the WebSocket URL of the source schema. A source schema that does not run in the local AppHost and defines no devUrl here keeps its configured transports.websockets.url without a warning.

`transports.http.clientName` Copy Section

Type: string (optional, defaults to "fusion")

The named HTTP client the gateway uses to communicate with this subgraph. Must match what the gateway configures via #!csharp builder.Services.AddHttpClient("fusion").

`transports.subscriptions.transport` Copy Section

Type: "sse" | "ws" (optional)

The transport protocol for real-time subscriptions. Defaults to "sse" (Server-Sent Events).

`extensions.nitro.apiId` Copy Section

Type: string (optional)

The Nitro Cloud API identifier for this subgraph. Required when using Nitro Cloud features like upload or publish.

`environments` Copy Section

Type: object (optional)

Per-environment variable substitutions. The active environment is selected via the --environment flag during composition or via the ASPNETCORE_ENVIRONMENT environment variable.

{
  "environments": {
    "development": {
      "API_URL": "http://localhost:5110/graphql"
    },
    "staging": {
      "API_URL": "https://staging.example.com/graphql"
    },
    "production": {
      "API_URL": "https://api.example.com/graphql"
    }
  }
}

When composing with --environment staging, all {{API_URL}} placeholders resolve to the staging URL.

`preprocessor.inferShareable` Copy Section

Type: boolean (optional, defaults to false)

When true, composition automatically marks every field on this source schema that is resolvable by multiple source schemas as @shareable, skipping INVALID_FIELD_SHARING validation. Fields that are part of a @key, marked @internal or @inaccessible, or defined on the subscription type are not marked automatically.

Environment Variables

The Nitro CLI reads these environment variables as defaults for their corresponding options.

Set these in CI/CD pipelines to avoid passing values as command-line arguments.

Exit Codes

• 0 -- success
• Non-zero -- failure (error details printed to stderr)

Website Content Docs Fusion Composition (`website/content/docs/fusion/composition.md`) Copy Section

title: "Composition" Copy Chapter

What Is Composition?

Composition is the build-time process that takes one or more source schemas (the schemas exported by your subgraphs) and produces a single, validated, distributable execution schema that the gateway uses to plan and execute distributed queries.

Each subgraph is a standalone GraphQL service that exposes a source schema. On its own, a source schema cannot tell whether its types are compatible with the rest of your system, whether the fields it declares actually overlap correctly with another team's source schema, or whether every entity it references can be resolved somewhere. Composition is the step that answers these questions before anything is deployed.

The pipeline runs on the developer machine or in CI. It validates each source schema individually, checks that the schemas are compatible with each other, merges them into one unified schema, validates the merged result, and finally checks that every reachable field can be resolved by at least one subgraph. If any of those phases produces errors, composition fails and emits diagnostic log codes that point to the exact rule that was violated.

The output of a successful composition is a Fusion archive: a package built around the execution schema. Lookup, key, and ownership information is embedded directly into the schema as directives, so the gateway has everything it needs to plan and execute distributed queries by reading the schema alone. The gateway loads this archive at startup and never sees raw source schemas, only the composed result.

Composition is the safety net of a Fusion deployment. It catches schema conflicts (mismatched types, broken @key references, unreachable fields, ambiguous ownership) at build time, not at request time. A query that succeeds against the gateway is guaranteed to be answerable by your fleet of subgraphs because composition has already proven it.

If you are still onboarding, start with Getting Started. The pages on Entities and Lookups and Field Ownership cover the directives most often referenced by the log codes below.

The Composition Pipeline

Composition runs as an ordered set of phases. Each phase reads the output of the previous one, runs its rules, and either passes the schema to the next phase or aborts with diagnostic errors. Composition halts at the first phase that produces errors. Within a single phase, several errors may be reported together before the pipeline stops at the phase boundary.

flowchart TD
    A[Source Schemas] --> B[1. Parse]
    B --> C[2. Preprocess]
    C --> D[3. Enrich]
    D --> E[4. Validate Source Schemas]
    E --> F[5. Pre-Merge Validation]
    F --> G[6. Merge]
    G --> H[7. Post-Merge Validation]
    H --> I[8. Validate Satisfiability]
    I --> J[Execution Schema]
    B -.fail.-> X[Composition Error]
    C -.fail.-> X
    D -.fail.-> X
    E -.fail.-> X
    F -.fail.-> X
    G -.fail.-> X
    H -.fail.-> X
    I -.fail.-> X

1. Parse Source Schemas Copy Chapter

Parses each source schema into an internal representation. This phase catches syntactically invalid SDL (INVALID_GRAPHQL).

2. Preprocess Source Schemas Copy Chapter

Normalizes each source schema for composition. This includes applying tag-based exclusions and any version-specific or interop transformations needed before the validation phases run.

3. Enrich Source Schemas Copy Chapter

Decorates each schema with metadata extracted from directives, such as key fields, shareability, accessibility flags, and lookup information. The metadata is attached to types and fields so later phases can reason about them efficiently without re-parsing directive arguments.

4. Validate Source Schemas Copy Chapter

Runs per-schema validation rules against each source schema independently. Each source schema is checked on its own at this stage, before any cross-schema reasoning. Examples of issues caught here include @external placed on an interface field, malformed @key selection sets, root types with non-default names, and @override referencing the same source schema.

5. Pre-Merge Validation Copy Chapter

Validates compatibility across source schemas. This is where the pipeline checks that two source schemas which both define the same type agree on its shape: enum values match, output field types are mergeable, external argument types align, and input types declare the same required fields. Most "two source schemas disagree" diagnostics are surfaced here.

6. Merge Source Schemas Copy Chapter

Combines all validated source schemas into a single merged schema. Same-named types are unified, Fusion metadata is applied, and lookup information is recorded so the gateway knows which subgraph owns which field.

7. Post-Merge Validation Copy Chapter

Validates the merged schema as a whole. The rules here treat the composed schema as if it were a single GraphQL schema and check global invariants: no merged type is empty, all interfaces are implemented, no field references an inaccessible or internal type, the root query type exposes accessible fields, and default values do not point at inaccessible enum values.

8. Validate Satisfiability Copy Chapter

Performs reachability analysis. Starting from the root types, the pipeline walks every reachable field in the merged schema and confirms it can be resolved by at least one subgraph given the available @lookup and @key paths. If a field is reachable from a query but no subgraph can produce it, satisfiability reports UNSATISFIABLE_QUERY_PATH. This is normally an error. When source-schema node resolution has a usable dispatcher but does not cover a composite Node type, Fusion reports a warning because the source resolver can return null or an error at runtime.

Cost Metadata Derivation

Fusion composition records each compatible source usage as an internal @fusion__cost or @fusion__listSize provenance entry, folds the source values, and projects the result as a public directive. A public @cost or @listSize directive is emitted only when at least one source has a compatible usage. The internal entries identify the source schema and preserve its declared values. An unannotated serving source contributes the coordinate default to the public @cost fold without adding an internal provenance entry.

Both folds only consider serving sources: a source schema that resolves the field itself. A source that provides the field only as partial (for example an Apollo Federation @external field returned through @provides) is not a serving source for either fold, so an unannotated partial member contributes neither the coordinate's default weight nor a gap that widens the @listSize bound. Its own @cost or @listSize usage, when declared, still folds in and is still recorded as its own provenance entry.

A usage without a local directive definition receives the canonical definition during composition. A locally declared definition can use a compatible subset of the canonical arguments.

For @cost, the public weight is the maximum effective weight across every serving source. A declared weight is effective as written. An unannotated serving source contributes the default for the coordinate:

For example, a composite-typed coordinate with weight -7 in one source and no declared weight in another source derives the public weight 1. Given these two source schemas:

# Schema A
type Query {
  book: Book @cost(weight: "-7")
}

type Book {
  id: ID
}

# Schema B
type Query {
  book: Book
}

type Book {
  id: ID
}

Composition folds Query.book to the public weight 1 and records schema A's declared value as its own provenance entry; schema B contributes the coordinate default without one:

type Query @fusion__type(schema: A) @fusion__type(schema: B) {
  book: Book
    @cost(weight: "1")
    @fusion__cost(schema: A, weight: "-7")
    @fusion__field(schema: A)
    @fusion__field(schema: B)
}

The public @listSize directive applies these folds:

The name unions are preserved as declared. A name that does not match an argument or child field in the composite schema contributes no runtime value, and list-size selection continues through its remaining fallbacks.

For assumedSize, given these two source schemas:

# Schema A
type Query {
  field: [Int] @listSize(assumedSize: 10)
}

# Schema B
type Query {
  field: [Int] @listSize(assumedSize: 5)
}

Composition folds assumedSize to the maximum of the two, 10, and records both declared values as provenance entries:

type Query @fusion__type(schema: A) @fusion__type(schema: B) {
  field: [Int]
    @listSize(assumedSize: 10)
    @fusion__field(schema: A)
    @fusion__field(schema: B)
    @fusion__listSize(schema: A, assumedSize: 10)
    @fusion__listSize(schema: B, assumedSize: 5)
}

The slicingArgumentDefaultValue argument is optional. A source can use a spec-only @listSize definition that omits this ChilliCream extension, and it composes without a warning. If every source omits the value, the public directive omits it too.

Composition reports a normal INVALID_GRAPHQL error for invalid locally declared definitions. Applying an argument-less local @cost definition reports The @cost directive must have a 'weight' argument of type String., the source schema name, and the usage coordinate.

Default List Size Copy Chapter

The assumed size for a list field that carries no applicable @listSize information is a composition setting, not a gateway runtime option. Set SourceSchemaMergerOptions.DefaultListSize on the composer:

var options = new SchemaComposerOptions
{
    Merger =
    {
        DefaultListSize = 100
    }
};

When set, composition writes the value onto the execution schema with a schema-level @fusion__cost_options(defaultListSize:) directive, and folds it into the effective assumedSize of a field for which at least one serving source declares a @listSize, so the public @listSize reflects the higher, sound bound. For a field no source annotates, composition emits no @listSize and the gateway applies the value directly from @fusion__cost_options. When absent (the default), no @fusion__cost_options usage is emitted and the gateway treats an unannotated list as unbounded.

See Cost Analysis for gateway enforcement, reporting, and options.

Common Scenarios

A few rules account for most composition failures. Knowing the shape of the error helps you spot the cause quickly.

Two source schemas return incompatible types for the same field. If Product.price is Float in one source schema and Int in another, composition fails with OUTPUT_FIELD_TYPES_NOT_MERGEABLE. Scalar and enum return types must match exactly, while object, interface, and union types merge when one declared type is a supertype of the others (for example, Product and a #!sdl union FeaturedItem = Product merge to FeaturedItem). Align the types when no common supertype exists.

A field is defined in multiple source schemas without @shareable. Defining User.name in both Accounts and Reviews without marking it @shareable produces INVALID_FIELD_SHARING.

# Accounts source schema
type User @key(fields: "id") {
  id: ID!
  name: String!
}

# Reviews source schema
type User @key(fields: "id") {
  id: ID!
  name: String!
}

Composition emits one diagnostic per non-shareable definition, so both source schemas are reported:

The field 'User.name' in schema 'Accounts' must be shareable.

The field 'User.name' in schema 'Reviews' must be shareable.

Add @shareable to User.name in both source schemas that define it. See Field Ownership for when sharing is appropriate.

If you do not want to mark shared fields manually, you can set the per-source-schema preprocessor.inferShareable option in that schema's schema-settings.json to true. When enabled, the composition automatically marks every field on that source schema that is also exposed by other source schemas as @shareable. Only enable inferShareable, if there are other processes in place that ensure fields are semantically the same across source schemas.

@key references a field that does not exist on the type. A #!sdl @key(fields: "sku") on a type that has no sku field fails with KEY_INVALID_FIELDS. The fix is to either add the missing field to the type or correct the selection set in the @key directive. See Entities and Lookups for the rules around key selection sets.

Log Codes Reference

This is the complete list of diagnostic codes the composition pipeline emits, grouped by severity. Codes are stable identifiers and are safe to match on in CI scripts.

The placeholders {0}, {1}, etc. in the message column are replaced with the relevant type, field, or schema name when the diagnostic is emitted.

Errors Copy Chapter