RESTier vNext: Modernize to ASP.NET Core, OData 8.x, and .NET 8/9/10

.github/CONTRIBUTING.md

@@ -38,7 +38,7 @@ These are the recommended steps to create a pull request:<br />
 17. Microsoft OData team will merge the pull request into upstream
 
 ### Test specification
-All tests need to be written with xUnit. Here are some rules to follow when you are organizing the test code:
+All tests need to be written with MSTest. Here are some rules to follow when you are organizing the test code:
 - **Project name correspondence** (`X -> X.Tests`). For instance, all the test code of the `Microsoft.Restier.Core` project should be placed in the `Microsoft.Restier.Core.Tests` project. Path and file name correspondence. (`X/Y/Z/A.cs -> X.Tests/Y/Z/ATests.cs`). For example, the test code of the `ConventionBasedApiModelBuilder` class (in the `Microsoft.Restier.Core/Convention/ConventionBasedApiModelBuilder.cs` file) should be placed in the `Microsoft.Restier.Core.Tests/Convention/ConventionBasedApiModelBuilderTests.cs` file.
 - **Namespace correspondence** (`X.Tests/Y/Z -> X.Tests.Y.Z`). The namespace of the file should strictly follow the path. For example, the namespace of the `ConventionBasedApiModelBuilderTests.cs` file should be `Microsoft.Restier.Core.Tests.Convention`.
 - **Utility classes**. The file for a utility class can be placed at the same level of its user or a shared level that is visible to all its users. But the file name must **NOT** be ended with `Tests` to avoid any confusion.

.gitignore

@@ -29,6 +29,9 @@ bld/
 # Uncomment if you have tasks that create the project's static files in wwwroot
 #wwwroot/
 
+#claude generated files.
+.claude/
+
 # Visual Studio 2017 auto generated files
 Generated\ Files/
 
@@ -329,3 +332,9 @@ ASALocalRun/
 # MFractors (Xamarin productivity tool) working folder 
 .mfractor/
 /docs/msdocs/.vscode
+/docs/msdocs/_site/
+
+# DotNetDocs SDK regenerates this on build
+src/Microsoft.Restier.Docs/api-reference/
+# DotNetDocs SDK writes this as a Debug-build debug dump (not config)
+src/Microsoft.Restier.Docs/assembly-list.txt

.pipelines/RESTier-CI.yml

@@ -23,7 +23,7 @@ stages:
 
     # --- Set Build Name ---
     - powershell: |
-        $buildName = "1.2.0-CI-$(Get-Date -Format 'yyyyMMdd-HHmmss')"
+        $buildName = "2.0.0-CI-$(Get-Date -Format 'yyyyMMdd-HHmmss')"
         Write-Host "##vso[build.updatebuildnumber]$buildName"
       displayName: Set Build Name
 
@@ -35,12 +35,29 @@ stages:
         packageType: sdk
         version: 10.0.100
 
+    # net8/net9 SDKs for multi-targeted test execution. UseDotNet@2 above pins
+    # dotnet to the tool cache, hiding the agent's pre-installed runtimes; and
+    # packageType: runtime only installs Microsoft.NETCore.App, not the
+    # Microsoft.AspNetCore.App shared framework the tests need, so we install
+    # SDKs (which bundle both runtimes) instead.
+    - task: UseDotNet@2
+      displayName: Use .NET SDK 9.x
+      inputs:
+        packageType: sdk
+        version: 9.x
+
+    - task: UseDotNet@2
+      displayName: Use .NET SDK 8.x
+      inputs:
+        packageType: sdk
+        version: 8.x
+
     # --- Restore & Build ---
     - task: DotNetCoreCLI@2
       displayName: dotnet restore
       inputs:
         command: restore
-        projects: 'src/RESTier.slnx'
+        projects: 'RESTier.slnx'
         feedsToUse: config
         nugetConfigPath: 'NuGet.Config'
 
@@ -55,15 +72,73 @@ stages:
           --configuration $(BuildConfiguration)
           --no-restore
 
