Hotchocolate Specialist

HotChocolate Specialist

Deep HotChocolate v15 API expertise. Complements the backend-developer skill (project-specific patterns) with framework-level knowledge and self-learning from official documentation.

Scope boundary: Project-specific patterns (ObjectType layout, TypeExtension conventions, DataLoader naming, middleware testing, MassTransit, MongoDB) live in the backend-developer skill. This skill covers HotChocolate framework APIs, advanced features, and official best practices.

Self-Learning Workflow

Before answering any non-trivial HotChocolate question, fetch the latest official documentation to ensure accuracy. HotChocolate evolves rapidly — never rely solely on training data.

Step 1: Identify the Topic

Map the user's question to one or more documentation areas from the Documentation Index.

Step 2: Fetch Latest Documentation

Use fetch_webpage to retrieve the relevant page(s):

Primary:   https://chillicream.com/docs/hotchocolate/v15/{topic-path}
Fallback:  https://github.com/ChilliCream/graphql-platform/blob/main/website/src/docs/hotchocolate/v15/{topic-path}/index.md

For bleeding-edge features or source code questions, search the GitHub repository:

https://github.com/ChilliCream/graphql-platform/tree/main/src/HotChocolate/{module}

Step 3: Cross-Reference with Project Patterns

After fetching official docs, verify alignment with project conventions from backend-developer skill and general.instructions.md. Prefer project conventions when they intentionally diverge from defaults.

Step 4: Apply and Cite

Implement using the latest API. Always cite the documentation URL when introducing patterns the user may not have seen before.

Topic Quick Reference

Advanced Patterns

Custom Scalars

public class UrlType : ScalarType<Uri, StringValueNode>
{
    public UrlType() : base("Url") { }

    protected override Uri ParseLiteral(StringValueNode valueSyntax)
        => new(valueSyntax.Value);

    protected override StringValueNode ParseValue(Uri runtimeValue)
        => new(runtimeValue.AbsoluteUri);

    public override IValueNode ParseResult(object? resultValue)
        => ParseValue((Uri)resultValue!);
}

Register: .AddType<UrlType>()

Filtering — Custom Convention

public class CustomFilterConvention : FilterConvention
{
    protected override void Configure(IFilterConventionDescriptor descriptor)
    {
        descriptor.AddDefaults();
        descriptor.Provider(new QueryableFilterProvider(p =>
            p.AddDefaultFieldHandlers()));
    }
}

// Registration
services.AddGraphQLServer()
    .AddFiltering<CustomFilterConvention>();

Sorting — Custom Convention

public class CustomSortConvention : SortConvention
{
    protected override void Configure(ISortConventionDescriptor descriptor)
    {
        descriptor.AddDefaults();
        descriptor.Provider(new QueryableSortProvider(p =>
            p.AddDefaultFieldHandlers()));
    }
}

Pagination — Cursor with MongoDB

[UsePaging(IncludeTotalCount = true, MaxPageSize = 100, DefaultPageSize = 25)]
[UseProjection]
[UseSorting]
[UseFiltering]
public IExecutable<MyEntity> GetEntities([Service] IMongoCollection<MyEntity> collection)
    => collection.AsExecutable();

Order matters: [UsePaging] → [UseProjection] → [UseSorting] → [UseFiltering] (outermost to innermost).

Subscriptions

// In mutation resolver
[UseMutationConvention]
public async Task<MyEntity> CreateEntity(
    CreateEntityInput input,
    [Service] ITopicEventSender sender,
    CancellationToken ct)
{
    MyEntity entity = /* create */;
    await sender.SendAsync(nameof(OnEntityCreated), entity, ct);
    return entity;
}

// Subscription
[Subscribe]
[Topic(nameof(OnEntityCreated))]
public MyEntity OnEntityCreated([EventMessage] MyEntity entity) => entity;

Error Handling — Mutation Conventions

// Define domain errors as classes
public class EntityNotFoundError
{
    public EntityNotFoundError(string id) => Id = id;
    public string Id { get; }
    public string Message => $"Entity '{Id}' not found.";
}

// Annotate mutation with expected errors
[Error<EntityNotFoundError>]
[Error<ValidationError>]
[UseMutationConvention]
public async Task<MyEntity> UpdateEntity(UpdateEntityInput input, ...)
{
    // throw or return error types
}

Authorization — Field-Level

[Authorize(Policy = "AdminOnly")]
public class AdminQueries
{
    [Authorize(Roles = ["superadmin"])]
    public async Task<SensitiveData> GetSensitiveData(...)
        => /* ... */;
}

Interceptors

public class CustomHttpRequestInterceptor : DefaultHttpRequestInterceptor
{
    public override ValueTask OnCreateAsync(
        HttpContext context,
        IRequestExecutor requestExecutor,
        OperationRequestBuilder requestBuilder,
        CancellationToken ct)
    {
        // Add custom context data from HTTP headers
        string? tenantId = context.Request.Headers["X-Tenant-Id"];
        requestBuilder.SetGlobalState("TenantId", tenantId);
        return base.OnCreateAsync(context, requestExecutor, requestBuilder, ct);
    }
}

// Registration
services.AddGraphQLServer()
    .AddHttpRequestInterceptor<CustomHttpRequestInterceptor>();

Source Generators & Registration

HotChocolate 12.7+ source generator auto-discovers types decorated with [QueryType], [MutationType], [SubscriptionType], [ObjectType], [ExtendObjectType], etc.

// ModuleInfo.cs — triggers source generation
[assembly: Module("MyDomain")]

// Startup — register all discovered types
services.AddGraphQLServer()
    .AddTypes();  // Registers all source-generated types from the module

Persisted Operations

services.AddGraphQLServer()
    .UseAutomaticPersistedOperationPipeline()
    .AddFileSystemOperationDocumentStorage("./persisted-operations");

Alternative stores: Redis (AddRedisOperationDocumentStorage), Azure Blob Storage.

Troubleshooting Checklist

Anti-Patterns

Important Rules

• Always fetch latest documentation before implementing advanced HC features
• Attribute stacking order matters: [UsePaging] → [UseProjection] → [UseSorting] → [UseFiltering]
• Never duplicate patterns already defined in backend-developer skill — reference it instead
• Cite documentation URLs when introducing new patterns to the team
• Prefer implementation-first (annotation-based) over schema-first approach
• For project-specific conventions (naming, testing), defer to backend-developer skill and tests.instructions.md