# Technical Documentation: ChilliCream/graphql-platform > ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/ChilliCream/graphql-platform) ### Overview (README.md) [](https://www.nuget.org/packages/HotChocolate/) [](https://github.com/ChilliCream/graphql-platform/blob/main/LICENSE) [](http://slack.chillicream.com/) [](https://twitter.com/chilli_cream) --- # ChilliCream GraphQL Platform Welcome to the ChilliCream GraphQL Platform! We help you, developers and companies, to leverage your APIs to the next level with GraphQL. Strongly-typed schemas that match your APIs 100 percent. Efficient data fetching that reduces overall cost without extra effort. Consumer-friendly, declarative, self documented APIs that support you in your daily work to build powerful UIs effectively. Most of our products are open-source and right here in this repository. Everyone is welcome! Always remember to treat anyone respectful, no matter their gender, opinion, religion, or skin-tone. We're one world and together we're stronger! Join our **awesome community** on [Slack](https://slack.chillicream.com), if you would like to get in touch with us, need help, or just want to learn! ## Our Products ### Hot Chocolate Hot Chocolate is the most efficient, feature-rich, open-source GraphQL server in the .NET ecosystem, that helps developers to build powerful GraphQL APIs and Gateways with ease. [Documentation](https://chillicream.com/docs/hotchocolate/) ### Nitro Nitro App is an awesome, performant, feature-rich GraphQL IDE / API Cockpit that helps developers and data scientists to explore, share, and test any GraphQL API. Nitro App can be installed as a [Desktop App](https://get-nitro.chillicream.com), used as a [Web App](https://nitro.chillicream.com), which can be installed through your browser of choice as well, or used as middleware on your GraphQL endpoint. Middlewares are available in [.NET](https://www.nuget.org/packages/HotChocolate.AspNetCore) and [NodeJS](https://www.npmjs.com/package/@chillicream/nitro-express-middleware). More middlewares will follow. [Documentation](https://chillicream.com/docs/nitro/) ### Strawberry Shake Strawberry Shake is an incredible, open-source GraphQL client for the .NET ecosystem, that helps developers to build awesome UIs in Blazor, Maui, and more. Other than most .NET GraphQL clients, Strawberry Shake is type-safe GraphQL client that generates .NET types from your GraphQL schema out of the box. Moreover, Strawberry Shake comes with a reactive store like in [Relay](https://relay.dev/) and [Apollo Client](https://www.apollographql.com/docs/react/), which is nice due to the fact that you can build reactive UIs in .NET with stuff like client-side data caching and data-fetching strategies. [Documentation](https://chillicream.com/docs/strawberryshake/) ### Green Donut Green Donut is a lightweight, yet powerful DataLoader that simplifies batching, caching, and solves the N+1 problem. [Documentation](https://chillicream.com/docs/hotchocolate/fetching-data/dataloader/) ## Official examples Examples of things built on top of the ChilliCream GraphQL Platform that are open source and can be explored by others. - [GraphQL workshop](https://github.com/ChilliCream/graphql-workshop) - [HotChocolate examples](https://github.com/ChilliCream/hotchocolate-examples) ## Contributing [Become a code contributor](CONTRIBUTING.md) and help us make the ChilliCream GraphQL platform even better! ## From our community [Check out](COMMUNITY.md) what members of our awesome community have made! ## License The source code in this repository is licensed under the [MIT License](LICENSE). The MIT License covers the source code only. It does not cover the ChilliCream name and trademarks, the logos and package icons, or the website content and design. See [TRADEMARKS.md](TRADEMARKS.md) for details. ## Financial Contributors [Become a financial contributor](https://opencollective.com/chillicream/contribute) and help us sustain our community. ### Sponsor [Become a sponsor](https://opencollective.com/chillicream#contribute) and get your logo on our README on Github with a link to your site. ### Backer [Become a backer](https://opencollective.com/chillicream#contribute) and get your image on our README on Github with a link to your site. --- ### Website Content Docs Fusion Getting Started (`website/content/docs/fusion/getting-started.md`) --- title: "Getting Started with GraphQL Federation" description: "Follow a practical GraphQL Federation tutorial to build two subgraphs, compose a unified schema, and query the unified API with ChilliCream's Fusion gateway." --- In this tutorial, you will build and run a small Fusion setup locally. By the end, you will have: - A Products subgraph on `http://localhost:5001/graphql` - A Reviews subgraph on `http://localhost:5002/graphql` - A Fusion gateway on `http://localhost:5000/graphql` - One composed API that clients query through the gateway If you want the broader conceptual background first, read [Overview](./index.md). # What Is Fusion and Why Use It? Hot Chocolate Fusion lets you split a GraphQL API across multiple independent services, called **subgraphs**, and present them to clients as a single, unified schema (called a **composite schema** in the spec). Each subgraph contributes types and fields to the overall API, runs in its own process, and can be developed, deployed, and scaled independently. A **gateway** sits in front of all your subgraphs, receives client queries, routes each part of the query to the subgraphs that own the requested fields, and combines the results. From the client's perspective, they are querying a single GraphQL endpoint with one schema. The gateway handles everything transparently. Instead of building one monolithic GraphQL server that knows about every domain in your system, you let each team own and ship their own GraphQL service. Fusion handles the hard part by composing those services into a single schema that clients query without knowing (or caring) how many services are behind it. **When should you use Fusion?** Fusion becomes valuable when your API spans multiple domains (products, reviews, accounts, shipping), when different teams own different parts of the API, or when you need to deploy and scale parts of your API independently. If you find yourself wanting to break a growing monolith into smaller, team-owned services without forcing clients to stitch together calls to multiple endpoints, Fusion is the tool for the job. # Thinking in Composite Schemas When you first encounter distributed GraphQL, there is a natural assumption about how subgraphs interact that turns out to be wrong. Getting the right mental model now will save you from the most common design mistakes. ## One GraphQL Schema, Many Contributors In Fusion, all subgraphs contribute to **one shared GraphQL schema**. There is no "Products Schema" and "Reviews Schema" that exist as separate GraphQL schemas. There is one graph that describes your entire domain, and different subgraphs are responsible for different parts of it. This means a single type can have fields contributed by multiple subgraphs. For example, the `Product` type might get its `name` and `price` fields from the Products subgraph, its `reviews` field from the Reviews subgraph, and its `deliveryEstimate` field from the Shipping subgraph. From the client's perspective, `Product` is one type with all those fields. The gateway figures out where each field lives and fetches it from the right place. ## Subgraphs Don't Call Each Other When you split an API across multiple services, it is tempting to think each subgraph needs to call other subgraphs directly. Consider two subgraphs: one that manages Tenants, and one that manages Users. A `User` belongs to a `Tenant`. **You might assume this is how it works:** > "My Users subgraph stores a `tenantId` on each User. To resolve the full Tenant object, I need my Users subgraph to call the Tenants subgraph and fetch it." This seems reasonable, but it creates a problem: your subgraphs become coupled. The Users subgraph has to know where the Tenants subgraph lives, how to call it, and how to handle failures. As you add more subgraphs, these cross-service dependencies multiply. **How Fusion actually works:** > "My Users subgraph knows that each User has a `tenantId`, and I declare that `user.tenant` returns a `Tenant` identified by that ID. I don't need to know _how_ or _where_ the Tenant gets resolved, because the gateway handles that." In Fusion, your subgraph never calls another subgraph. Instead, it says: "this field returns a Tenant with this ID" and trusts the gateway to figure out the rest. The gateway knows which subgraph can resolve a Tenant by ID, using a **lookup**, which is a query field that resolves an entity by its key. The Tenants subgraph provides this lookup resolver, and the gateway calls it when it needs to turn a tenant ID into a full Tenant object. The Users subgraph never talks to the Tenants subgraph directly. The gateway handles all coordination. ## Why This Matters This design has practical consequences: - **Subgraphs stay independent.** The Users subgraph does not import anything from the Tenants subgraph. It just knows that `Tenant` is an entity with an `id` field. - **Adding new subgraphs is safe.** If a new Billing subgraph wants to contribute a `billingPlan` field to the `Tenant` type, it can do so without modifying the Tenants or Users subgraphs. - **The gateway is the coordinator.** Cross-subgraph data fetching is the gateway's job, not yours. Your subgraph only needs to know how to resolve the fields it owns and how to look up its own entities by key. When you build your subgraphs in the following sections, keep this model in mind: each subgraph contributes to one API, declares its entities and lookups, and trusts the gateway to wire everything together. # Key Concepts Before diving into code, here are the core terms you will encounter throughout this guide. Each builds on the mental model from the previous section. **Subgraph:** An independent GraphQL service that contributes types and fields to the overall API. Each subgraph runs in its own process, owns its own data, and defines resolvers for the fields it contributes. In Hot Chocolate, a subgraph is a standard Hot Chocolate server with a few additional attributes that tell Fusion how its types fit into the larger API. **Source Schema:** The GraphQL schema exposed by a single subgraph. When you export a subgraph's schema (as a `.graphqls` file), that exported schema is the source schema. Fusion's composition engine reads source schemas from all your subgraphs and merges them into the composite schema. **Composite Schema:** The unified, client-facing GraphQL schema produced by merging all source schemas. All types and fields from every subgraph appear in the composite schema, and clients can query across subgraph boundaries in a single request as if they were querying a single monolithic GraphQL server. They never interact with individual subgraphs directly. **Gateway:** The service that sits between clients and subgraphs. It exposes the composite schema, receives client queries, analyzes each query, routes parts of it to the appropriate subgraphs, and combines the results into a single response. In Hot Chocolate, you create a gateway by calling `AddGraphQLGateway()` in a standard ASP.NET Core project. **Query Planning:** The process the gateway uses to build an optimized execution plan for a client query across multiple subgraphs. When a query touches fields from different subgraphs, the gateway analyzes the query, determines which subgraphs own which fields, and creates a plan that fetches data in the right order. **Entity:** A type with a stable key that can be referenced across subgraphs. Entity keys (such as `id` or `sku`) uniquely identify each instance and are used for cross-subgraph references and resolution. **Lookup:** A query field the gateway uses to enrich an already-referenced entity with additional fields from another subgraph. ```graphql type Query { productById(id: ID!): Product @lookup } ``` - An **internal lookup** (marked with the `@internal` directive) is excluded from the composite schema, cannot be called by clients, and is used only by the gateway for cross-subgraph entity resolution. ```graphql type Query { productById(id: ID!): Product @internal @lookup } ``` **Shareable:** A contract for fields that are defined in multiple subgraphs. By default, each non-key field must be defined by exactly one subgraph. If the same field appears in multiple subgraphs, composition fails until every definition is explicitly marked with the `@sharable` directive. This asserts that all definitions have the same semantics, and it allows the query planner to fetch the field from any subgraph subgraph providing this field. ```graphql type User { name: String @sharable } ``` # Prerequisites To follow this tutorial, you need the following installed on your machine. ## .NET SDK Install the [.NET 10 SDK](https://dotnet.microsoft.com/download) or later. Verify your installation: ```shell dotnet --version ``` You should see `10.0.100` or higher. ## Nitro CLI The Nitro CLI is a .NET tool that handles schema composition. Install it globally: ```shell dotnet tool install -g ChilliCream.Nitro.CommandLine ``` Verify the installation: ```shell nitro version ``` ## Hot Chocolate Templates Install the Hot Chocolate templates: ```shell dotnet new install HotChocolate.Templates ``` # Create Your First Subgraph (Products) Time to write code. You will create a Products subgraph that exposes a few products through a GraphQL API. This subgraph will later become part of your composed API. ## Project Setup Create a new GraphQL server project from the template: ```shell mkdir fusion-getting-started cd fusion-getting-started dotnet new graphql -n Products ``` The template creates sample files in `Products/Types` (`Author.cs`, `Book.cs`, `Query.cs`). Delete those files before continuing so your schema only contains the tutorial types. Your `Products/Products.csproj` should now look like this: ```xml net10.0 enable enable preview runtime; build; native; contentfiles; analyzers; buildtransitive all ``` ## Configure the Port The `dotnet new graphql` template already defines a default port in `launchSettings.json`. For this tutorial, change it so the Products subgraph runs on port 5001. Edit `Products/Properties/launchSettings.json` and set `launchUrl` and `applicationUrl` under the `http` profile to: ```json "launchUrl": "http://localhost:5001/graphql", "applicationUrl": "http://localhost:5001" ``` This ensures the subgraph runs on port 5001, which matches what we will configure for composition later. ## Define the Product Type Create a file called `Product.cs` in the Products project: ```csharp namespace Products; public class Product { public int Id { get; set; } public required string Name { get; set; } public double Price { get; set; } } ``` This is a plain C# class with nothing GraphQL-specific yet. ## Add In-Memory Data Create a file called `ProductRepository.cs`: ```csharp namespace Products; public static class ProductRepository { private static readonly List Products = [ new Product { Id = 1, Name = "Table", Price = 899.99 }, new Product { Id = 2, Name = "Couch", Price = 1299.50 }, new Product { Id = 3, Name = "Chair", Price = 54.00 }, ]; public static Product? GetById(int id) => Products.FirstOrDefault(p => p.Id == id); public static List GetAll() => Products; } ``` > In production, use **DataLoader** or **batch resolvers** in your subgraphs to batch backend lookups and reduce N+1 query patterns. This is especially important for entity lookups across subgraphs. See the [Fusion demo project](https://github.com/ChilliCream/fusion-demo) for a more complete example. ## Expose Products Through GraphQL Create a file called `ProductQueries.cs`. This class defines the Query root fields for the Products subgraph: ```csharp namespace Products; [QueryType] public static partial class ProductQueries { [Lookup] public static Product? GetProductById(int id) => ProductRepository.GetById(id); public static List GetProducts() => ProductRepository.GetAll(); } ``` Two attributes to notice: - **`[QueryType]`** tells Hot Chocolate that this class contributes fields to the `Query` root type. The source generator (from `HotChocolate.Types.Analyzers`) automatically registers these fields. - **`[Lookup]`** marks `GetProductById` as a lookup resolver. This is how the gateway resolves a `Product` when another subgraph references it. Without this attribute, the gateway would have no way to fetch a Product by its ID from this subgraph. Because this lookup is **public**, it also appears in the composite schema as a query field clients can call directly. Lookups must return nullable entity types (`Product?`) so unresolved keys can return `null` and avoid cascading failures when one or more subgraphs cannot provide requested fields for an entity. ## Configure the Server Set `Program.cs` to: ```csharp var builder = WebApplication.CreateBuilder(args); builder .AddGraphQL("Products") .AddTypes(); var app = builder.Build(); app.MapGraphQL(); app.RunWithGraphQLCommands(args); ``` This is a minimal Hot Chocolate server. `#!csharp AddGraphQL("Products")` sets the subgraph name used during schema export. `AddTypes()` registers all discovered types, including `ProductQueries` and `Product`. `RunWithGraphQLCommands(args)` enables CLI commands, including schema export. ## Test the Subgraph Run the Products subgraph: ```shell cd Products dotnet run ``` Open your browser to `http://localhost:5001/graphql/` to access the Nitro GraphQL IDE. Try this query: ```graphql query { products { id name price } } ``` You should see: ```json { "data": { "products": [ { "id": 1, "name": "Table", "price": 899.99 }, { "id": 2, "name": "Couch", "price": 1299.5 }, { "id": 3, "name": "Chair", "price": 54 } ] } } ``` Also test the lookup resolver, which the gateway will use later: ```graphql query { productById(id: 1) { id name price } } ``` Stop the server with `Ctrl+C` before continuing. ## Export the Schema The gateway needs each subgraph's source schema for composition. Hot Chocolate can export source schema files automatically. From the `fusion-getting-started` directory, run: ```shell dotnet run --project ./Products -- schema export ``` This generates two files in the Products project directory: - **`schema.graphqls`**: The Products subgraph's source schema, describing its types and fields. - **`schema-settings.json`**: A companion file that tells Fusion the subgraph's name and runtime URL and other subgraph options. Because `Program.cs` uses `#!csharp AddGraphQL("Products")`, `Products/schema-settings.json` already contains `"name": "Products"`. The generated transport URL still defaults to `http://localhost:5000/graphql`, so update it to match port 5001: ```json { "name": "Products", "transports": { "http": { "url": "http://localhost:5001/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. ## What You Built Your Products subgraph now: - Exposes a `products` query that returns all products - Provides a `productById` lookup that the gateway will use to resolve Product references from other subgraphs - Has an exported schema file (`schema.graphqls`) describing its types - Has a settings file (`schema-settings.json`) telling Fusion where to reach it at runtime In the next section, you will create a second subgraph (Reviews) that references Products. This is where the power of Fusion starts to show. # Create a Second Subgraph (Reviews) Now you will create a Reviews subgraph that adds review data to the API. The key part is that the Reviews subgraph will add a `reviews` field to the `Product` type that lives in the Products subgraph. This is Fusion's core capability: multiple subgraphs contributing fields to the same type. ## Project Setup From the `fusion-getting-started` directory: ```shell dotnet new graphql -n Reviews ``` The template also creates sample files in `Reviews/Types` (`Author.cs`, `Book.cs`, `Query.cs`). Delete those files before continuing. ## Configure the Port The `dotnet new graphql` template already defines a default port in `launchSettings.json`. For this tutorial, change it so the Reviews subgraph runs on port 5002. Edit `Reviews/Properties/launchSettings.json` and set `launchUrl` and `applicationUrl` under the `http` profile to: ```json "launchUrl": "http://localhost:5002/graphql", "applicationUrl": "http://localhost:5002" ``` The Reviews subgraph runs on port 5002, while the Products subgraph runs on 5001. ## Define the Review Type Create `Review.cs` in the Reviews project: ```csharp namespace Reviews; public class Review { public int Id { get; set; } public required string Body { get; set; } public int Stars { get; set; } public int ProductId { get; set; } } ``` Each review has a `ProductId` that references a product from the Products subgraph. ## Add In-Memory Data Create `ReviewRepository.cs`: ```csharp namespace Reviews; public static class ReviewRepository { private static readonly List Reviews = [ new Review { Id = 1, Body = "Sturdy and well-built.", Stars = 5, ProductId = 1 }, new Review { Id = 2, Body = "A bit wobbly.", Stars = 3, ProductId = 1 }, new Review { Id = 3, Body = "Very comfortable!", Stars = 5, ProductId = 2 }, new Review { Id = 4, Body = "Good value for the price.", Stars = 4, ProductId = 3 }, ]; public static Review? GetById(int id) => Reviews.FirstOrDefault(r => r.Id == id); public static List GetByProductId(int productId) => Reviews.Where(r => r.ProductId == productId).ToList(); public static List GetAll() => Reviews; } ``` Notice that reviews reference products by `ProductId`. Reviews 1 and 2 belong to Product 1 (Table), Review 3 belongs to Product 2 (Couch), and Review 4 belongs to Product 3 (Chair). ## Define the Product Stub This is the most important file in this section. Create `Product.cs`: ```csharp namespace Reviews; public sealed record Product(int Id) { public List GetReviews() => ReviewRepository.GetByProductId(Id); } ``` This is **not** a duplicate of the Product type from the Products subgraph. It is an **entity stub**, a lightweight declaration that says: "I know `Product` exists in the API, identified by `Id`, and I want to add a `reviews` field to it." The Reviews subgraph does not define `name`, `price`, or any other Product fields. It only contributes the `reviews` field. When the gateway composes the API, it merges this stub with the full `Product` type from the Products subgraph. Clients see one `Product` type with: - `id`, `name`, and `price` from the Products subgraph - `reviews` from the Reviews subgraph All fields appear on a single unified `Product` type in the composite schema. ## Add Query Resolvers Create `ReviewQueries.cs`: ```csharp namespace Reviews; [QueryType] public static partial class ReviewQueries { [Lookup] public static Review? GetReviewById(int id) => ReviewRepository.GetById(id); public static List GetReviews() => ReviewRepository.GetAll(); } ``` And create `ProductQueries.cs`. This provides the internal lookup that lets the gateway resolve Product references within the Reviews subgraph: ```csharp namespace Reviews; [QueryType] public static partial class ProductQueries { [Lookup, Internal] public static Product? GetProductById(int id) => new(id); } ``` Two attributes to notice: - **`[Lookup]`** makes this a lookup resolver for the `Product` entity. The gateway calls this when it needs to resolve a Product reference. - **`[Internal]`** hides this field from the composite schema. Clients cannot call `productById` on the Reviews subgraph directly. It exists only for the gateway's internal use during query planning. Why is the internal lookup needed? When a client queries `review.product.reviews`, the gateway needs a way to enter the Reviews subgraph's `Product` type so it can resolve the `reviews` field. The internal lookup provides this entry point. Given a product ID (which the gateway already knows from another subgraph), it constructs a `Product` stub that the `reviews` field can then resolve against. Notice that this lookup returns `Product?` (nullable), even though it is internal. Lookups should be nullable so unresolved keys can return `null` and avoid cascading failures across subgraphs. In this sample, the resolver still constructs a stub with `new(id)` because the key is already known. ## Configure the Server Set `Program.cs` to: ```csharp var builder = WebApplication.CreateBuilder(args); builder .AddGraphQL("Reviews") .AddTypes(); var app = builder.Build(); app.MapGraphQL(); app.RunWithGraphQLCommands(args); ``` This follows the same pattern as the Products subgraph, but sets the subgraph name to `Reviews`. ## Add the ObjectType Extension There is one more piece needed. The `Review` type currently exposes a raw `ProductId`. To expose `review.product` instead, add a type extension for `Review`. Create `ReviewNode.cs`: ```csharp using HotChocolate.Types; namespace Reviews; [ObjectType] public static partial class ReviewNode { [BindMember(nameof(Review.ProductId))] public static Product GetProduct([Parent] Review review) => new(review.ProductId); } ``` - **`[ObjectType]`** tells Hot Chocolate that this class extends the `Review` type. - **`[BindMember(nameof(Review.ProductId))]`** replaces the raw `ProductId` integer on `Review` with a resolved `Product` object. In the exported schema, clients see `review.product` (returning a full `Product`) instead of `review.productId` (returning a raw integer). - **`[Parent]`** tells Hot Chocolate to inject the parent object (the `Review`) into the resolver. This is how `GetProduct()` accesses the `ProductId` from the review it belongs to. This transformation happens in the GraphQL schema, not your C# classes. Your `Review` class still has a `ProductId` field internally, but in the exported schema that field is replaced with `product: Product`. When a client queries `review.product`, Hot Chocolate calls `GetProduct()`, reads the `ProductId` from the parent Review, and returns a `Product` stub with just that ID. The gateway then uses the Product lookup to fetch the full product data from whichever subgraph owns it. ## Test the Subgraph Run the Reviews subgraph: ```shell cd Reviews dotnet run ``` Open `http://localhost:5002/graphql/` and try: ```graphql query { reviews { id body stars } } ``` You should see: ```json { "data": { "reviews": [ { "id": 1, "body": "Sturdy and well-built.", "stars": 5 }, { "id": 2, "body": "A bit wobbly.", "stars": 3 }, { "id": 3, "body": "Very comfortable!", "stars": 5 }, { "id": 4, "body": "Good value for the price.", "stars": 4 } ] } } ``` Now try a query that exercises the entity stub and `[BindMember]`: ```graphql query { reviews { id body product { id reviews { body } } } } ``` You should see each review with its product reference, and each product with its reviews. Notice that `product.name` and `product.price` are not available here. Those fields live in the Products subgraph and will only appear after composition in the gateway. Within the Reviews subgraph alone, `Product` only has the fields the Reviews subgraph contributes: `id` and `reviews`. Stop the server with `Ctrl+C`. ## Export the Schema Export the Reviews subgraph's source schema. From the `fusion-getting-started` directory: ```shell dotnet run --project ./Reviews -- schema export ``` This generates two files in the Reviews project directory: - **`schema.graphqls`**: The Reviews subgraph's source schema, describing its types and fields. - **`schema-settings.json`**: A companion file that tells Fusion the subgraph's name and runtime URL and other subgraph options. Because `Program.cs` uses `#!csharp AddGraphQL("Reviews")`, `Reviews/schema-settings.json` already contains `"name": "Reviews"`. The generated transport URL still defaults to `http://localhost:5000/graphql`, so update it to match port 5002: ```json { "name": "Reviews", "transports": { "http": { "url": "http://localhost:5002/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. ## What You Built Your Reviews subgraph now: - Exposes a `reviews` query and a `reviewById` lookup - Adds a `reviews` field to the `Product` type using an entity stub, without duplicating any Product data - Replaces the raw `productId` on reviews with a resolved `Product` reference via `[BindMember]` - Provides an internal `productById` lookup that the gateway uses for cross-subgraph resolution - Has an exported schema and settings file ready for composition You now have two independent subgraphs that contribute to one shared API. In the next section, you will compose them into a single composite schema. # Compose the Schemas with Nitro CLI You now have two subgraphs, each with an exported schema and a settings file. The next step is **composition**: merging these source schemas into a single composite schema that the gateway will serve to clients. Composition is handled by the Nitro CLI. It reads each subgraph's `.graphqls` schema file and its companion `-settings.json` file, validates that the schemas are compatible, and produces a **Fusion archive** (`.far` file) that contains everything the gateway needs: the composite schema, the execution schema with routing metadata, and the transport configuration for each subgraph. ## Verify Your File Structure Before running composition, make sure your project looks like this: ```text fusion-getting-started/ ├── Products/ │ ├── Product.cs │ ├── ProductQueries.cs │ ├── ProductRepository.cs │ ├── Program.cs │ ├── Products.csproj │ ├── schema.graphqls <-- exported schema │ └── schema-settings.json <-- subgraph settings └── Reviews/ ├── Review.cs ├── ReviewRepository.cs ├── ReviewQueries.cs ├── ProductQueries.cs ├── Product.cs ├── ReviewNode.cs ├── Program.cs ├── Reviews.csproj ├── schema.graphqls <-- exported schema └── schema-settings.json <-- subgraph settings ``` Each subgraph directory has a `schema.graphqls` and a `schema-settings.json`. The Nitro CLI matches these files by their shared prefix (`schema`). ## Run Composition From the `fusion-getting-started` directory, run: ```shell mkdir Gateway nitro fusion compose -f Products/schema.graphqls -f Reviews/schema.graphqls -a Gateway/gateway.far ``` If composition succeeds, you will see output similar to: ```text Validating source schemas... Merging schemas... Fusion archive created: gateway.far ``` The exact output may vary by Nitro CLI version. Confirm that `Gateway/gateway.far` was created. This file contains the composed gateway configuration, and the gateway loads it directly. ## What Happens During Composition The Nitro CLI performs four steps: 1. **Validate** source schemas: check GraphQL validity and Fusion metadata. 2. **Merge** source schemas: combine matching types and enforce field ownership rules. 3. **Check satisfiability**: verify that cross-subgraph selections can actually be fulfilled with the available keys and lookups. 4. **Produce** output: create the composite schema plus routing metadata for the gateway. # Run the Fusion Gateway The gateway is the service that clients connect to. It loads the composed configuration from the `.far` file, exposes the composite schema, and routes queries to the appropriate subgraphs at runtime. ## Create the Gateway Project From the `fusion-getting-started` directory: ```shell cd Gateway dotnet new graphql-gateway cd .. ``` The `graphql-gateway` template already includes the `HotChocolate.Fusion.AspNetCore` package and a working gateway `Program.cs`. Your `Gateway/Gateway.csproj` should look like this: ```xml net10.0 enable enable ``` ## Configure the Port Edit `Gateway/Properties/launchSettings.json` and set `launchUrl` and `applicationUrl` under the `http` profile to: ```json "launchUrl": "http://localhost:5000/graphql", "applicationUrl": "http://localhost:5000" ``` The gateway runs on port 5000. The subgraphs run on ports 5001 (Products) and 5002 (Reviews). ## Verify the Fusion Archive The composition step already wrote `gateway.far` into the `Gateway` directory (`-f Gateway/gateway.far`). Verify that the file exists before continuing: ```shell ls Gateway/gateway.far ``` ## Configure the Gateway The template generates `Gateway/Program.cs`. For this tutorial, enable operation-plan telemetry so Nitro can show execution metrics in the Operation Plan view: ```csharp var builder = WebApplication.CreateBuilder(args); builder.Services .AddHttpClient("fusion"); builder .AddGraphQLGateway() .AddFileSystemConfiguration("./gateway.far") .ModifyRequestOptions(o => o.CollectOperationPlanTelemetry = true); var app = builder.Build(); app.MapGraphQL(); app.Run(); ``` Three things to notice: - **`#!csharp AddHttpClient("fusion")`** registers a named HTTP client called `"fusion"`. The gateway uses this client to send requests to the subgraphs. The name `"fusion"` is the default HTTP client name that Fusion uses when no explicit `clientName` is specified in the subgraph's `schema-settings.json`. - **`AddGraphQLGateway()`** registers the Fusion gateway services. This is what makes this project a gateway rather than a regular GraphQL server. - **`#!csharp AddFileSystemConfiguration("./gateway.far")`** tells the gateway to load its composed configuration from a local file. In production, you would typically use `.AddNitro()` to download the configuration from the Nitro cloud, but for local development the file system approach is simpler. - **`#!csharp ModifyRequestOptions(o => o.CollectOperationPlanTelemetry = true)`** enables operation-plan telemetry. This is off by default. ## Start Everything You need all three services running at the same time: both subgraphs and the gateway. Open three terminal windows and start the subgraphs first. > [!CAUTION] > Start the Products and Reviews subgraphs before the gateway. The gateway connects to each subgraph on startup and may log errors if they are not reachable. **Terminal 1: Products subgraph** ```shell cd fusion-getting-started/Products dotnet run ``` **Terminal 2: Reviews subgraph** ```shell cd fusion-getting-started/Reviews dotnet run ``` **Terminal 3: Gateway** ```shell cd fusion-getting-started/Gateway dotnet run ``` Wait for all three services to start. You should see output like this in each terminal: ```text info: Microsoft.Hosting.Lifetime[14] Now listening on: http://localhost:5001 info: Microsoft.Hosting.Lifetime[0] Application started. Press Ctrl+C to shut down. ``` The port number will differ for each service (5001, 5002, and 5000). If you see errors like "Address already in use," another process is using that port. Either stop it or choose a different port in `launchSettings.json`. ## Verify the Gateway Open your browser to `http://localhost:5000/graphql/` to access the Nitro GraphQL IDE on the gateway. Try a simple query to verify the gateway is working: ```graphql query { products { id name price } } ``` You should see the same product data as when you queried the Products subgraph directly. The difference is that this query went through the gateway, which routed it to the Products subgraph behind the scenes. If you look at the terminal running the Products subgraph (Terminal 1), you should see a log entry showing it received and processed the request. This confirms the gateway successfully routed the query. ## What You Built Your gateway now: - Loads the composed configuration from the `gateway.far` file - Exposes the unified composite schema on port 5000 - Routes queries to the Products and Reviews subgraphs as needed - Acts as the single entry point for clients, so they never talk to the subgraphs directly In the next section, you will run queries that demonstrate the gateway coordinating data across both subgraphs in a single request. # Query Across Subgraphs This is the moment everything comes together. With all three services running (Products on 5001, Reviews on 5002, Gateway on 5000), you can now run a single query that fetches data from both subgraphs. ## The Cross-Subgraph Query Open Nitro at `http://localhost:5000/graphql/` and run this query: ```graphql query { products { id name price reviews { body stars } } } ``` Example in Nitro: You should see: ```json { "data": { "products": [ { "id": 1, "name": "Table", "price": 899.99, "reviews": [ { "body": "Sturdy and well-built.", "stars": 5 }, { "body": "A bit wobbly.", "stars": 3 } ] }, { "id": 2, "name": "Couch", "price": 1299.5, "reviews": [{ "body": "Very comfortable!", "stars": 5 }] }, { "id": 3, "name": "Chair", "price": 54, "reviews": [{ "body": "Good value for the price.", "stars": 4 }] } ] } } ``` Look at what happened: `name` and `price` came from the Products subgraph, while `reviews` came from the Reviews subgraph. The client sent one query to one endpoint, and the gateway coordinated the rest. ## What the Gateway Did Behind the scenes, the gateway executed a query plan with multiple steps: To inspect the plan in Nitro, open the **Operation Plan** tab and enable it. With `CollectOperationPlanTelemetry` enabled on the gateway, the plan includes telemetry such as step duration and status: 1. **Fetched the products** from the Products subgraph. This returned `id`, `name`, and `price` for each product. 2. **Resolved the reviews** from the Reviews subgraph. Using each product's `id`, the gateway called the Reviews subgraph's internal `productById` lookup to get a `Product` stub, then resolved the `reviews` field on each stub. 3. **Combined the results** into a single response that looks exactly like it came from one GraphQL server. The client never knew that two separate services were involved. This is the core promise of Fusion: multiple subgraphs, one unified API. ## Try Another Query You can also query in the other direction: start from reviews and reach into product data. ```graphql query { reviews { body stars product { name price } } } ``` You should see: ```json { "data": { "reviews": [ { "body": "Sturdy and well-built.", "stars": 5, "product": { "name": "Table", "price": 899.99 } }, { "body": "A bit wobbly.", "stars": 3, "product": { "name": "Table", "price": 899.99 } }, { "body": "Very comfortable!", "stars": 5, "product": { "name": "Couch", "price": 1299.5 } }, { "body": "Good value for the price.", "stars": 4, "product": { "name": "Chair", "price": 54 } } ] } } ``` This time, `body` and `stars` came from the Reviews subgraph, while `product.name` and `product.price` came from the Products subgraph. The gateway resolved the product references by calling the Products subgraph's `productById` lookup with each review's product ID. ## Compare: Before and After Composition Remember in the previous section, when you queried `review.product` on the Reviews subgraph directly? You could see `product.id` and `product.reviews`, but `product.name` and `product.price` were missing because those fields did not exist in the Reviews subgraph. Now, through the gateway, `product.name` and `product.price` are available. Composition merged the Product type from both subgraphs, and the gateway resolves each field from the subgraph that owns it. This is what it means for subgraphs to contribute to one shared API. ## Lookup a Single Product You can also look up a single product by ID: ```graphql query { productById(id: 1) { name price reviews { body stars } } } ``` This uses the `productById` lookup from the Products subgraph, the public one that appears in the composite schema. The gateway then fetches reviews from the Reviews subgraph using its internal lookup. Public lookups serve as both client-facing query fields and gateway entity resolution entry points, while internal lookups are only used by the gateway behind the scenes. ## What You Accomplished You proved that Fusion works: - Clients send queries to one endpoint (the gateway) - The gateway routes parts of each query to the appropriate subgraphs - Multiple subgraphs contribute fields to the same types (`Product`, `Review`) - Cross-subgraph entity resolution happens automatically through lookups - The result is a unified API that feels like one service The Products and Reviews subgraphs are completely independent. They do not import each other's code, do not call each other directly, and can be deployed and scaled separately. Yet clients can query across both as if they were one unified schema. # Sharing Fields Across Subgraphs In the tutorial so far, the Products and Reviews subgraphs each contribute **different** fields to the `Product` type. Products owns `name` and `price`, while Reviews owns `reviews`. There is no overlap, so composition works without any special annotations. But what happens when two subgraphs need to define the **same** field on the same type? By default, Fusion treats this as an error. If two subgraphs both define `Product.name`, composition fails because Fusion does not know which subgraph should be authoritative. The `[Shareable]` attribute solves this. When you mark a field as shareable in both subgraphs, you are telling Fusion: "these definitions are intentional and return the same data. Use whichever is most efficient." ## When You Need It A common scenario: your Reviews subgraph needs to display the product name alongside each review. You could always fetch the name from the Products subgraph via the gateway, but if performance matters, you might want the Reviews subgraph to cache product names locally. In that case, both subgraphs would define `Product.name`: **Products subgraph:** ```csharp public class Product { public int Id { get; set; } [Shareable] public required string Name { get; set; } public double Price { get; set; } } ``` **Reviews subgraph (entity stub):** ```csharp public sealed record Product(int Id) { [Shareable] public string Name => ProductRepository.GetProductName(Id); public List GetReviews() => ReviewRepository.GetByProductId(Id); } ``` Both subgraphs define `Product.name` and mark it `[Shareable]`. Composition succeeds, and the gateway can resolve `name` from either subgraph depending on what else the query needs. If a query only asks for `product.name` and `product.reviews`, the gateway will fetch everything from the Reviews subgraph in a single call instead of making a separate trip to the Products subgraph. ## The Rule Without `[Shareable]`, a non-key field must exist in exactly one subgraph. Key fields (like `id`) are automatically shareable, so you do not need the attribute on them. For any other field that appears in multiple subgraphs, add `[Shareable]` to **all** definitions of that field. If even one subgraph forgets to mark it, composition fails. ## When Not to Use It Do not mark a field as shareable unless the subgraphs genuinely return the same data. If two subgraphs define `Product.name` but one returns the display name and the other returns an internal code name, marking them shareable would give clients inconsistent results depending on which subgraph the gateway happens to call. If the fields return **different** data, they should have **different** names (e.g., `displayName` vs `codeName`) and each lives in its own subgraph without `[Shareable]`. # What's Next You now have a working Fusion setup: two subgraphs contributing to one composed API, served through a single gateway. Here are some directions to explore next based on what you need: - **I want to add another subgraph to this project**: [Adding a Subgraph](./adding-a-subgraph.md) - **I want to understand entities more deeply**: [Entities and Lookups](./entities-and-lookups.md) - **I need cross-subgraph field dependencies (`[Require]`)**: [Entities and Lookups](./entities-and-lookups.md) - **I need to deploy this**: [Deployment & CI/CD](./deployment-and-ci-cd.md) - **I need to secure this**: [Authentication and Authorization](./authentication-and-authorization.md) - **I'm coming from Apollo**: [Coming from Apollo Federation](./migration/coming-from-apollo-federation.md) --- ### Website Content Docs Fusion Index (`website/content/docs/fusion/index.md`) --- title: Fusion metaTitle: "Fusion: Federated GraphQL Gateway" description: "Fusion is ChilliCream's GraphQL gateway for composing multiple services into one API, implementing the GraphQL Composite Schemas spec with build-time validation." --- Fusion lets you split one GraphQL API into multiple smaller services, without changing how clients consume it. Clients still send queries to one endpoint, and Fusion combines data from all services into one response. Teams can deploy independently, and contract conflicts are caught during build time. # What Is Fusion Fusion is ChilliCream's API gateway for exposing one GraphQL API over multiple upstream services. Those upstream services can be GraphQL, OpenAPI-based REST, or gRPC. Each service owns its contract and implementation. Fusion composes those contracts at build time, and the gateway orchestrates execution at runtime. Fusion implements the [GraphQL Composite Schemas specification](https://graphql.github.io/composite-schemas-spec/draft/), an open standard being developed under the GraphQL Foundation. The architecture has three parts: **Subgraphs** are the upstream services behind the Fusion gateway: GraphQL services, OpenAPI-based REST services, and gRPC services. Each subgraph owns part of the API surface and implementation logic, and can be developed and deployed independently. A **source schema** is the contract document for a subgraph, such as a GraphQL schema, an OpenAPI document, or a gRPC/protobuf definition. **Composition** processes all source schemas, validates them against each other, and produces a Fusion archive (`.far`) that contains the composite schema and gateway configuration. Type conflicts, missing fields, and incompatible enums are caught in CI before deployment. The **gateway** receives client requests, determines which subgraphs to call, executes those calls, and merges the results. **GraphQL subgraphs stay standard GraphQL servers.** The [GraphQL Composite Schemas specification](https://graphql.github.io/composite-schemas-spec/draft/) is designed so a standard GraphQL server can already act as a compatible subgraph. In a common Hot Chocolate setup, subgraphs remain normal Hot Chocolate servers with regular resolvers, without a separate distributed-runtime package or vendor-specific protocol layer. The result: clients send one request to one endpoint and receive one unified response, while Fusion handles routing and aggregation across upstream services. The following query touches three services, but the client doesn't know or care about this implementation detail. ```graphql query { products(first: 5) { nodes { name # from Products service price # from Products service reviews { # from Reviews service stars author { username # from Accounts service } } } } } ``` # Key Terminology | Term | Definition | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Subgraph** | An upstream service behind the Fusion gateway. A subgraph can be a GraphQL service, an OpenAPI-based REST service, or a gRPC service. | | **Source schema** | The contract document published by one subgraph (for example a GraphQL schema, OpenAPI document, or gRPC/protobuf definition). | | **Composite schema** | The unified, client-facing GraphQL schema produced during composition. Clients query this schema as if it were a single API. | | **Gateway** | The public entry point for client requests. It receives queries against the composite schema, routes requests across subgraphs, and assembles responses. | | **Entity** | A type with a stable key that can be referenced across GraphQL subgraphs. A subgraph can define an entity without resolving it locally. | | **Lookup** | A Query field annotated with a `@lookup` directive that resolves an entity by key in that subgraph. | | **Composition** | The offline step that validates source schemas and produces the composite schema and gateway configuration. Runs via the Nitro CLI or Aspire. | # When to Use Fusion Fusion adds operational complexity, including a gateway process, a composition step in your build pipeline, and distributed debugging. That complexity pays off in specific situations: - **Multiple teams need to ship independently.** If different teams own different parts of your API (e.g., a product catalog team and a reviews team), Fusion lets each team deploy on their own schedule without coordinating schema changes through a shared codebase. - **You need to scale services differently.** Your product search might need 10 instances while your user profile service needs 2. With separate services, you scale each one based on its actual load. - **Your domain has clear boundaries.** If your data naturally splits into distinct areas (accounts, products, orders, reviews), separate services map well to those boundaries. Each service owns its data store and its API contract. - **You want build-time validation of distributed contracts.** Composition catches conflicts between source schemas before deployment. Your CI pipeline can validate that a change in one service does not break the composed API. # When NOT to Use Fusion Fusion is not the right choice for every project. Evaluate whether the additional complexity is justified: - **One team, one service.** If one team owns the entire API and deploys it as a single unit, a standard Hot Chocolate server is simpler and has lower operational overhead. You likely do not need a gateway, a composition pipeline, or distributed tracing. - **A small or early-stage API.** If your API has a handful of types and modest traffic, a distributed gateway setup often adds more complexity than value. Start with a monolith and split later when needed. Hot Chocolate supports an incremental path from monolith to modular monolith to distributed architecture. - **No clear domain boundaries.** If your types are deeply intertwined and most queries touch most of the schema, splitting into many services can create more cross-service calls than it removes. Fusion works best when services are relatively self-contained and have clear data contracts. - **Your team is just getting started with GraphQL.** Learn GraphQL and Hot Chocolate first. Get comfortable with types, resolvers, DataLoaders, and the execution pipeline. Fusion adds concepts on top of that foundation and is easier to adopt once the basics are understood. The cost of premature distribution is real: more services to deploy, more infrastructure to monitor, and harder debugging when something goes wrong. Start simple, and add Fusion when the pain of a monolith outweighs the cost of distribution. # Migrating from a Monolith If you already have a Hot Chocolate server, you can adopt Fusion incrementally. **Start with one upstream service.** Point the Fusion gateway at your existing Hot Chocolate server as the only subgraph. Composition works with one source schema. Your clients connect to the gateway instead of directly to your server, but behavior stays the same. **Add services incrementally.** When a new team or domain needs its own service, add another subgraph. The new service can extend types from the original service with entity stubs where needed. Composition merges both source schemas, and the gateway handles cross-service execution automatically. Your original service does not need a rewrite. **Clients see no difference.** Whether you have one subgraph or ten, clients still call one endpoint and keep the same query surface. You can split your monolith over weeks or months without breaking the client contract. The key insight: this is not a rewrite. It is a gradual process. You move types and fields to new services over time, and the gateway smooths over the transition. # Next Steps Where you go from here depends on what you need: - **"I want to build something."** Start with the [Getting Started](./getting-started.md) tutorial. You will create two services and a gateway from scratch. - **"I want to add another service to an existing project."** Go to [Adding a Subgraph](./adding-a-subgraph.md). It covers creating a new service (subgraph) that extends existing entity types. - **"I'm migrating from another distributed GraphQL framework."** Read [Coming from Apollo Federation](./migration/coming-from-apollo-federation.md) or [Migrating from Schema Stitching](./migration/migrating-from-schema-stitching.md). These guides map familiar concepts to Fusion equivalents and walk through a migration. - **"I need to deploy this."** See [Deployment & CI/CD](./deployment-and-ci-cd.md) for pipeline setup, schema management, and gateway configuration. - **"I need CDN and browser caching behavior."** See [Cache Control](./cache-control.md) for `@cacheControl`, composition merge behavior, and gateway response headers. --- ### Website Content Docs Hotchocolate Index (`website/content/docs/hotchocolate/index.md`) --- title: Hot Chocolate metaTitle: "Hot Chocolate: GraphQL Server for .NET" description: "Hot Chocolate is an open-source GraphQL server for .NET that turns your C# classes into a spec-compliant schema and handles parsing, validation, and execution." --- Hot Chocolate is an open-source [GraphQL](https://graphql.org/) server for .NET. You define your API shape using C# classes and methods, and Hot Chocolate translates that into a spec-compliant GraphQL schema. It handles parsing, validation, execution, and transport so you can focus on your domain logic. # What Is Hot Chocolate Hot Chocolate is a GraphQL server framework that runs on [ASP.NET Core](https://learn.microsoft.com/aspnet/core). You write C# types and resolvers. Hot Chocolate turns them into a GraphQL schema, validates incoming operations against that schema, executes them, and returns results over HTTP, WebSocket, or Server-Sent Events. Hot Chocolate implements the [GraphQL 2025 specification](https://spec.graphql.org/) and several draft features including `@defer`, `@stream`, and `@requiresOptIn`. It implements the [GraphQL over HTTP specification](https://graphql.github.io/graphql-over-http/) for transport. It is compatible with all spec-compliant clients, including [Strawberry Shake](../strawberryshake/index.md), [Relay](https://relay.dev/), and [Apollo Client](https://www.apollographql.com/docs/react/). # How You Build a Schema Hot Chocolate supports two approaches to building a GraphQL schema. Both produce the same result: a fully typed, spec-compliant GraphQL schema. They differ in how you express it in C#. ## Implementation-First With implementation-first, your C# implementation is the single source of truth for your GraphQL schema. Define your API using familiar C# classes and attributes like `[QueryType]`. At build time, a source generator analyzes your code and creates the GraphQL types for you. You focus on your business logic, since your implementation is your schema. You don’t need to manually keep your code and schema in sync, deal with GraphQL-specific boilerplate, or write large type definitions in C#. ```csharp [QueryType] public static partial class ProductQueries { public static async Task GetProductByIdAsync( int id, CatalogContext db, CancellationToken ct) => await db.Products.FindAsync([id], ct); } ``` This approach is similar to how Meta built their GraphQL server. Your schema stays close to your domain code, while the tooling handles the translation. ## Code-First The code-first approach lets you define your GraphQL types and schema structure directly in C# using Hot Chocolate’s fluent type descriptor API. ```csharp public class ProductType : ObjectType { protected override void Configure(IObjectTypeDescriptor descriptor) { descriptor .Field(p => p.Id) .Type>(); descriptor .Field(p => p.Name) .Type>(); } } ``` Code-first is useful when you need to decouple the GraphQL schema shape from your C# model, or when you are building infrastructure that generates schemas programmatically. Both approaches can be mixed in the same project. You can use implementation-first for most types and drop into code-first for specific cases that need more control. # GraphQL API Security Strategies GraphQL APIs are typically designed for one of two usage models. Either your API is exclusively consumed by applications you control (first-party), such as your own web, mobile, or internal services, where you define and manage every client operation. Or your API is open to external developers or partners (third-party), and you have no control over the GraphQL operations they send. This distinction shapes how you configure Hot Chocolate and operate your GraphQL server. ## First-party GraphQL A first-party API is consumed exclusively by your own applications. This is how Meta built and operates GraphQL internally. Because you control both the server and every client, you know every operation at build time. This enables you to maintain a precise schema usage history and strictly allow only approved GraphQL operations. Hot Chocolate supports this scenario with **trusted documents**. You extract all operations from your client applications during their build process, register them with the server, and the server only accepts pre-registered operations. - [Trusted documents](./performance/trusted-documents.md) covers the full workflow: extraction, registration, and enforcement. - [Strawberry Shake](../strawberryshake/index.md) and [Relay](https://relay.dev/docs/guides/persisted-queries/) both support build-time operation extraction. When in the future you want to change or phase out parts of your schema you know the impact this change will have to your system before you apply it. This is a super power for API evolution. ## Third-party GraphQL A third-party API is consumed by external developers or clients outside your organization. GitHub’s GraphQL API is a canonical example. You publish a schema, and external teams build applications against it. Because you do not control the clients, they can send any operation they want. Hot Chocolate provides **cost analysis** for this scenario. You assign weights to fields and connections, and the server rejects operations that exceed the performance budget before execution begins. - [Cost analysis](./security/cost-analysis.md) explains field weights, type costs, and budget configuration. - [Controlling introspection](./security/introspection.md) lets you restrict schema visibility in production. These two approaches complement each other. A common setup is to host both a public and an internal GraphQL API. The internal API uses trusted documents to strictly control operations, while the public API relies on cost analysis and other safeguards to manage external traffic and protect against abuse. # Key Terminology | Term | Definition | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Schema** | The contract that describes what data clients can query. Hot Chocolate generates it from your C# code. | | **Query type** | The root type for read operations. Clients enter the graph through fields on this type. | | **Mutation type** | The root type for write operations. Mutations execute serially and are expected to cause side effects. | | **Subscription type** | The root type for real-time operations. Clients subscribe to events and receive updates as they occur. | | **Resolver** | A function that fetches data for a single field. In implementation-first, each public method on a `[QueryType]` class is a resolver for third-party or first-party APIs. | | **Batch resolver** | A resolver that fetches data for multiple parent objects in a single call, improving performance by reducing the number of backend requests. Useful for solving the N+1 problem and optimizing data access patterns. | | **DataLoader** | A batching and caching layer that groups multiple individual data requests into a single batch call, eliminating the N+1 problem. | | **Source generator** | A Roslyn source generator that inspects your C# code at build time and generates the schema registration, resolver pipelines, and DataLoader infrastructure. | | **Cost analysis** | An analysis pass that evaluates operation cost before execution and rejects operations that exceed configured limits. Based on the [IBM Cost Analysis specification](https://ibm.github.io/graphql-specs/cost-spec.html). | | **Trusted documents** | Pre-registered operations that the server accepts by hash. Operations not in the store are rejected. Also known as persisted operations. | # Scaling Beyond a Single Server When your API grows beyond what a single service can handle, [Fusion](../fusion/index.md) lets you split your schema across multiple independent services. Each service owns part of the API surface. A gateway composes them into one unified schema that clients query as a single endpoint. Fusion is not a separate product. It builds on Hot Chocolate. A standard Hot Chocolate server can act as a Fusion subgraph without changes to its resolvers or type definitions. You can start with a single Hot Chocolate server and add Fusion later when you need independent deployment or team-level ownership boundaries. # Next Steps Where you go from here depends on what you need: - **"I want to build something."** Start with the [Getting Started](./get-started-with-graphql-in-net-core.md) tutorial. You will create a running GraphQL server in under five minutes. - **"I want to understand the schema system."** Read [Defining a Schema](./defining-a-schema/index.md). It covers queries, mutations, subscriptions, and all the GraphQL types. - **"I need to fetch data efficiently."** Go to [DataLoader](./fetching-data/batching/dataloader.md) for batching and caching, or [Resolvers](./resolvers/index.md) for the full resolver API. - **"I need to secure my API."** See [Securing Your API](./security/index.md) for authentication, authorization, cost analysis, and trusted documents. - **"I'm migrating from an older version."** Read the [migration guide from v15 to v16](./migrating/migrate-from-15-to-16.md). - **"I want to split my API across services."** See [Fusion](../fusion/index.md) for distributed GraphQL with a gateway. --- ### Website Content Docs Mocha Index (`website/content/docs/mocha/index.md`) --- title: Mocha metaTitle: "Mocha: Messaging Bus for .NET" description: "Mocha is a messaging framework for .NET with a message bus for inter-service communication and a source-generated mediator for in-process CQRS." --- ```csharp // Inter-service messaging via the message bus builder.Services .AddMessageBus() .AddOrderService() // source-generated handler registration .AddRabbitMQ(); // In-process CQRS via the mediator builder.Services .AddMediator() .AddHandlers(); ``` Mocha gives you two dispatch mechanisms. The **message bus** sends messages across service boundaries through a transport like RabbitMQ. The **mediator** dispatches commands, queries, and notifications within a single process using source-generated code - no reflection, no dictionary lookups. Use them independently or together. # What Mocha is Mocha is a messaging framework for .NET with two complementary dispatch systems: - **Message bus** - sends messages across service boundaries through transports like RabbitMQ. Supports pub/sub events, request/reply, saga orchestration, inbox/outbox reliability, and pluggable transports. Follows the patterns described in [Enterprise Integration Patterns](https://www.enterpriseintegrationpatterns.com/patterns/messaging/Introduction.html). - **Mediator** - dispatches commands, queries, and notifications within a single process. A Roslyn source generator produces a concrete mediator class at compile time with specialized dispatch and pre-compiled pipeline delegates. No reflection, no runtime code generation. Both integrate directly into ASP.NET Core's dependency injection and are designed for [event-driven architectures](https://learn.microsoft.com/en-us/azure/architecture/guide/architecture-styles/event-driven). Use the message bus when messages cross process boundaries. Use the mediator when you want in-process CQRS with pipeline behaviors for cross-cutting concerns like validation, logging, and transactions. Most real-world services use both: the mediator handles internal command/query dispatch, and the message bus handles inter-service events. The framework is handler-first in both cases. You implement handler interfaces, and Mocha builds the infrastructure around those declarations - whether that means wiring up transport endpoints and middleware pipelines for the bus, or generating a type-safe mediator class with pre-compiled dispatch for in-process handlers. # Terminology These terms appear throughout the documentation. They are defined once here and used consistently everywhere. | Term | Definition | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Message** | A plain C# record representing business data. The unit of communication between handlers and services. | | **Event** | A message published via `PublishAsync`. Represents something that happened. Multiple handlers can receive an event. | | **Request** | A message sent via `SendAsync` or `RequestAsync`. When sent with `RequestAsync`, the sender awaits a typed response. When sent with `SendAsync`, it is fire-and-forget. | | **Handler** | A class implementing a Mocha handler interface that processes a specific message type. | | **Consumer** | The processing unit that wraps a handler or custom logic. Mocha builds consumers automatically from handlers, or you can implement `IConsumer` or `Consumer` directly. | | **Endpoint** | A named, addressable unit in the messaging topology. Each endpoint has a transport address, a middleware pipeline, and a kind (default, error, skipped, or reply). Receive endpoints consume messages; dispatch endpoints produce them. | | **Transport** | The infrastructure layer connecting Mocha to a message broker, such as RabbitMQ or an in-process channel. | | **Pipeline** | The chain of middleware that processes a message from the transport through to the handler. | | **Saga** | A long-running stateful workflow that coordinates multiple messages and transitions across services. | | **Mediator** | An in-process dispatcher that routes commands, queries, and notifications to their handlers without a transport layer. Source-generated at compile time. | | **Source generator** | A Roslyn analyzer that discovers handlers and sagas at compile time and generates typed registration code. Used by both the [mediator](./mediator/index.md) and the [message bus](./handler-registration.md). | | **Command** | A mediator message representing an action. Implements `ICommand` (void) or `ICommand` (with response). Dispatched via `SendAsync`. | | **Query** | A mediator message representing a read operation. Implements `IQuery`. Dispatched via `QueryAsync`. | # Architecture When you call `PublishAsync`, here is what happens: Your code in OrderService calls `PublishAsync` with an `OrderPlaced` message **(1)**. Mocha serializes it and hands it to the dispatch endpoint **(2)**, which sends it into RabbitMQ. The broker routes the message through two exchanges into the queue (the unnumbered transport layer between the services). On the BillingService side, the receive endpoint **(3)** picks the message off the queue, runs it through the middleware pipeline, and calls `HandleAsync` on your `OrderPlacedHandler` **(4)**. Middleware in the pipeline handles cross-cutting concerns - tracing, retries, concurrency limits - without touching your handler code. # Core capabilities ## Handler-first design You write handlers. That is the primary abstraction. Implement an interface, register it with the builder, and your handler runs when the matching message arrives. ```csharp public class OrderPlacedHandler(AppDbContext db) : IEventHandler { public async ValueTask HandleAsync( OrderPlaced message, CancellationToken cancellationToken) { var invoice = new Invoice { OrderId = message.OrderId }; db.Invoices.Add(invoice); await db.SaveChangesAsync(cancellationToken); } } ``` Mocha provides handler interfaces for each messaging pattern: | Interface | Pattern | Bus method | | ---------------------------------- | ---------------------- | ------------------------ | | `IEventHandler` | Pub/sub events | `PublishAsync` | | `IEventRequestHandler` | Request/reply | `RequestAsync` | | `IEventRequestHandler` | Send (fire-and-forget) | `SendAsync` | | `IBatchEventHandler` | Batch processing | `PublishAsync` (batched) | ## Messaging patterns and consumers Mocha supports three core patterns for message-driven systems. Each pattern answers a different question: - **Events (pub/sub):** Who needs to know? Publish once, all subscribers receive it. Use `PublishAsync` and `IEventHandler`. - **Send (fire-and-forget):** Who should act? Deliver to one endpoint without waiting for a result. Use `SendAsync` and `IEventRequestHandler`. - **Request/reply:** What is the result? Send and await a typed response. Use `RequestAsync` and `IEventRequestHandler`. Handlers are the fastest way to get started, but they are not the only option. If you need full control over message processing, implement `IConsumer` for a lightweight consumer or extend `Consumer` for complete customization. ## Pluggable transports Switch transports without changing your handler code, and use multiple transports at the same time. Register a default transport, then route specific messages through a different transport when you need different throughput or delivery characteristics: ```csharp builder.Services .AddMessageBus() .AddEventHandler() .AddEventHandler() // Default transport for most messages .RabbitMQ() // High-throughput transport for specific messages .AddEventHub(t => t.AddEventHandler()); ``` ## Middleware pipelines Underneath, everything in Mocha is a middleware pipeline - dispatch, receive, and consumer processing are each a chain you can customize. Mocha compiles these pipelines into an optimized chain with no per-message dictionary lookups or dynamic dispatch at runtime. You can insert your own middleware at any point in the pipeline for cross-cutting concerns like logging, validation, or custom error handling. ## OpenTelemetry-native observability Every message dispatch, receive, and handler execution produces structured traces and metrics through OpenTelemetry. Correlation IDs propagate across service boundaries automatically. ```csharp builder.Services .AddMessageBus() .AddInstrumentation() .AddEventHandler() .AddRabbitMQ(); ``` Connect your services to Nitro to introspect your messaging configuration visually. Here is a real-world example: OrderApi publishes `OrderPlaced`, and the broker fans it out to both BillingService and InventoryService through separate exchanges and queues. The trace shows every hop: Expand the visualization to see the full trace sidebar. Each numbered step - publish, dispatch, receive, consume - is a real OpenTelemetry span. The unnumbered nodes between dispatch and receive are the RabbitMQ exchanges and queues the message passed through. When something goes wrong, this is how you answer "where did the message go?" without digging through logs. ## Resiliency Mocha provides an inbox and outbox to guarantee reliable message processing. The **outbox** ensures that database writes and message dispatches succeed or fail together - no lost messages during failures. The **inbox** ensures that messages are processed exactly once, even when the transport delivers duplicates. Both are optimized for your specific database system. ```csharp builder.Services .AddMessageBus() .AddEventHandler() .AddEntityFramework(p => { p.UsePostgresOutbox(); p.UseTransaction(); p.UsePostgresInbox(); }) .AddRabbitMQ(); ``` ## Saga orchestration Sagas coordinate multi-step workflows that span multiple services and messages. You define a state machine with states and transitions, and Mocha validates the entire state machine - every state must be reachable and every path must lead to a final state. Reducing the possibility of deploying a saga that gets stuck in an intermediate state. Mocha persists saga state, manages transitions, and supports compensation when steps fail. See [Sagas](./sagas.md) for a full walkthrough. ## In-process mediator 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: ```csharp // Define a command and its handler public record PlaceOrderCommand(Guid ProductId, int Quantity) : ICommand; public class PlaceOrderCommandHandler(AppDbContext db) : ICommandHandler { public async ValueTask HandleAsync( PlaceOrderCommand command, CancellationToken cancellationToken) { // business logic return new PlaceOrderResult(true, Guid.NewGuid()); } } ``` ```csharp // Register and use builder.Services .AddMediator() .AddCatalog() .UseEntityFrameworkTransactions(); 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](./mediator/index.md) for the full guide. # Learning paths Choose an entry point based on how you learn best: - **Get something running first:** [Quick Start](./quick-start.md) -zero to a working message bus in under five minutes with the InMemory transport. - **Understand the concepts first:** [Messages](./messages.md) then [Messaging Patterns](./messaging-patterns.md) - learn what flows through the system and what patterns govern how it flows. - **Evaluating Mocha for a specific broker:** [Transports](./transports/index.md) - understand the transport abstraction and what is available. - **In-process CQRS:** [Mediator](./mediator/index.md) - dispatch commands, queries, and notifications within a single service using the source-generated mediator. - **See a real-world system:** The [Demo application](https://github.com/ChilliCream/graphql-platform/tree/main/src/Mocha/examples/Demo) 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](./quick-start.md). --- ### Website Content Docs Nitro Getting Started (`website/content/docs/nitro/getting-started.md`) --- title: "Getting Started" description: "Set up Nitro as a web or desktop app and run your first GraphQL query, from creating a document to connecting to a server and executing operations." --- 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](https://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](/products/nitro). 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](#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](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. 1. **Response Pane:** Here, you will see the output or response of your queries. 1. **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: ```graphql { 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](./explore-the-ui/index.md) guide. Happy querying! --- ### Website Content Docs Nitro Index (`website/content/docs/nitro/index.md`) --- title: Nitro metaTitle: "Nitro: GraphQL IDE, Observability, and Governance" description: "Introduction to Nitro, the GraphQL IDE from ChilliCream with team collaboration, schema and client registries, and OpenTelemetry monitoring for your APIs." --- Nitro combines a collaborative [GraphQL IDE](./explore-the-ui/index.md), [schema and client registries](./apis/overview.md), and [OpenTelemetry monitoring](./open-telemetry/operation-monitoring.md) 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!](./getting-started.md) # 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`) --- title: "Getting Started" description: "Run the `skills` CLI with `dnx` and add your first Agent Skill to Claude Code or another AI coding agent in five minutes using `dnx skills add`." --- 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](https://agentskills.io/home), 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: | Requirement | Why you need it | | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [.NET 10 SDK or newer](https://dotnet.microsoft.com/download) | To run `skills` with `dnx`, the way these docs show it. The `dnx` command ships with the .NET 10 SDK. | | An AI coding agent | The target for your skill. This guide uses [Claude Code](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview). The `skills` CLI supports 55+ agents. | 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](#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 `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. ```shell dnx skills add anthropics/skills --agent claude-code ``` On the first run, `dnx` prompts you to confirm the package download before it proceeds: ```text Tool package skills@ 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](#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`: ```shell dnx --yes skills add anthropics/skills --agent claude-code ``` You can control the `skills` version that `dnx` runs and where it fetches it from: | Command | What it does | | -------------------------------------------- | ----------------------------------- | | `#!shell dnx skills@0.3.0 add ...` | Runs an exact version. | | `#!shell dnx skills@0.3.* add ...` | Runs the latest 0.3.x version. | | `#!shell dnx --prerelease skills add ...` | Allows prerelease versions. | | `#!shell dnx --source skills add ...` | Fetches from a specific NuGet feed. | 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 If you would rather have `skills` on your `PATH`, install it as a global [.NET tool](https://learn.microsoft.com/dotnet/core/tools/global-tools). This needs the .NET SDK 8.0 or newer. ```shell dotnet tool install -g skills ``` ```text 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+` (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: ```shell 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](https://github.com/anthropics/skills), Anthropic's reference repository, targeting Claude Code. ```shell 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: ```text 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 ` (repeatable). For the full set of source forms, scopes, and flags, see [Installing Skills](./installing-skills.md). **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](./troubleshooting.md) for more. # See what is installed To confirm what landed in your project, list the installed skills: ```shell dnx skills list ``` ```text 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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview): 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: ```shell dotnet tool update -g skills ``` ```text Tool 'skills' was successfully updated from version '0.3.0' to version ''. ``` To uninstall it: ```shell dotnet tool uninstall -g skills ``` ```text 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](./installing-skills.md). # Next steps - [Installing Skills](./installing-skills.md): every source form, project versus global scope, picking agents and skills, symlink versus copy, and checking for skill updates. - [Authoring Skills](./authoring-skills.md): scaffold a `SKILL.md` with `dnx skills init`, write a good description, and publish your skill. - [Reference](./reference.md): the complete command and flag surface. --- ### Website Content Docs Skills Index (`website/content/docs/skills/index.md`) --- title: Skills metaTitle: "Skills: Agent Skills CLI for .NET" description: "The `skills` .NET CLI installs, updates, and authors Agent Skills: portable SKILL.md files you can share across Claude Code, Cursor, and 55+ agents." --- `skills` is the .NET CLI that installs, updates, and authors [Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-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: ```shell dnx skills add anthropics/skills --agent claude-code ``` ```text 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](./getting-started.md). The [source repository](https://github.com/ChilliCream/skills) and [`skills` package on NuGet](https://www.nuget.org/packages/skills) 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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) and the [open specification](https://agentskills.io/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. | Level | What loads | When | Token cost | | --------------------- | ----------------------------------------------------- | --------------------------------------- | --------------------- | | Level 1: Metadata | The `name` and `description` from the frontmatter | Always, at startup | ~100 tokens per skill | | Level 2: Instructions | The `SKILL.md` Markdown body | When the skill is triggered | Keep under ~5k tokens | | Level 3: Resources | Bundled files in `references/`, `scripts/`, `assets/` | On demand, when the body points to them | Effectively unlimited | 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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) and the [agentskills.io home page](https://agentskills.io/home). # 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: ```text 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: ```markdown --- 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](./authoring-skills.md) walks through it with the generated `SKILL.md` and folder tree. The full field reference, including optional frontmatter, lives in the [open specification](https://agentskills.io/specification) and in [Authoring Skills](./authoring-skills.md). # 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. | Layer | What it is | Where | | ------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | Format / spec | The open `SKILL.md` standard | [agentskills.io](https://agentskills.io/specification), [anthropics/skills](https://github.com/anthropics/skills) | | Discovery | A directory of published skills to browse | [skills.sh](https://www.skills.sh/) | | Installers | CLIs that fetch and install skills | `skills` (.NET), [npx skills](https://github.com/vercel-labs/skills) (Node) | The `skills` CLI brings the [npx skills](https://github.com/vercel-labs/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](https://www.skills.sh/). # Next steps - [Get started](./getting-started.md): run `skills` and add your first skill end to end. - [Author a skill](./authoring-skills.md): scaffold a `SKILL.md`, write a strong description, and publish it. --- ### Website Content Docs Strawberryshake Index (`website/content/docs/strawberryshake/index.md`) --- title: Strawberry Shake metaTitle: "Strawberry Shake: GraphQL Client for .NET" description: A reactive GraphQL client for .NET. --- 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](../hotchocolate/index.md), [Apollo Server](https://www.apollographql.com/docs/apollo-server), and [GraphQL Java](https://www.graphql-java.com). 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](./get-started/index.md) 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`) --- title: "Type System" description: "Overview of the Hot Chocolate type system: how C# classes map to GraphQL SDL for objects, inputs, enums, interfaces, unions, and scalars in your schema." --- 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: ```graphql 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. | SDL part | Type system member | What it means | Learn more | | --------------------------- | ------------------- | --------------------------------- | --------------------------------------------- | | `Query` | Operation root type | Entry point for read operations. | [Queries](./queries.md) | | `Mutation` | Operation root type | Entry point for write operations. | [Mutations](./mutations.md) | | `bookById` and `createBook` | Fields | Selectable members on a type. | [Object Types](./object-types.md) | | `id` and `input` | Arguments | Values supplied to a field. | [Arguments](./arguments.md) | | `Book` and `Author` | Object types | Returned data shapes. | [Object Types](./object-types.md) | | `CreateBookInput` | Input object type | Structured data sent by a client. | [Input Object Types](./input-object-types.md) | | `ID` and `String` | Scalars | Leaf values with no subfields. | [Scalars](./scalars.md) | | `!` and `[]` | Type modifiers | Non-null and list wrappers. | [Lists and Non-Null](./lists.md) | 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: ```graphql 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 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 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. ```csharp using HotChocolate.Types; public sealed class BookType : ObjectType { protected override void Configure(IObjectTypeDescriptor descriptor) { descriptor .Field(t => t.Title) .Type>() .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 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. | Element | Purpose | Authoring cue | Learn more | | ------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------- | | Query | Read entry point. Query fields should be side-effect-free and may execute in parallel. | `[QueryType]` or `AddQueryType`. | [Queries](./queries.md) | | Mutation | Write entry point. Top-level mutation fields execute serially. | `[MutationType]` or `AddMutationType`. | [Mutations](./mutations.md) | | Subscription | Event stream entry point. | `[SubscriptionType]` or `AddSubscriptionType`. | [Subscriptions](./subscriptions.md) | ## Output Types Output types describe the shapes of data that clients can select after a field resolves. | Element | Use it for | Learn more | | ----------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------- | | Object type | Normal returned data shapes, such as `Book` or `Author`. | [Object Types](./object-types.md) | | Scalar | Leaf values such as `String`, `Int`, `Boolean`, `ID`, `UUID`, `URI`, `DateTime`, `Any`, and custom scalars. | [Scalars](./scalars.md) | | Enum | A closed set of symbolic values in input or output positions. | [Enums](./enums.md) | | Interface | Polymorphic output types that share fields. | [Interfaces](./interfaces.md) | | Union | Polymorphic output types that do not need shared fields. | [Unions](./unions.md) | ## Fields and Arguments 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. | Element | Purpose | Learn more | | -------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | Field | A selectable member on a root type or object type. Root fields start operations. Nested fields shape returned data. | [Queries](./queries.md), [Mutations](./mutations.md), [Object Types](./object-types.md) | | Argument | A value supplied to a field. Common uses include lookup IDs, filters, paging arguments, and mutation payloads. | [Arguments](./arguments.md) | Not every C# method parameter becomes an argument. Service parameters, parent values, cancellation tokens, and resolver context parameters are resolver concerns. ## Input Types Input types define the shapes of data that clients can send to your API, such as arguments and input objects for mutations and queries. | Element | Use it for | Learn more | | ----------------- | --------------------------------------------------------------------------- | --------------------------------------------- | | Argument | A scalar, enum, ID, list, or input object supplied to a field. | [Arguments](./arguments.md) | | Input object type | Structured payloads for mutations, filters, and other complex field inputs. | [Input Object Types](./input-object-types.md) | GraphQL separates input and output type systems. Input objects can use defaults, `Optional`, and `@oneOf`, but those rules are detailed on the input pages. ## Type Modifiers Type modifiers such as non-null and list indicate whether a field or argument is required or can accept multiple values. | Modifier | Example | What it says | Learn more | | ----------------------- | ---------- | ------------------------------------------------------- | -------------------------------- | | Non-null | `String!` | The field or argument must not be null in the contract. | [Lists and Non-Null](./lists.md) | | List | `[Book]` | The value is a collection. | [Lists and Non-Null](./lists.md) | | List plus item non-null | `[Book!]!` | The list is required, and every item is required. | [Lists and Non-Null](./lists.md) | 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 Organize your schema for maintainability and support advanced modeling scenarios using type extensions, Relay helpers, and dynamic schemas. | Topic | Use it for | Learn more | | --------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------- | | Type extensions | Split large object or root type definitions across classes. Extensions are merged into the final schema. | [Object Types](./object-types.md) | | Relay helpers | Use stable IDs, global object identification, `node`, `nodes`, `[ID]`, `[Node]`, and `[NodeResolver]`. | [Relay](./relay.md) | | Dynamic schemas | Generate types from CMS, multi-tenant, or configuration-driven metadata with `ITypeModule`. | [Dynamic Schemas](./dynamic-schemas.md) | ## Contract Metadata and Lifecycle Metadata and lifecycle features help you document, annotate, and evolve your schema safely over time. | Topic | Use it for | Learn more | | ------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------- | | Descriptions | Add schema documentation from XML comments, `[GraphQLDescription]`, or descriptors. | [Documentation Comments](./documentation.md) | | Directives | Add schema metadata or executable behavior, depending on the directive kind. | [Directives](./directives.md) | | Deprecation and evolution | Communicate lifecycle changes and plan compatible schema updates. | [Versioning](./versioning.md) | 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](./queries.md). - Learn how returned shapes are inferred and configured in [Object Types](./object-types.md). - Add field inputs with [Arguments](./arguments.md) and [Input Object Types](./input-object-types.md). - Strengthen the contract with [Lists and Non-Null](./lists.md). - Move to runtime behavior with [Resolvers](../resolvers/index.md) and [DataLoader](../fetching-data/batching/dataloader.md) after the schema shape is clear. --- ### Website Content Docs Hotchocolate Fetching Data Index (`website/content/docs/hotchocolate/fetching-data/index.md`) --- title: Fetching Data description: "Overview of data middleware in Hot Chocolate: pagination, filtering, sorting, projections, and DataLoader batching applied to IQueryable data sources." --- 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](https://relay.dev/graphql/connections.htm), 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](./pagination.md) # 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](./filtering.md) # 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](./sorting.md) # 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](./projections.md) # 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](./batching/dataloader.md) for key-based batching with deduplication and caching. - [Batch Resolvers](./batching/batch-resolver.md) 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](./integrations/entity-framework.md) for EF Core DbContext patterns and pooling. - [MongoDB](./integrations/mongodb.md) for the MongoDB driver integration. - [Marten](./integrations/marten.md) for Marten document database support. - [Extending Filtering](./integrations/extending-filtering.md) for building custom filter providers. --- ### Website Content Docs Hotchocolate Performance Index (`website/content/docs/hotchocolate/performance/index.md`) --- title: Performance description: "Overview of Hot Chocolate performance features: faster startup, trusted documents, and persisted operations that cut parsing and validation overhead per request." --- 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](../server/warmup.md) # 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 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](https://relay.dev/docs/guides/persisted-queries/), and [Apollo](https://www.apollographql.com/docs/react/api/link/persisted-queries/) client all support this approach. [Learn more about persisted operations](./trusted-documents.md) ## Automatic Persisted Operations 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](https://www.apollographql.com/docs/apollo-server/performance/apq/) client support this approach. [Learn more about automatic persisted operations](./automatic-persisted-operations.md) --- ### Website Content Docs Hotchocolate Resolvers Index (`website/content/docs/hotchocolate/resolvers/index.md`) --- title: Resolvers metaTitle: "GraphQL Resolvers in Hot Chocolate" description: "Introduction to resolvers in Hot Chocolate: how the resolver tree executes a query, defining resolver methods, accessing arguments, and injecting services." --- 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: ```graphql query { me { name company { id name } } } ``` This produces the following resolver tree: ```mermaid 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. In the implementation-first approach, a public method is automatically inferred as a resolver. This means the method defines both the field in your schema and the logic to resolve its value. ```csharp [QueryType] public partial class Query { public static string Foo() => "Bar"; } ``` This generates the following schema: ```sdl type Query { foo: String! } ``` Resolvers do not have to be methods. Public properties are also inferred as resolvers and exposed as fields in your schema. ```csharp [QueryType] public partial class Query { public static User User => new User("Ted"); } public record User(string Name); ``` In this case, the property `Name` of the `User` object is also inferred as a resolver. In the code-first approach, you define a resolver by assigning a resolver delegate to a field. This delegate contains the logic for resolving the field's value. ```csharp public class QueryType : ObjectType { protected override void Configure(IObjectTypeDescriptor descriptor) { descriptor .Field("foo") .Type>() .Resolve(ctx => "bar"); } } ``` You can also use `ObjectType` with a backing POCO. Public methods and properties on the POCO are bound as fields automatically. Use the `Field` method with a lambda expression to configure individual fields. ```csharp public class Query { public string Foo() => "Bar"; } public class QueryType : ObjectType { protected override void Configure(IObjectTypeDescriptor descriptor) { descriptor .Field(f => f.Foo()) .Type>(); } } ``` ## Async Resolver 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. When using the implementation-first approach, you can add a `CancellationToken` parameter to your resolver method. The execution engine will automatically inject the request's cancellation token. ```csharp public class Query { public async Task GetProductByIdAsync( int id, ProductService productService, CancellationToken cancellationToken) => await productService.GetAsync(cancellationToken); } ``` When using the code-first approach, you can access the `CancellationToken` through the `IResolverContext` provided to your resolver. ```csharp 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. When using the implementation-first approach, any parameter in your resolver method that is not a service, a `CancellationToken`, or specially annotated is treated as a GraphQL argument. The execution engine will inject the argument value from the query into these parameters. For example, in the method below, the `id` parameter is recognized as an argument, while `ProductService` is injected as a service from the DI container. ```csharp public class Query { public async Task GetProductByIdAsync( int id, ProductService productService, CancellationToken cancellationToken) => await productService.GetAsync(cancellationToken); } ``` When using the code-first approach, you can access field arguments using the resolver context. ```csharp descriptor .Field("foo") .Argument("id", a => a.Type>()) .Resolve(context => { var id = context.ArgumentValue("id"); // Omitted code for brevity }); ``` [Learn more about arguments](../defining-a-schema/arguments.md) # Injecting Services Hot Chocolate automatically recognizes types registered in the DI container and injects them into resolver parameters. ```csharp public class Query { public List GetUsers(UserService userService) => userService.GetUsers(); } ``` While you can take attributes to annotate services, you do not have to for non-keyed services. ```csharp public class Query { public List GetUsers([Service] UserService userService) => userService.GetUsers(); } ``` [Learn more about dependency injection](./dependency-injection.md) # Accessing parent values Each field resolver has access to the value that was resolved for its parent type. For example, consider the following schema: ```sdl 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. ```csharp 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: In the implementation-first approach, the parent object can be injected as a resolver parameter: ```csharp [ObjectType] public static partial class UserNode { public static Task> GetFriendsAsync( [Parent] User user, UserService userService, CancellationToken cancellationToken) { // Omitted code for brevity } } ``` If database projections are enabled, the parent object may only contain the fields requested by the client. To ensure the projections engine also loads properties required by the resolver, declare those requirements on the parent parameter: ```csharp [ObjectType] public static partial class UserNode { public static Task> GetFriendsAsync( [Parent(requires: nameof(User.Id))] User user, UserService userService, CancellationToken cancellationToken) { // Omitted code for brevity } } ``` Use `nameof` to make this requirement refactoring-safe. In the code-first approach, the parent object is available via the `IResolverContext`. ```csharp public class User { public string Id { get; set; } } public class UserType : ObjectType { protected override void Configure(IObjectTypeDescriptor descriptor) { descriptor .Field("friends") .Resolve(context => { User parent = context.Parent(); // Omitted code for brevity }); } } ``` # What's in This Section - [Dependency Injection](./dependency-injection.md) explains how services are injected into resolvers, scoping behavior, keyed services, and switching the service provider. - [Errors](./errors.md) covers how exceptions become GraphQL errors, error filters for mapping domain exceptions, and throwing `GraphQLException` for explicit errors. - [Field Middleware](./field-middleware.md) 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`) --- title: Securing Your API description: "Overview of securing a Hot Chocolate GraphQL API: cost analysis for public APIs, trusted documents for private ones, plus authorization and request limits." --- 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](./cost-analysis.md) # 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](../performance/trusted-documents.md) # Defense in Depth Regardless of whether your API is public or private, apply these additional protections: ## Authentication 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](./authentication.md) ## Authorization 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](./authorization.md) ## Request Limits 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](./request-limits.md) ## Introspection Introspection powers developer tools but can also reveal your schema to attackers. You can restrict or disable introspection in production. [Learn more about introspection](./introspection.md#disabling-introspection) ## FIPS Compliance Hot Chocolate uses MD5 for document hashing by default. If you need FIPS compliance, switch to SHA256: ```csharp builder .AddGraphQL() .AddSha256DocumentHashProvider(); ``` [Learn more about hashing providers](../performance/trusted-documents.md#hashing-algorithms) # Next Steps - **Building a public API?** Start with [Cost Analysis](./cost-analysis.md). - **Building a private API?** Start with [Trusted Documents](../performance/trusted-documents.md). - **Need authentication?** See [Authentication](./authentication.md). - **Need authorization?** See [Authorization](./authorization.md). --- ### Website Content Docs Hotchocolate Server Index (`website/content/docs/hotchocolate/server/index.md`) --- title: Server description: "Overview of configuring and operating a Hot Chocolate GraphQL server: endpoints, HTTP transport, interceptors, dependency injection, and instrumentation." --- 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](/products/nitro) GraphQL IDE. [Learn more about endpoints](./endpoints.md) # 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](./http-transport.md) # 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](./cache-control.md) # 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](./interceptors.md) # 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](../resolvers/dependency-injection.md) # 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](./warmup.md) # 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](./global-state.md) # 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](../security/introspection.md) # 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](./files.md) # 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](./instrumentation.md) # 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](./batching.md) # 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](./command-line.md) --- ### Website Content Docs Mocha Mediator Index (`website/content/docs/mocha/mediator/index.md`) --- title: Mediator description: "Use the Mocha Mediator to dispatch commands, queries, and notifications within a single process using zero-reflection, source-generated dispatch." --- ```csharp 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. ```csharp // 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](https://refactoring.guru/design-patterns/mediator) -- objects communicate through a central hub instead of referencing each other directly. If you have used [MediatR](https://github.com/jbogard/MediatR), the concepts are familiar. Mocha Mediator takes a different approach to performance: a [Roslyn source generator](https://learn.microsoft.com/en-us/dotnet/csharp/roslyn-sdk/source-generators-overview) 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: | Use the **mediator** when... | Use the **message bus** when... | | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | Dispatch stays in-process | Messages cross process or service boundaries | | You want [CQRS](https://learn.microsoft.com/en-us/azure/architecture/patterns/cqrs) separation of commands and queries | You want pub/sub events across services | | You need a request/response pipeline with middleware | You need transport-level features (retries, outbox) | | Handlers live in the same assembly or solution | Handlers live in different services | 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 Commands represent actions that change state. Use imperative verb-noun naming: `PlaceOrder`, `ProcessPayment`. ```csharp // 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; public record PlaceOrderResult(bool Success, Guid? OrderId = null, string? Error = null); ``` ## Queries Queries represent read operations that return data without side effects. Use noun-based naming: `GetProducts`, `GetOrderById`. ```csharp public record GetProductsQuery : IQuery>; public record GetProductByIdQuery(Guid Id) : IQuery; ``` ## Notifications Notifications represent events that multiple handlers can observe. Use past-tense naming: `OrderPlaced`, `PaymentCompleted`. ```csharp public record OrderPlacedNotification( Guid OrderId, decimal Amount) : INotification; ``` ## Message type reference | Interface | Purpose | Dispatch method | Return type | | --------------------- | -------------------- | --------------- | ---------------------- | | `ICommand` | Action, no response | `SendAsync` | `ValueTask` | | `ICommand` | Action with response | `SendAsync` | `ValueTask` | | `IQuery` | Read operation | `QueryAsync` | `ValueTask` | | `INotification` | Multi-handler event | `PublishAsync` | `ValueTask` | # 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 ```csharp // Handles a void command public sealed class DeleteOrderCommandHandler(AppDbContext db) : ICommandHandler { 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 { public async ValueTask 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 ```csharp public sealed class GetProductsQueryHandler(AppDbContext db) : IQueryHandler> { public async ValueTask> HandleAsync( GetProductsQuery query, CancellationToken cancellationToken) => await db.Products.ToListAsync(cancellationToken); } ``` ## Notification handlers Multiple handlers can subscribe to the same notification type. The mediator invokes all of them. ```csharp public sealed class SendOrderConfirmationEmail(IEmailService email) : INotificationHandler { public async ValueTask HandleAsync( OrderPlacedNotification notification, CancellationToken cancellationToken) { await email.SendAsync( $"Order {notification.OrderId} confirmed", cancellationToken); } } public sealed class UpdateAnalyticsDashboard(IAnalytics analytics) : INotificationHandler { public async ValueTask HandleAsync( OrderPlacedNotification notification, CancellationToken cancellationToken) { await analytics.RecordOrderAsync( notification.OrderId, notification.Amount); } } ``` ## Handler interface reference | Interface | Message type | Response | | -------------------------------------- | --------------------- | ----------- | | `ICommandHandler` | `ICommand` | void | | `ICommandHandler` | `ICommand` | `TResponse` | | `IQueryHandler` | `IQuery` | `TResponse` | | `INotificationHandler` | `INotification` | void | # Dispatching messages Inject `IMediator`, `ISender`, or `IPublisher` from DI and call the appropriate method. ```csharp // 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 When the message type is not known at compile time, use the `object`-based overloads: ```csharp // 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 ```csharp 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 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: ```csharp using Mocha.Mediator; [assembly: MediatorModule("Billing")] ``` ## Manual handler registration with AddHandler 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()`: ```csharp builder.Services .AddMediator() .AddHandler() .AddHandler() .AddHandler(); ``` `AddHandler()` 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: ```csharp builder.Services .AddMediator() .AddCatalog() // source-generated handlers .AddHandler(); // 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 By default, handlers are registered as `Scoped`. To change the default: ```csharp 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 | Option | Type | Default | Description | | ------------------------- | ------------------------- | ------------ | --------------------------------------------- | | `ServiceLifetime` | `ServiceLifetime` | `Scoped` | Default DI lifetime for handler registrations | | `NotificationPublishMode` | `NotificationPublishMode` | `Sequential` | How notification handlers are dispatched | # 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](https://learn.microsoft.com/en-us/dotnet/core/extensions/dependency-injection#keyed-services). ```csharp // Register a named mediator builder.Services .AddMediator("billing") .AddBilling(); // Register the default (unnamed) mediator builder.Services .AddMediator() .AddCatalog(); ``` Resolve a named mediator from DI: ```csharp 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("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` The source generator did not find a handler for your message type. Verify: - Your handler class implements the correct interface (e.g., `ICommandHandler`) - Your message type implements the correct marker interface (e.g., `ICommand`) - 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 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 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()` The type you passed does not implement any handler interface. Make sure `T` implements one of: `ICommandHandler`, `ICommandHandler`, `IQueryHandler`, or `INotificationHandler`. ## Named mediator returns wrong handlers 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](./pipeline-and-middleware.md) - 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`) --- title: "Transports" description: "Understand how transports move messages in Mocha, how the transport abstraction works, and how to choose between InMemory, PostgreSQL, RabbitMQ, and Azure Service Bus." --- 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](https://www.enterpriseintegrationpatterns.com/patterns/messaging/MessageChannel.html) pattern: the sender and receiver are decoupled from the physical infrastructure that carries the message. Mocha ships with four transports: | Transport | Package | Use case | | --------------------- | --------------------------------- | ------------------------------------------------------------ | | **InMemory** | `Mocha.Transport.InMemory` | Development, testing, single-process scenarios | | **PostgreSQL** | `Mocha.Transport.Postgres` | Database-backed messaging when you already operate Postgres | | **RabbitMQ** | `Mocha.Transport.RabbitMQ` | Production, distributed systems, multi-service architectures | | **Azure Service Bus** | `Mocha.Transport.AzureServiceBus` | Managed cloud messaging on Azure | # Add a transport Every transport implements the same `MessagingTransport` base class. The transport is always the last call in the builder chain: ```csharp // InMemory - zero configuration builder.Services .AddMessageBus() .AddEventHandler() .AddInMemory(); ``` ```csharp // RabbitMQ - production-ready builder.Services .AddMessageBus() .AddEventHandler() .AddRabbitMQ(); ``` ```csharp // PostgreSQL - database-backed transport builder.Services .AddMessageBus() .AddEventHandler() .AddPostgres("Host=localhost;Database=mocha_messaging;Username=postgres;Password=postgres"); ``` ```csharp // Azure Service Bus - managed cloud messaging builder.Services .AddMessageBus() .AddEventHandler() .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: | Criterion | InMemory | PostgreSQL | RabbitMQ | Azure Service Bus | | ------------------ | ------------------------------------------- | ------------------------------------------- | ------------------------------------------- | ------------------------------------- | | Setup effort | None, zero dependencies | Requires a PostgreSQL database | Requires a running broker | Azure subscription and namespace | | Message durability | **Messages lost on process exit** | Messages are stored in database tables | Messages survive broker restarts | Durable, broker-managed | | Multi-process | **Single process only** | Multiple services sharing the same database | Multiple services, multiple instances | Multiple services, multiple instances | | Request/reply | Supported | Supported | Supported | Supported | | Native scheduling | Yes, built-in and cancellable (non-durable) | Yes, built-in and cancellable | None, requires `UsePostgresScheduling()` | Yes, durable and cancellable | | Operational cost | None | Database capacity, migrations, monitoring | Broker infrastructure, monitoring, upgrades | Pay-per-use Azure resource | | Network latency | None, in-process | Database round trip | Broker round trip | Cloud network round trip | **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. ```text Bus scope (global defaults) └── Transport scope (transport-specific overrides) └── Endpoint scope (endpoint-specific overrides) ``` To add middleware at the transport level: ```csharp 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. ```csharp builder.Services .AddMessageBus() .AddEventHandler() .AddRabbitMQ(transport => { transport.BindExplicitly(); transport.Queue("order-processing") .BindImplicitly() .Handler(); }); ``` Calling `Queue("name")` without a handler, consumer, or `Receives()` 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: ```csharp builder.Services .AddMessageBus() .AddEventHandler() .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: ```csharp builder.Services .AddMessageBus() .AddEventHandler() .AddRabbitMQ(transport => { transport.BindExplicitly(); transport.Queue("order-events") .BindImplicitly() .Handler(); }); ``` 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()` 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()`: ```csharp builder.Services .AddMessageBus() .AddEventHandler() .AddRabbitMQ(transport => { transport.Handler() .ConfigureEndpoint(e => e.MaxPrefetch(50).MaxConcurrency(10)); }); ``` The handler still gets a convention-named endpoint - `Handler()` 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()`: ```csharp transport.Consumer() .ConfigureEndpoint(e => e.MaxConcurrency(3)); ``` `Handler()` and `Consumer()` 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: ```csharp builder.Services .AddMessageBus() .AddEventHandler() .AddEventHandler() .AddRabbitMQ(r => r.IsDefaultTransport()) // default for unclaimed handlers .AddInMemory(m => m.Handler()); // AuditHandler claimed by InMemory // OrderPlacedEventHandler → RabbitMQ (default, implicit) // AuditHandler → InMemory (claimed) ``` You can also use the queue descriptor with explicit binding: ```csharp builder.Services .AddMessageBus() .AddEventHandler() .AddEventHandler() // Default transport for most messages .AddRabbitMQ() // High-throughput transport for click-stream data .AddInMemory(transport => { transport.BindExplicitly(); transport.Queue("click-stream") .BindImplicitly() .Handler(); }); ``` 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](./in-memory.md) - Set up the InMemory transport for development and testing. - [PostgreSQL Transport](./postgres.md) - Configure database-backed messaging with PostgreSQL. - [RabbitMQ Transport](./rabbitmq.md) - Configure the RabbitMQ transport for production deployments. - [Azure Service Bus Transport](./azure-service-bus.md) - Configure managed cloud messaging on Azure. > **Runnable example:** [MultiTransport](https://github.com/ChilliCream/graphql-platform/tree/main/src/Mocha/src/Examples/Transports/MultiTransport) --- ### Website Content Docs Nitro Apis Overview (`website/content/docs/nitro/apis/overview.md`) --- title: APIs description: "APIs in Nitro represent your GraphQL servers and group documents, settings, registries, and telemetry. Compare Collection, Service, and Gateway API types." --- 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](./schema-registry.md) guide the [Client Registry](./client-registry.md) and the [Telemetry](../open-telemetry/operation-monitoring.md) guide. # API Types ## API Collection A compilation of GraphQL Documents with shared connection settings, enabling the grouping of documents for sharing with your team. ## API Service 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 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`) --- title: Documents description: "Tour of the Document View in Nitro, the workspace for running GraphQL queries, mutations, and subscriptions and exploring the schema reference and SDL." --- 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](./schema-reference.md) 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](./schema-definition.md) 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](./operations.md) 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](./response.md) 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](./connection-settings.md) guide for detailed information about it. You can also configure the authentication settings for the document. Refer to the [Authentication Settings](./authentication.md) guide for more details. --- ### Website Content Docs Nitro Explore The Ui Index (`website/content/docs/nitro/explore-the-ui/index.md`) --- title: Explore the UI description: "Overview of the Nitro user interface: sidebar, document tree, main area, environments, history, settings, and the status bar, with links to detailed guides." --- 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](../documents/index.md). 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](../settings/index.md). 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](../organizations/index.md). 6. **Document Tree**: Here you can manage files, folders, documents, and APIs. Read more about it in the [Explorer](./explorer.md). 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](./status-bar.md). --- ### Website Content Docs Nitro Organizations Index (`website/content/docs/nitro/organizations/index.md`) --- title: "Organizations" description: "Create and manage organizations in Nitro, the structure that hosts your workspaces and members, including the personal organization and management portal." --- 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](https://identity.chillicream.com/Organizations) 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 Invited users can join an organization in two ways: 1. By clicking on the join link they received via email. 1. 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: | Role | Transfer Ownership | Delete Organization | Invite Users | View Subscriptions | Add Redirect URLs | | ------------ | ------------------ | ------------------- | ------------ | ------------------ | ----------------- | | Owner | Yes | Yes | Yes | Yes | Yes | | Admin | No | No | Yes | Yes | Yes | | Collaborator | No | No | No | No | No | - **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 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](https://nitro.chillicream.com) 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`) --- title: Settings - Overview description: "Overview of the Settings section in Nitro, reached via the cog icon, covering customization options like Themes and where to find organization settings." --- 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](./themes.md) 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](../organizations/index.md) documentation. --- ### Website Content Docs Strawberryshake Caching Index (`website/content/docs/strawberryshake/caching/index.md`) --- title: "Caching" description: "Strawberry Shake caches GraphQL results in a normalized entity store, reducing network requests and keeping reactive components in sync with state." --- > 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. ```mermaid 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 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 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 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 The global strategy default can be set on our dependency injection setup method. ```csharp 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. ```csharp 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`) --- title: "Get started with Strawberry Shake and Blazor" description: "Add a Strawberry Shake GraphQL client to a Blazor WebAssembly app: generate typed C# clients from GraphQL queries and build reactive components." --- 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](https://www.youtube.com/watch?v=-oq7YEciouM) > 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. ```shell dotnet new tool-manifest ``` 2. Install the Strawberry Shake tools. ```shell 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`. ```shell dotnet new sln --name Demo ``` 2. Create a new Blazor for WebAssembly application. ```shell dotnet new blazorwasm --name Demo ``` 3. Add the project to the solution `Demo.sln`. ```shell 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. ```shell 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](https://demo.chillicream.com/graphql). 1. Add the crypto client to your Blazor application. ```shell 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. ```json { "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: ```shell code ./Demo ``` 4. Create new query document `GetSessions.graphql` with the following content: ```graphql 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. ```shell 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. ```csharp using Microsoft.AspNetCore.Components.Web; using Microsoft.AspNetCore.Components.WebAssembly.Hosting; using Demo; var builder = WebAssemblyHostBuilder.CreateDefault(args); builder.RootComponents.Add("#app"); builder.RootComponents.Add("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 ```csharp @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 "/"` ```csharp @page "/" ``` 3. Add the `UseGetAssets` component to your page. ```csharp @page "/" Something went wrong ...
@result.First().Message Loading ... ``` > 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. ```csharp @page "/"
    @foreach (var item in result.Assets!.Nodes!) {
  • @item.Name (@item.Price.LastPrice)
    • }
