graphql
/graphql
USE FOR: Building GraphQL APIs in .NET using Hot Chocolate. Use when clients need flexible query capabilities, field selection, and efficient data fetching across related entities without over-fetching or under-fetching. DO NOT USE FOR: Simple CRUD APIs with fixed response shapes (use REST with minimal APIs), file upload/download endpoints (use REST), or real-time bidirectional communication (use SignalR, though GraphQL subscriptions can complement it).
- Author
- Tyler-R-Kendrick ↗
- Repository
- agent-skills ↗
- Licence
- MIT
- Last repository change
- 09.06.2026
Assessment and security
- Files in this package
- 21
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 3
No signals detected. Repository changed on 09.06.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
USE FOR: Building GraphQL APIs in .NET using Hot Chocolate. Use when clients need flexible query capabilities, field selection, and efficient data fetching across related entities without over-fetching or under-fetching. DO NOT USE FOR: Simple CRUD APIs with fixed response shapes (use REST with minimal APIs), file upload/download endpoints (use REST), or real-time bidirectional communication (use SignalR, though GraphQL subscriptions can complement it).
Original author description
USE FOR: Building GraphQL APIs in .NET using Hot Chocolate. Use when clients need flexible query capabilities, field selection, and efficient data fetching across related entities without over-fetching or under-fetching. DO NOT USE FOR: Simple CRUD APIs with fixed response shapes (use REST with minimal APIs), file upload/download endpoints (use REST), or real-time bidirectional communication (use SignalR, though GraphQL subscriptions can complement it).
How it works
- Overview
- Server Setup
- Query Type with Filtering, Sorting, and Pagination
- Mutation Type
- DataLoader for N+1 Prevention
- GraphQL vs REST Comparison
- Best Practices
SKILL.md preview
---
name: graphql
description: |
USE FOR: Building GraphQL APIs in .NET using Hot Chocolate. Use when clients need flexible query capabilities, field selection, and efficient data fetching across related entities without over-fetching or under-fetching.
DO NOT USE FOR: Simple CRUD APIs with fixed response shapes (use REST with minimal APIs), file upload/download endpoints (use REST), or real-time bidirectional communication (use SignalR, though GraphQL subscriptions can complement it).
license: MIT
metadata:
displayName: GraphQL (Hot Chocolate)
author: "Tyler-R-Kendrick"
version: "1.0.0"
compatibility:
- claude
- copilot
- cursor
references:
- title: "Hot Chocolate Documentation"
url: "https://chillicream.com/docs/hotchocolate/v13/"
- title: "Hot Chocolate GitHub Repository"
url: "https://github.com/ChilliCream/graphql-platform"
- title: "HotChocolate.AspNetCore NuGet Package"
url: "https://www.nuget.org/packages/HotChocolate.AspNetCore"
---
# GraphQL (Hot Chocolate)
## Overview
Hot Chocolate is the most popular GraphQL server library for .NET. It enables building type-safe GraphQL APIs with support for queries, mutations, subscriptions, filtering, sorting, pagination, data loaders (for N+1 prevention), and schema stitching. Hot Chocolate integrates with ASP.NET Core, Entity Framework Core, and the standard .NET dependency injection system. It supports both code-first and schema-first approaches and generates a fully introspectable GraphQL schema.
## Server Setup
Configure Hot Chocolate in an ASP.NET Core application.
```csharp
using Microsoft.EntityFrameworkCore;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<AppDbContext>(options =>
options.UseSqlServer(builder.Configuration.GetConnectionString("Default")));
builder.Services
.AddGraphQLServer()
.AddQueryType<Query>()
.AddMutationType<Mutation>()
.AddSubscriptionType<Subscription>()
.AddFiltering()
.AddSorting()
.AddProjections()
.AddInMemorySubscriptions();
var app = builder.Build();
app.UseWebSockets();
app.MapGraphQL();
app.Run();
```
## Query Type with Filtering, Sorting, and Pagination
Define queries that expose data with built-in filtering and cursor-based pagination.
```csharp
using HotChocolate;
using HotChocolate.Data;
using HotChocolate.Types;
using Microsoft.EntityFrameworkCore;
namespace MyApp.GraphQL;
public class Query
{
[UsePaging(IncludeTotalCount = true)]
[UseProjection]
[UseFiltering]
[UseSorting]
public IQueryable<Product> GetProducts(AppDbContext context)
=> context.Products.AsNoTracking();
public async Task<Product?> GetProductById(
int id,
AppDbContext context)
=> await context.Products
.Include(p => p.Category)
.FirstOrDefaultAsync(p => p.Id == id);
[UseFiltering]
[UseSorting]
public IQueryable<Customer> GetCustomers(AppDbContext context)
=> context.Customers.AsNoTracking();
}
```
## Mutation Type
Define mutations for data modification operations.
```csharp
using HotChocolate;
using HotChocolate.Types;
namespace MyApp.GraphQL;
public class Mutation
{
public async Task<CreateProductPayload> CreateProduct(
CreateProductInput input,
AppDbContext context)
{
var product = new Product
{
Name = input.Name,
Price = input.Price,
CategoryId = input.CategoryId,
Description = input.Description
};
context.Products.Add(product);
await context.SaveChangesAsync();
return new CreateProductPayload(product);
}
public async Task<UpdateProductPayload> UpdateProduct(
int id,
UpdateProductInput input,
AppDbContext context)
{
var product = await context.Products.FindAsync(id);
if (product is null)
{
return new UpdateProductPayload(
product: null,
error: new UserError("Product not found.", "PRODUCT_NOT_FOUND"));
}
if (input.Name is not null) product.Name = input.Name;
if (input.Price.HasValue) product.Price = input.Price.Value;
if (input.Description is not null) product.Description = input.Description;
await context.SaveChangesAsync();
return new UpdateProductPayload(product, error: null);
}
public async Task<bool> DeleteProduct(int id, AppDbContext context)
{
var product = await context.Products.FindAsync(id);
if (product is null) return false;
context.Products.Remove(product);
await context.SaveChangesAsync();
return true;
}
}
// Input and Payload types
public record CreateProductInput(string Name, decimal Price, int CategoryId, string? Description);
public record UpdateProductInput(string? Name, decimal? Price, string? Description);
public record CreateProductPayload(Product Product);
public record UpdateProductPayload(Product? Product, UserError? Error);
public record UserError(string Message, string Code);
```
## DataLoader for N+1 Prevention
Use DataLoaders to batch database queries and prevent the N+1 query problem.
```csharp
using GreenDonut;
using HotChocolate;
using Microsoft.EntityFrameworkCore;
namespace MyApp.GraphQL;
public class CategoryBatchDataLoader : BatchDataLoader<int, Category>
{
private readonly IDbContextFactory<AppDbContext> _contextFactory;
public CategoryBatchDataLoader(
IDbContextFactory<AppDbContext> contextFactory,
IBatchScheduler batchScheduler,
DataLoaderOptions? options = null)
: base(batchScheduler, options)
{
_contextFactory = contextFactory;
}
protected override async Task<IReadOnlyDictionary<int, Category>> LoadBatchAsync(
IReadOnlyList<int> keys,
CancellationToken cancellationToken)
{
await using var context = await _contextFactory.CreateDbContextAsync(cancellationToken);
return await context.Categories
.Where(c => keys.Contains(c.Id))
.ToDictionaryAsync(c => c.Id, cancellationToken);
}
}
// Usage in a type extension
[ExtendObjectType(typeof(Product))]
public class ProductExtensions
{
public async Task<Category?> GetCategory(
[Parent] Product product,
CategoryBatchDataLoader loader)
=> await loader.LoadAsync(product.CategoryId);
}
```
## GraphQL vs REST Comparison
| Feature | GraphQL (Hot Chocolate) | REST (ASP.NET Core) |
|---|---|---|
| Data fetching | Client specifies fields | Server defines response shape |
| Over-fetching | Eliminated | Common |
| Under-fetching | Eliminated | Requires multiple calls |
| Versioning | Schema evolution | URL or header versioning |
| Caching | Per-field, complex | HTTP caching, simple |
| File upload | Multipart spec (complex) | Native support |
| Real-time | Subscriptions (WebSocket) | SignalR / SSE |
| Tooling | GraphQL Playground, Banana Cake Pop | Swagger, Postman |
## Best Practices
1. **Use `[UseProjection]` on every query that returns `IQueryable<T>`** so that Hot Chocolate generates SQL `SELECT` statements containing only the fields requested by the client, preventing full-table reads when the client queries only `id` and `name` from an entity with 20 columns.
2. **Implement `BatchDataLoader<TKey, TValue>` for every foreign key relationship** (e.g., `Product.CategoryId` to `Category`) and register it via type extensions using `[ExtendObjectType]`, so that resolving the category for 50 products results in one `WHERE Id IN (...)` query instead of 50 individual queries.
3. **Use `AddDbContextFactory<T>()` instead of `AddDbContext<T>()` when using DataLoaders** because DataLoaders outlive the HTTP request scope and hold references to scoped services; `IDbContextFactory` creates short-lived `DbContext` instances per batch that are disposed after use.
4. **Define input types for mutations (`CreateProductInput`) and return payload types (`CreateProductPayload`) with optional `UserError` fields** rather than throwing exceptions, following the GraphQL convention where errors are part of the response payload, not transport-level failures.
5. **Enable `AddFiltering()` and `AddSorting()` on list queries but restrict the filterable/sortable fields** using `[UseFiltering(typeof(ProductFilterType))]` with a custom filter type, to prevent clients from filtering on expensive computed columns or sensitive fields like `PasswordHash`.
6. **Use cursor-based pagination with `[UsePaging]` instead of offset-based pagination** for lists that may change between page loads, because cursor pagination guarantees no items are skipped or duplicated when new items are inserted; offset pagination shifts results when the underlying data changes.
7. **Register GraphQL services using `AddGraphQLServer()` and call `MapGraphQL()` at a dedicated path** (default `/graphql`) rather than embedding GraphQL resolution inside REST controllers, keeping the two API styles isolated and independently configurable.
8. **Apply `[Authorize]` attributes on query/mutation resolvers that require authentication** and use `[GraphQLAuthorize(Policy = "AdminOnly")]` for role-based access control, rather than checking `ClaimsPrincipal` manually in every resolver method.
9. **Use Hot Chocolate's `ITopicEventSender` and `ITopicEventReceiver` for subscriptions** rather than implementing custom WebSocket handlers, because Hot Chocolate manages subscription lifecycle, serialization, and concurrent subscriber tracking through the configured subscription provider (in-memory or Redis).
10. **Monitor resolver execution times using Hot Chocolate's built-in instrumentation events** (`IExecutionDiagnosticEvents`) and log queries that exceed a threshold (e.g., 500ms), focusing optimization on the slowest resolvers; avoid premature optimization of resolvers that complete in single-digit milliseconds.
Files in this package (21)
- AGENTS.md 9 KB
- README.md 1 KB
- SKILL.md 10 KB
- metadata.json 1 KB
- rules/_sections.md 3 KB
- rules/_template.md 1 KB
- rules/graphql-apply-authorize-attributes-on-query-mutation-resolvers-that.md 1 KB
- rules/graphql-define-input-types-for-mutations-createproductinput-and.md 1 KB
- rules/graphql-design-schema-first.md 1 KB
- rules/graphql-enable-addfiltering-and-addsorting-on-list-queries-but.md 1 KB
- rules/graphql-handle-errors-appropriately.md 1 KB
- rules/graphql-implement-batchdataloader-tkey-tvalue-for-every-foreign-key.md 1 KB
- rules/graphql-implement-dataloader-for-n-1-prevention.md 1 KB
- rules/graphql-monitor-resolver-execution-times-using-hot-chocolate-s.md 1 KB
- rules/graphql-register-graphql-services-using-addgraphqlserver-and-call.md 1 KB
- rules/graphql-use-adddbcontextfactory-t-instead-of-adddbcontext-t-when.md 1 KB
- rules/graphql-use-cursor-based-pagination-with-usepaging-instead-of.md 1 KB
- rules/graphql-use-hot-chocolate-s-itopiceventsender-and.md 1 KB
- rules/graphql-use-proper-authorization.md 1 KB
- rules/graphql-use-useprojection-on-every-query-that-returns-iqueryable-t.md 1 KB
- rules/graphql-version-through-schema-evolution.md 1 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · Tyler-R-Kendrick/agent-skills | 100 | MIT |
| TerminalSkills/skills | 100 | Apache-2.0 |
| nimadorostkar/Claude-Skills-collection | 100 | MIT |
| crowdin/skills | 100 | MIT |
| claude-dev-suite/claude-dev-suite | 100 | MIT |
| lynricsy/hyperskills | 100 | MIT |
| muon-m2/magento2-tools | 100 | MIT |
| G1Joshi/Agent-Skills | 100 | MIT |
| chrishuffman5/domain-expert | 100 | MIT |
Database snapshot: 13.11.2026 · package version f4ca7e7cd76b (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100design-api
Design REST and GraphQL APIs: naming, versioning, error shapes, auth. Use when "design an API", "create endpoints", "REST vs GraphQL", or "API contract". - 100designing-apis
Designs REST and GraphQL APIs including endpoints, error handling, versioning, and documentation. Use when creating new APIs, designing endpoints, reviewing API contracts, or when asked about REST, GraphQL, or API patterns. - 100population-net
USE FOR: GraphQL-like selective field projection in REST APIs, reducing over-fetching by returning only client-requested fields, dynamic response shaping based on query parameters, and bandwidth optimization for mobile or low-bandwidth clients. DO NOT USE FOR: Full GraphQL… - 100graphql-implementation
Builds GraphQL APIs with schema design, resolvers, error handling, and performance optimization using Apollo or Graphene. Use when creating flexible query APIs, migrating from REST, or implementing real-time subscriptions. - 100spring-graphql
Spring for GraphQL - building GraphQL APIs with Spring Boot. Covers queries, mutations, subscriptions, @BatchMapping, DataLoader, and security. USE WHEN: user mentions "spring graphql", "@QueryMapping", "@MutationMapping", "@SubscriptionMapping", "@BatchMapping", "GraphQL Spring… - 95graphql-expert
GraphQL API design and implementation. Use when building GraphQL APIs, designing schemas, implementing resolvers, or optimizing GraphQL performance.