+    # --- Test ---
+    # Pre-start LocalDB so the first test's connection doesn't time out waiting
+    # on the ~60s auto-start (observed previously failing the net8 batch).
+    - powershell: |
+        sqllocaldb start MSSQLLocalDB
+        sqllocaldb info MSSQLLocalDB
+      displayName: Start LocalDB
+
+    - task: DotNetCoreCLI@2
+      displayName: dotnet test
+      env:
+        ConnectionStrings__LibraryContext: 'Server=(localdb)\MSSQLLocalDB;Initial Catalog=LibraryContext;Trusted_Connection=true;TrustServerCertificate=true'
+        ConnectionStrings__MarvelContext: 'Server=(localdb)\MSSQLLocalDB;Initial Catalog=MarvelContext;Trusted_Connection=true;TrustServerCertificate=true'
+      inputs:
+        command: test
+        projects: 'test/**/*.csproj'
+        arguments: >
+          --configuration $(BuildConfiguration)
+          --no-build
+          --collect:"XPlat Code Coverage"
+        publishTestResults: true
+
+    # --- Coverage report ---
+    - task: DotNetCoreCLI@2
+      displayName: Install ReportGenerator
+      inputs:
+        command: custom
+        custom: tool
+        arguments: install dotnet-reportgenerator-globaltool --tool-path $(Agent.TempDirectory)/tools
+
+    - powershell: |
+        Write-Host "=== Coverage files discovered under Agent.TempDirectory ==="
+        Get-ChildItem -Path "$(Agent.TempDirectory)" -Filter coverage.cobertura.xml -Recurse -ErrorAction SilentlyContinue |
+          ForEach-Object { Write-Host $_.FullName }
+        Write-Host "==========================================================="
+        & "$(Agent.TempDirectory)/tools/reportgenerator.exe" `
+          "-reports:$(Agent.TempDirectory)/**/coverage.cobertura.xml" `
+          "-targetdir:$(Build.ArtifactStagingDirectory)/CoverageReport" `
+          "-reporttypes:Cobertura;HtmlInline_AzurePipelines;TextSummary"
+        Get-Content "$(Build.ArtifactStagingDirectory)/CoverageReport/Summary.txt"
+      displayName: Generate Coverage Report
+
+    - task: PublishCodeCoverageResults@2
+      displayName: Publish Code Coverage
+      inputs:
+        summaryFileLocation: '$(Build.ArtifactStagingDirectory)/CoverageReport/Cobertura.xml'
+        pathToSources: '$(Build.SourcesDirectory)'
+
+    - task: PublishPipelineArtifact@1
+      displayName: 'Publish Artifact: CoverageReport'
+      inputs:
+        targetPath: '$(Build.ArtifactStagingDirectory)/CoverageReport'
+        artifact: CoverageReport
+      condition: succeededOrFailed()
+
     # --- Pack ---
     - powershell: |
         $projects = @(
           "src/Microsoft.Restier.Core/Microsoft.Restier.Core.csproj",
           "src/Microsoft.Restier.EntityFramework/Microsoft.Restier.EntityFramework.csproj",
+          "src/Microsoft.Restier.EntityFramework.Spatial/Microsoft.Restier.EntityFramework.Spatial.csproj",
           "src/Microsoft.Restier.EntityFrameworkCore/Microsoft.Restier.EntityFrameworkCore.csproj",
-          "src/Microsoft.Restier.AspNet/Microsoft.Restier.AspNet.csproj",
+          "src/Microsoft.Restier.EntityFrameworkCore.Spatial/Microsoft.Restier.EntityFrameworkCore.Spatial.csproj",
           "src/Microsoft.Restier.AspNetCore/Microsoft.Restier.AspNetCore.csproj",
           "src/Microsoft.Restier.AspNetCore.Swagger/Microsoft.Restier.AspNetCore.Swagger.csproj",
+          "src/Microsoft.Restier.AspNetCore.NSwag/Microsoft.Restier.AspNetCore.NSwag.csproj",
+          "src/Microsoft.Restier.AspNetCore.Versioning/Microsoft.Restier.AspNetCore.Versioning.csproj",
           "src/Microsoft.Restier.Breakdance/Microsoft.Restier.Breakdance.csproj"
         )
         foreach ($proj in $projects) {

CLAUDE.md

@@ -0,0 +1,119 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Microsoft RESTier is an OData V4 API development framework for building standardized RESTful services on .NET. It is the spiritual successor to WCF Data Services, providing convention-based query interception and data manipulation over Entity Framework.
+
+## Build & Test Commands
+
+```bash
+# Build entire solution
+dotnet build RESTier.slnx
+
+# Run all tests
+dotnet test RESTier.slnx
+
+# Run a single test project
+dotnet test test/Microsoft.Restier.Tests.Core/Microsoft.Restier.Tests.Core.csproj
+
+# Run a specific test by name
+dotnet test --filter "FullyQualifiedName~TestMethodName"
+
+# Build a single project
+dotnet build src/Microsoft.Restier.Core/Microsoft.Restier.Core.csproj
+```
+
+## Architecture
+
+### Core Pipeline (Chain of Responsibility)
+
+RESTier's central pattern is a **chain of responsibility** pipeline for both queries and submissions. Services implement `IChainedService<TService>` with an `Inner` property, composed via `IChainOfResponsibilityFactory`.
+
+**Query pipeline** (`Microsoft.Restier.Core.Query`):
+`IQueryExpressionSourcer` -> `IQueryExpressionAuthorizer` -> `IQueryExpressionExpander` -> `IQueryExpressionProcessor` -> `IQueryExecutor`
+Orchestrated by `DefaultQueryHandler`.
+
+**Submit pipeline** (`Microsoft.Restier.Core.Submit`):
+`IChangeSetInitializer` -> `IChangeSetItemFilter` -> `IChangeSetItemAuthorizer` -> `IChangeSetItemValidator` -> `ISubmitExecutor`
+Orchestrated by `DefaultSubmitHandler`.
+
+### Convention-Based Interception
+
+RESTier discovers interceptor methods by naming convention on `ApiBase` subclasses:
+- `OnFiltering{EntitySet}()` / `OnInserting{Entity}()` / `OnValidating{Entity}()` etc.
+- Implemented via `ConventionBasedQueryExpressionProcessor`, `ConventionBasedChangeSetItemFilter`, `ConventionBasedChangeSetItemValidator`
+
+### Key Base Classes
+
+- `ApiBase` - Base class for all RESTier APIs; subclass to define your API surface
+- `EntityFrameworkApi<TContext>` - EF-specific base providing DbContext integration
+- `RestierController : ODataController` - Handles OData HTTP requests in ASP.NET Core
+
+### Project Layout
+
+| Directory | Purpose |
+|-----------|---------|
+| `src/Microsoft.Restier.Core` | Core abstractions, pipelines, conventions, DI |
+| `src/Microsoft.Restier.AspNetCore` | ASP.NET Core integration, routing, controller |
+| `src/Microsoft.Restier.EntityFramework` | Entity Framework 6.x support |
+| `src/Microsoft.Restier.EntityFrameworkCore` | Entity Framework Core support |
+| `src/Microsoft.Restier.EntityFramework.Shared` | Shared EF code (shared project, not NuGet) |
+| `src/Microsoft.Restier.Breakdance` | In-memory testing framework |
+| `src/Microsoft.Restier.AspNetCore.Swagger` | Swagger/OpenAPI generation |
+
+### Dependency Injection
+
+Uses `Microsoft.Extensions.DependencyInjection` with per-route service containers. Service registration extensions are in `Microsoft.Restier.Core.DependencyInjection` and `Microsoft.Restier.AspNetCore.Extensions`.
+
+## Code Conventions
+
+- **Targets:** .NET 8.0, .NET 9.0, and .NET Framework 4.8
+- **Warnings as errors** enabled globally
+- **Implicit usings disabled** - all `using` directives must be explicit
+- **Nullable reference types disabled**
+- **Strong name signing** with `restier.snk`
+- **Allman brace style**, prefer `var`, prefer curly braces even for single-line blocks
+- **InternalsVisibleTo** is auto-configured from source to matching test project
+
+## Test Conventions
+
+- **Framework:** MSTest 3.x, FluentAssertions (AwesomeAssertions), NSubstitute
+- **Project naming:** `X` -> `X.Tests` (e.g., `Microsoft.Restier.Core` -> `Microsoft.Restier.Tests.Core`)
+- **File naming:** `X/Y/Z/A.cs` -> `X.Tests/Y/Z/ATests.cs`
+- **Namespace:** must match folder path (e.g., `Microsoft.Restier.Tests.Core.Convention`)
+- **Integration/scenario tests** go in `X.Tests/IntegrationTests` or `X.Tests/ScenarioTests`
+
+## Documentation
+
+Documentation lives in `src/Microsoft.Restier.Docs/` and is built with the **DotNetDocs SDK** (`<Project Sdk="DotNetDocs.Sdk/1.2.0">`), which generates Mintlify-flavored MDX.
+
+```bash
+# Build the docs project (regenerates api-reference/ and docs.json)
+dotnet build src/Microsoft.Restier.Docs/Microsoft.Restier.Docs.docsproj
+```
+
+The docs project is part of `RESTier.slnx`, so a full solution build also builds the docs:
+
+```bash
+dotnet build RESTier.slnx
+```
+
+**Authoring conventions:**
+- Hand-written content lives under `guides/`, `release-notes/`, and the project root (`index.mdx`, `quickstart.mdx`, `contribution-guidelines.mdx`, `why-restier.mdx`).
+- API reference under `api-reference/` is auto-generated from XML doc comments (six assemblies at TFM `net9.0`) and gitignored — do NOT hand-edit it.
+- Pages use Mintlify components: `<Info>`, `<Note>`, `<Tip>`, `<Warning>`, `<Steps>`, `<CodeGroup>`, `<Tabs>`, `<CardGroup>`. See existing pages for examples.
+
+**Navigation source of truth:** the `<MintlifyTemplate>` block in `Microsoft.Restier.Docs.docsproj`. The SDK regenerates `docs.json` from this template on every build, so commit `docs.json` alongside any nav-affecting change but do not hand-edit it.
+
+**Build-ordering note:** the docsproj has an explicit `BuildSourceProjectsForDocs` target that calls `<MSBuild>` on each documented source project for `net8.0` before doc generation runs. The DotNetDocs SDK resolves assembly paths against `bin/Debug/net8.0/`, and `<ProjectReference>` items alone don't reliably trigger a full Build of the multi-targeted source projects from this NoTargets-style docsproj.
+
+`assembly-list.txt` under the docs project is a Debug-build debug dump written by the SDK (not configuration). It is gitignored.
+
+## Key Dependencies
+
+- Microsoft.OData.Core / Microsoft.OData.Edm (8.x)
+- Microsoft.OData.ModelBuilder (2.x)
+- Microsoft.AspNetCore.OData (9.x)
+- EntityFramework 6.5.x / EntityFrameworkCore 8.x-10.x