Something went wrong ...
@result.First().Message Loading ... ``` 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`) --- title: "Networking" description: "Strawberry Shake networking: HTTP, WebSocket, SignalR, gRPC, and in-memory transport packages, plus transport profiles to pick a protocol per operation." --- 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 | Protocol | Package | Strawberry Shake Version | | --------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------ | | HTTP | [GraphQL over HTTP](https://github.com/michaelstaib/graphql-over-http) | [StrawberryShake.Transport.Http](https://www.nuget.org/packages/StrawberryShake.Transport.Http) | 11.1 | | WebSocket | [subscriptions-transport-ws](https://github.com/apollographql/subscriptions-transport-ws/blob/master/PROTOCOL.md) | [StrawberryShake.Transport.WebSockets](https://www.nuget.org/packages/StrawberryShake.Transport.WebSockets) | 11.1 | | WebSocket | [graphql-transport-ws](https://github.com/graphql/graphql-over-http/pull/140) | StrawberryShake.Transport.WebSockets | 12.0 | | SignalR | GraphQL over SignalR | StrawberryShake.Transport.SignalR | 12.0 | | gRPC | GraphQL over gRPC | StrawberryShake.Transport.gRPC | 12.0 | | InMemory | Hot Chocolate In-Memory | [StrawberryShake.Transport.InMemory](https://www.nuget.org/packages/StrawberryShake.Transport.InMemory) | 11.1 | # 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`. ```json { "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. ```csharp 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`) --- title: "Performance" description: "Optimize Strawberry Shake client performance with persisted operations and persisted state, cutting request size and network round trips for your app." --- 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 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](./persisted-operations.md). ## Automatic persisted operations 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](../caching/index.md). 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](./persisted-state.md). --- ### Website Content Docs Hotchocolate Fetching Data Batching Index (`website/content/docs/hotchocolate/fetching-data/batching/index.md`) --- title: "Batching" metaTitle: "GraphQL Batching in Hot Chocolate: Solve the N+1 Problem" description: "Learn how batching solves the N+1 problem in GraphQL. Hot Chocolate offers DataLoader and batch resolvers to group data fetches into single calls." --- 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](./dataloader.md) and [batch resolvers](./batch-resolver.md). > [!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](../../server/batching.md). # 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](../../resolvers/index.md), and the execution engine walks the query as a tree. Consider this query: **Client query** ```graphql { 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: ```text 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](./dataloader.md) # 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](./batch-resolver.md) # Next Steps - **Loading data by key?** Start with [DataLoader](./dataloader.md). - **Resolving one field for many parents?** See [Batch Resolvers](./batch-resolver.md). - **New to resolvers?** See [Resolvers](../../resolvers/index.md) for the resolver tree mental model. - **Using Entity Framework?** See [Entity Framework](../integrations/entity-framework.md) for integration patterns. - **Looking for HTTP request batching?** See [Server Batching](../../server/batching.md). --- ### Website Content Docs Hotchocolate Fetching Data Integrations Index (`website/content/docs/hotchocolate/fetching-data/integrations/index.md`) --- title: Integrations description: Learn how to use the IExecutable interface to abstract data sources in Hot Chocolate. --- The `IExecutable` and `IExecutable` 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` is recognized as a list. ```csharp public class User { public string Name { get; } } public interface IUserRepository { public IExecutable FindAll(); } public class Query { public IExecutable GetUsers(IUserRepository repo) => repo.FindAll(); } ``` ```sdl 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 ```csharp 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` or `IAggregateFluent`. `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 ```csharp ValueTask ToListAsync(CancellationToken cancellationToken); ``` Returns a list of items. ## FirstOrDefaultAsync ```csharp ValueTask FirstOrDefaultAsync(CancellationToken cancellationToken); ``` Returns the first element of the sequence, or a default value if the sequence contains no elements. ## SingleOrDefaultAsync ```csharp ValueTask 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 ```csharp 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: ```csharp public class EntityFrameworkExecutable : QueryableExecutable { public IQueryable Source { get; } object IExecutable.Source => Source; public EntityFrameworkExecutable(IQueryable queryable) : base(queryable) { } public QueryableExecutable WithSource(IQueryable source) { return new QueryableExecutable(source); } public override async ValueTask ToListAsync( CancellationToken cancellationToken) => await Source.ToListAsync(cancellationToken).ConfigureAwait(false); public override async ValueTask FirstOrDefaultAsync( CancellationToken cancellationToken) => await Source.FirstOrDefaultAsync(cancellationToken).ConfigureAwait(false); public override async ValueTask SingleOrDefaultAsync( CancellationToken cancellationToken) => await Source.SingleOrDefaultAsync(cancellationToken).ConfigureAwait(false); public override string Print() => Source.ToQueryString(); } ``` # Next Steps - [Entity Framework integration](./entity-framework.md) for EF Core executables - [MongoDB integration](./mongodb.md) for MongoDB executables - [Filtering](../filtering.md) for applying filters to executables --- ### Profiling (`docs/profiling.md`) # 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 The dev container installs these tools, pinned in `.devcontainer/dockerfile`: | Tool | Version | Location | | ---------------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------- | | `dotnet-trace`, `dotnet-counters`, `dotnet-gcdump`, `dotnet-dump`, `dotnet-symbol` | 10.0.750501 | `~/.dotnet/tools`, dotnet global tools | | `dottrace` | 2026.2.3.1 | `~/.dotnet/tools`, dotnet global tool `JetBrains.dotTrace.GlobalTools` | | `dotmemory` | 2026.2.3.1 | `/opt/dotmemory` with the launcher in `/usr/local/bin`, unpacked from `JetBrains.dotMemory.Console.` | `~/.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 Write everything to `perf/