GraphQL para C# (.NET): Guia Completo da Biblioteca GraphQL.NET

Biblioteca GraphQL C# (.NET) — GraphQL.NET

GraphQL é uma linguagem de consulta para APIs que permite aos clientes solicitar apenas os dados de que realmente precisam. No ecossistema .NET, uma das implementações mais populares é a biblioteca GraphQL.NET (também conhecida como graphql-dotnet). Ela fornece ferramentas poderosas para criar APIs flexíveis, tipadas e eficientes na plataforma C# (.NET).

Neste artigo, vamos explorar detalhadamente como usar o GraphQL.NET, abordar os conceitos-chave e fornecer exemplos práticos de código.

O que é GraphQL.NET?

GraphQL.NET é uma biblioteca de código aberto que implementa a especificação GraphQL para a plataforma .NET. Ela suporta tanto .NET Core quanto .NET Framework. Principais recursos:

• Criação de esquemas fortemente tipados em C#.
• Suporte a consultas (Query), mutações (Mutation) e assinaturas (Subscription).
• Validação e execução de consultas integradas.
• Integração com frameworks web populares (ASP.NET Core, Nancy e outros).
• Suporte a assinaturas via WebSockets (SignalR).

Instalação e configuração

Para começar, instale o pacote via NuGet:

dotnet add package GraphQLdotnet add package GraphQL.SystemTextJson  // para serialização JSON

Se você estiver usando ASP.NET Core, instale também:

dotnet add package GraphQL.Server.Transports.AspNetCoredotnet add package GraphQL.Server.Ui.Playground  // UI integrada para testes

Criando o primeiro esquema

GraphQL é construído em torno de um esquema que define os tipos de dados e as operações disponíveis. Vamos considerar um exemplo simples — uma API para obter informações sobre livros.

Passo 1. Defina o modelo de dados:

public class Book{    public string Id { get; set; }    public string Title { get; set; }    public string Author { get; set; }    public int Pages { get; set; }}

Passo 2. Crie os tipos GraphQL:

public class BookType : ObjectGraphType<Book>{    public BookType()    {        Field(x => x.Id).Description("Identificador do livro");        Field(x => x.Title).Description("Título do livro");        Field(x => x.Author).Description("Autor");        Field(x => x.Pages).Description("Número de páginas");    }}

Passo 3. Defina a consulta raiz (Query):

public class BookQuery : ObjectGraphType{    public BookQuery(IDataStore dataStore)    {        Field<BookType>("book")            .Arguments(new QueryArguments(new QueryArgument<StringGraphType> { Name = "id" }))            .Resolve(context => dataStore.GetBookById(context.GetArgument<string>("id")));

        Field<ListGraphType<BookType>>("books")            .Resolve(context => dataStore.GetAllBooks());    }}

Passo 4. Monte o esquema:

public class BookSchema : Schema{    public BookSchema(IServiceProvider provider) : base(provider)    {        Query = provider.GetRequiredService<BookQuery>();    }}

Integração com ASP.NET Core

Registre os serviços no Program.cs (ou Startup.cs):

builder.Services.AddGraphQL(b => b    .AddSystemTextJson()    .AddSchema<BookSchema>()    .AddGraphTypes(typeof(BookType).Assembly));

builder.Services.AddScoped<IDataStore, InMemoryDataStore>();

Adicione o middleware:

app.UseGraphQL<BookSchema>();  // endpoint padrão /graphqlapp.UseGraphQLPlayground();    // UI para testes (opcional)

Executando uma consulta

Agora você pode