Add field projections

Author: SimonCropp

claude.md

@@ -2,6 +2,14 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## Workflow Guidelines
+
+**IMPORTANT - Git Commits:**
+- NEVER automatically commit changes
+- NEVER prompt or ask to commit changes
+- NEVER suggest creating commits
+- The user will handle all git commits manually
+
 ## Project Overview
 
 GraphQL.EntityFramework is a .NET library that adds EntityFramework Core IQueryable support to GraphQL.NET. It enables automatic query generation, filtering, pagination, and ordering for GraphQL queries backed by EF Core.
@@ -67,6 +75,10 @@ The README.md and docs/*.md files are auto-generated from source files using [Ma
 - Builds LINQ expressions from GraphQL where clause arguments
 - Supports complex filtering including grouping, negation, and nested properties
 
+**ProjectionAnalyzer** (`src/GraphQL.EntityFramework/GraphApi/ProjectionAnalyzer.cs`)
+- Analyzes projection expressions to extract required property names
+- Used by navigation fields, filters, and FieldBuilder extensions to determine which properties need to be loaded
+
 **Filters** (`src/GraphQL.EntityFramework/Filters/Filters.cs`)
 - Post-query filtering mechanism for authorization or business rules
 - Executed after EF query to determine if nodes should be included in results
@@ -136,6 +148,60 @@ Arguments are processed in order: ids → where → orderBy → skip → take
 
 The library supports EF projections where you can use `Select()` to project to DTOs or anonymous types before applying GraphQL field resolution.
 
+### FieldBuilder Extensions (Projection-Based Resolve)
+
+The library provides projection-based extension methods on `FieldBuilder` to safely access navigation properties in custom resolvers:
+
+**Extension Methods** (`src/GraphQL.EntityFramework/GraphApi/FieldBuilderExtensions.cs`)
+- `Resolve<TDbContext, TSource, TReturn, TProjection>()` - Synchronous resolver with projection
+- `ResolveAsync<TDbContext, TSource, TReturn, TProjection>()` - Async resolver with projection
+- `ResolveList<TDbContext, TSource, TReturn, TProjection>()` - List resolver with projection
+- `ResolveListAsync<TDbContext, TSource, TReturn, TProjection>()` - Async list resolver with projection
+
+**Why Use These Methods:**
+When using `Field().Resolve()` or `Field().ResolveAsync()` directly, navigation properties on `context.Source` may be null if the projection system didn't include them. The projection-based extension methods ensure required data is loaded by:
+1. Storing projection metadata in field metadata
+2. Compiling the projection expression for runtime execution
+3. Applying the projection to `context.Source` before calling your resolver
+4. Providing the projected data via `ResolveProjectionContext<TDbContext, TProjection>`
+
+**Example:**
+```csharp
+public class ChildGraphType : EfObjectGraphType<IntegrationDbContext, ChildEntity>
+{
+    public ChildGraphType(IEfGraphQLService<IntegrationDbContext> graphQlService) : base(graphQlService) =>
+        Field<int>("ParentId")
+            .Resolve<IntegrationDbContext, ChildEntity, int, ParentEntity>(
+                projection: x => x.Parent!,
+                resolve: ctx => ctx.Projection.Id);
+}
+```
+
+## Roslyn Analyzer
+
+The project includes a Roslyn analyzer (`GraphQL.EntityFramework.Analyzers`) that detects problematic usage patterns at compile time:
+
+**GQLEF002**: Warns when using `Field().Resolve()` or `Field().ResolveAsync()` to access navigation properties without projection
+- **Category:** Usage
+- **Severity:** Warning
+- **Solution:** Use projection-based extension methods instead
+
+**Safe Patterns (No Warning):**
+- Accessing primary key properties (e.g., `context.Source.Id`, `context.Source.CompanyId` when in `Company` class)
+- Accessing foreign key properties (e.g., `context.Source.ParentId`, `context.Source.UserId`)
+- Using projection-based extension methods
+
+**Unsafe Patterns (Warning):**
+- Accessing scalar properties (e.g., `context.Source.Name`, `context.Source.Age`) - these might not be loaded
+- Accessing navigation properties (e.g., `context.Source.Parent`)
+- Accessing properties on navigation properties (e.g., `context.Source.Parent.Id`)
+- Accessing collection navigation properties (e.g., `context.Source.Children.Count()`)
+
+**Why Only PK/FK Are Safe:**
+The EF projection system always loads primary keys and foreign keys, but other properties (including regular scalars like `Name` or `Age`) are only loaded if explicitly requested in the GraphQL query. Accessing them in a resolver without projection can cause null reference exceptions.
+
+The analyzer automatically runs during build and in IDEs (Visual Studio, Rider, VS Code).
+
 ## Testing
 
 Tests use:
@@ -157,3 +223,4 @@ The test project (`src/Tests/`) includes:
 - Treats warnings as errors
 - Uses .editorconfig for code style enforcement
 - Uses Fody/ConfigureAwait.Fody for ConfigureAwait(false) injection
+- Always use `_ => _` for single parameter delegates (not `x => x` or other named parameters)

docs/configuration.md

@@ -721,9 +721,9 @@ public class BaseGraphType :
 {
     public BaseGraphType(IEfGraphQLService<IntegrationDbContext> graphQlService) :
         base(graphQlService) =>
-        AddNavigationConnectionField<DerivedChildEntity>(
+        AddNavigationConnectionField(
             name: "childrenFromInterface",
-            includeNames: ["ChildrenFromBase"]);
+            projection: _ => _.ChildrenFromBase);
 }
 ```
 <sup><a href='/src/Tests/IntegrationTests/Graphs/Inheritance/BaseGraphType.cs#L1-L9' title='Snippet source file'>snippet source</a> | <a href='#snippet-BaseGraphType.cs' title='Start of snippet'>anchor</a></sup>
@@ -740,14 +740,15 @@ public class DerivedGraphType :
     {
         AddNavigationConnectionField(
             name: "childrenFromInterface",
-            _ => _.Source.ChildrenFromBase);
+            projection: _ => _.ChildrenFromBase,
+            resolve: _ => _.Projection);
         AutoMap();
         Interface<BaseGraphType>();
         IsTypeOf = obj => obj is DerivedEntity;
     }
 }
 ```
-<sup><a href='/src/Tests/IntegrationTests/Graphs/Inheritance/DerivedGraphType.cs#L1-L14' title='Snippet source file'>snippet source</a> | <a href='#snippet-DerivedGraphType.cs' title='Start of snippet'>anchor</a></sup>
+<sup><a href='/src/Tests/IntegrationTests/Graphs/Inheritance/DerivedGraphType.cs#L1-L15' title='Snippet source file'>snippet source</a> | <a href='#snippet-DerivedGraphType.cs' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 

docs/defining-graphs.md

@@ -46,7 +46,29 @@ context.Heros
         .Include("Friends.Address");
 ```
 
-The string for the include is taken from the field name when using `AddNavigationField` or `AddNavigationConnectionField` with the first character upper cased. This value can be overridden using the optional parameter `includeNames` . Note that `includeNames` is an `IEnumerable<string>` so that multiple navigation properties can optionally be included for a single node.
+The string for the include is taken from the field name when using `AddNavigationField` or `AddNavigationConnectionField` with the first character upper cased. This can be customized using a projection expression:
+
+```cs
+// Using projection to specify which navigation properties to include
+AddNavigationConnectionField(
+    name: "employeesConnection",
+    projection: _ => _.Employees,
+    resolve: ctx => ctx.Projection);
+
+// Multiple properties can be included using anonymous types
+AddNavigationField(
+    name: "child1",
+    projection: _ => new { _.Child1, _.Child2 },
+    resolve: ctx => ctx.Projection.Child1);
+
+// Nested navigation paths are also supported
+AddNavigationField(
+    name: "level3Entity",
+    projection: _ => _.Level2Entity.Level3Entity,
+    resolve: ctx => ctx.Projection);
+```
+
+The projection expression provides type-safety and automatically extracts the include names from the accessed properties.
 
 
 ## Projections
@@ -146,6 +168,55 @@ public class OrderGraph :
 Without automatic foreign key inclusion, `context.Source.CustomerId` would be `0` (or `Guid.Empty` for Guid keys) if `customerId` wasn't explicitly requested in the GraphQL query, causing the query to fail.
 
 
+### Using Projection-Based Resolve
+
+When using `Field().Resolve()` or `Field().ResolveAsync()` in graph types, navigation properties on `context.Source` may not be loaded if the projection system didn't include them. To safely access navigation properties in custom resolvers, use the projection-based extension methods:
+
+```cs
+public class ChildGraphType : EfObjectGraphType<IntegrationDbContext, ChildEntity>
+{
+    public ChildGraphType(IEfGraphQLService<IntegrationDbContext> graphQlService) :
+        base(graphQlService) =>
+        Field<int>("ParentId")
+            .Resolve<IntegrationDbContext, ChildEntity, int, ParentEntity>(
+                projection: x => x.Parent,
+                resolve: ctx => ctx.Projection.Id);
+}
+```
+
+**Available Extension Methods:**
+
+- `Resolve<TDbContext, TSource, TReturn, TProjection>()` - Synchronous resolver with projection
+- `ResolveAsync<TDbContext, TSource, TReturn, TProjection>()` - Async resolver with projection
+- `ResolveList<TDbContext, TSource, TReturn, TProjection>()` - List resolver with projection
+- `ResolveListAsync<TDbContext, TSource, TReturn, TProjection>()` - Async list resolver with projection
+
+The projection-based extension methods ensure required data is loaded by:
+
+1. Storing projection metadata in field metadata
+2. Compiling the projection expression for runtime execution
+3. Applying the projection to `context.Source` before calling the resolver
+4. Providing the projected data via `ResolveProjectionContext<TDbContext, TProjection>`
+
+**Problematic Pattern (Navigation Property May Be Null):**
+
+```cs
+Field<int>("ParentId")
+    .Resolve(context => context.Source.Parent.Id); // Parent may be null
+```
+
+**Safe Pattern (Projection Ensures Data Is Loaded):**
+
+```cs
+Field<int>("ParentId")
+    .Resolve<IntegrationDbContext, ChildEntity, int, ParentEntity>(
+        projection: x => x.Parent,
+        resolve: ctx => ctx.Projection.Id); // Parent is guaranteed to be loaded
+```
+
+**Note:** A Roslyn analyzer (GQLEF002) warns at compile time when `Field().Resolve()` accesses properties other than primary keys and foreign keys. Only PK and FK properties are guaranteed to be loaded by the projection system - all other properties (including regular scalars like `Name`) require projection-based extension methods to ensure they are loaded.
+
+
 ### When Projections Are Not Used
 
 Projections are bypassed and the full entity is loaded in these cases:
@@ -213,16 +284,17 @@ public class CompanyGraph :
     {
         AddNavigationListField(
             name: "employees",
-            resolve: _ => _.Source.Employees);
+            projection: _ => _.Employees,
+            resolve: _ => _.Projection);
         AddNavigationConnectionField(
             name: "employeesConnection",
-            resolve: _ => _.Source.Employees,
-            includeNames: ["Employees"]);
+            projection: _ => _.Employees,
+            resolve: _ => _.Projection);
         AutoMap();
     }
 }
 ```
-<sup><a href='/src/Snippets/TypedGraph.cs#L5-L24' title='Snippet source file'>snippet source</a> | <a href='#snippet-typedGraph' title='Start of snippet'>anchor</a></sup>
+<sup><a href='/src/Snippets/TypedGraph.cs#L5-L25' title='Snippet source file'>snippet source</a> | <a href='#snippet-typedGraph' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 
@@ -340,10 +412,11 @@ public class CompanyGraph :
         base(graphQlService) =>
         AddNavigationConnectionField(
             name: "employees",
-            resolve: _ => _.Source.Employees);
+            projection: _ => _.Employees,
+            resolve: _ => _.Projection);
 }
 ```
-<sup><a href='/src/Snippets/ConnectionTypedGraph.cs#L5-L17' title='Snippet source file'>snippet source</a> | <a href='#snippet-ConnectionTypedGraph' title='Start of snippet'>anchor</a></sup>
+<sup><a href='/src/Snippets/ConnectionTypedGraph.cs#L5-L18' title='Snippet source file'>snippet source</a> | <a href='#snippet-ConnectionTypedGraph' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 

docs/filters.md

@@ -294,7 +294,7 @@ Filters can project through navigation properties to access related entity data:
 ```cs
 var filters = new Filters<MyDbContext>();
 filters.For<Order>().Add(
-    projection: o => new { o.TotalAmount, o.Customer.IsActive },
+    projection: _ => new { _.TotalAmount, _.Customer.IsActive },
     filter: (_, _, _, x) => x.TotalAmount >= 100 && x.IsActive);
 EfGraphQLConventions.RegisterInContainer<MyDbContext>(
     services,

docs/mdsource/defining-graphs.source.md

@@ -39,7 +39,29 @@ context.Heros
         .Include("Friends.Address");
 ```
 
-The string for the include is taken from the field name when using `AddNavigationField` or `AddNavigationConnectionField` with the first character upper cased. This value can be overridden using the optional parameter `includeNames` . Note that `includeNames` is an `IEnumerable<string>` so that multiple navigation properties can optionally be included for a single node.
+The string for the include is taken from the field name when using `AddNavigationField` or `AddNavigationConnectionField` with the first character upper cased. This can be customized using a projection expression:
+
+```cs
+// Using projection to specify which navigation properties to include
+AddNavigationConnectionField(
+    name: "employeesConnection",
+    projection: _ => _.Employees,
+    resolve: ctx => ctx.Projection);
+
+// Multiple properties can be included using anonymous types
+AddNavigationField(
+    name: "child1",
+    projection: _ => new { _.Child1, _.Child2 },
+    resolve: ctx => ctx.Projection.Child1);
+
+// Nested navigation paths are also supported
+AddNavigationField(
+    name: "level3Entity",
+    projection: _ => _.Level2Entity.Level3Entity,
+    resolve: ctx => ctx.Projection);
+```
+
+The projection expression provides type-safety and automatically extracts the include names from the accessed properties.
 
 
 ## Projections
@@ -87,6 +109,55 @@ snippet: ProjectionCustomResolver
 Without automatic foreign key inclusion, `context.Source.CustomerId` would be `0` (or `Guid.Empty` for Guid keys) if `customerId` wasn't explicitly requested in the GraphQL query, causing the query to fail.
 
 
+### Using Projection-Based Resolve
+
+When using `Field().Resolve()` or `Field().ResolveAsync()` in graph types, navigation properties on `context.Source` may not be loaded if the projection system didn't include them. To safely access navigation properties in custom resolvers, use the projection-based extension methods:
+
+```cs
+public class ChildGraphType : EfObjectGraphType<IntegrationDbContext, ChildEntity>
+{
+    public ChildGraphType(IEfGraphQLService<IntegrationDbContext> graphQlService) :
+        base(graphQlService) =>
+        Field<int>("ParentId")
+            .Resolve<IntegrationDbContext, ChildEntity, int, ParentEntity>(
+                projection: x => x.Parent,
+                resolve: ctx => ctx.Projection.Id);
+}
+```
+
+**Available Extension Methods:**
+
+- `Resolve<TDbContext, TSource, TReturn, TProjection>()` - Synchronous resolver with projection
+- `ResolveAsync<TDbContext, TSource, TReturn, TProjection>()` - Async resolver with projection
+- `ResolveList<TDbContext, TSource, TReturn, TProjection>()` - List resolver with projection
+- `ResolveListAsync<TDbContext, TSource, TReturn, TProjection>()` - Async list resolver with projection
+
+The projection-based extension methods ensure required data is loaded by:
+
+1. Storing projection metadata in field metadata
+2. Compiling the projection expression for runtime execution
+3. Applying the projection to `context.Source` before calling the resolver
+4. Providing the projected data via `ResolveProjectionContext<TDbContext, TProjection>`
+
+**Problematic Pattern (Navigation Property May Be Null):**
+
+```cs
+Field<int>("ParentId")
+    .Resolve(context => context.Source.Parent.Id); // Parent may be null
+```
+
+**Safe Pattern (Projection Ensures Data Is Loaded):**
+
+```cs
+Field<int>("ParentId")
+    .Resolve<IntegrationDbContext, ChildEntity, int, ParentEntity>(
+        projection: x => x.Parent,
+        resolve: ctx => ctx.Projection.Id); // Parent is guaranteed to be loaded
+```
+
+**Note:** A Roslyn analyzer (GQLEF002) warns at compile time when `Field().Resolve()` accesses properties other than primary keys and foreign keys. Only PK and FK properties are guaranteed to be loaded by the projection system - all other properties (including regular scalars like `Name`) require projection-based extension methods to ensure they are loaded.
+
+
 ### When Projections Are Not Used
 
 Projections are bypassed and the full entity is loaded in these cases:

src/Benchmarks/SimpleQueryBenchmark.cs

@@ -38,8 +38,8 @@ public ParentGraphType(IEfGraphQLService<BenchmarkDbContext> graphQlService) :
     {
         AddNavigationListField(
             name: "children",
-            resolve: _ => _.Source.Children,
-            includeNames: ["Children"]);
+            projection: _ => _.Children,
+            resolve: _ => _.Projection);
         AutoMap();
     }
 }

src/Directory.Build.props

@@ -2,7 +2,7 @@
 <Project>
   <PropertyGroup>
     <NoWarn>CS1591;NU5104;CS1573;CS9107;NU1608;NU1109</NoWarn>
-    <Version>34.0.0-beta.4</Version>
+    <Version>34.0.0</Version>
     <LangVersion>preview</LangVersion>
     <AssemblyVersion>1.0.0</AssemblyVersion>
     <PackageTags>EntityFrameworkCore, EntityFramework, GraphQL</PackageTags>

src/Directory.Packages.props

@@ -15,6 +15,8 @@
     <PackageVersion Include="GraphQL.SystemTextJson" Version="8.8.3" />
     <PackageVersion Include="MarkdownSnippets.MsBuild" Version="28.0.0-beta.25" />
     <PackageVersion Include="Microsoft.AspNetCore.Mvc.Testing" Version="10.0.2" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.Analyzers" Version="3.11.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="5.0.0" />
     <PackageVersion Include="Microsoft.Data.SqlClient" Version="6.1.4" />
     <PackageVersion Include="Microsoft.EntityFrameworkCore" Version="10.0.2" />
     <PackageVersion Include="Microsoft.EntityFrameworkCore.InMemory" Version="10.0.2" />