OData · jspuij · Apr 9, 2025 · Apr 12, 2025 · Apr 12, 2025 · Apr 21, 2025
diff --git a/.DS_Store b/.DS_Store
diff --git a/.claude/settings.local.json b/.claude/settings.local.json
diff --git a/src/.editorconfig → .editorconfig b/src/.editorconfig → .editorconfig
diff --git a/.gitignore b/.gitignore
@@ -329,3 +329,4 @@ ASALocalRun/
 # MFractors (Xamarin productivity tool) working folder 
 .mfractor/
 /docs/msdocs/.vscode
+/docs/msdocs/_site/
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,107 @@
+# 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:** xUnit v3, 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 `docs/msdocs/` and is built with **docfx** (not mkdocs, despite the legacy `mkdocs.yml`).
+
+```bash
+# Build docs (installs docfx as .NET global tool if missing)
+docs/msdocs/build.sh
+
+# Serve locally for preview
+docfx serve docs/msdocs/_site
+```
+
+The navigation structure is defined in `docs/mkdocs.yml` (legacy) and `docs/msdocs/toc.yml` / `docs/msdocs/docfx.json`.
+
+## 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
diff --git a/src/Directory.Build.props → Directory.Build.props b/src/Directory.Build.props → Directory.Build.props
@@ -3,6 +3,7 @@
 	<PropertyGroup>
 		<IsBenchmarkProject Condition="$(MSBuildProjectName.EndsWith('.Performance'))">true</IsBenchmarkProject>
 		<IsTestProject Condition="$(MSBuildProjectName.ToLower().Contains('.tests.'))">true</IsTestProject>
+    <IsTestSharedProject Condition="$(MSBuildProjectName.ToLower().Contains('.tests.shared'))">true</IsTestSharedProject>
 		<IsTestAssetProject Condition="$(RepoRelativeProjectDir.ToLower().Contains('testassets'))">true</IsTestAssetProject>
 		<IsSampleProject Condition="$(MSBuildProjectName.ToLower().Contains('.samples.'))">true</IsSampleProject>
 		<IsTemplateProject Condition="$(MSBuildProjectName.ToLower().Contains('.templates.'))">true</IsTemplateProject>
@@ -81,19 +82,13 @@
 		<!-- Suppress warnings about pre-release packages -->
 		<NoWarn>$(NoWarn);NU5104</NoWarn>
 
-	</PropertyGroup>
+		<!-- Suppress .NET 10 package pruning warnings for multi-targeted packages that are in-box on net10.0 -->
+		<NoWarn>$(NoWarn);NU1510</NoWarn>
 
-	<!-- Base settings for all test projects -->
-	<PropertyGroup Condition=" $(IsTestProject) == 'true' ">
-		<NoWarn>$(NoWarn);CA1001;CA1031;CA1062;CA1301;CA1303;AC1307;CA1707;CA1716;CA1801;CA1806;CA1819;CA1822;CA1825;CA2000;CA2007;CA2227;CA2234</NoWarn>
-		<IsPackable>false</IsPackable>
 	</PropertyGroup>
 
-	<!-- Use VSTest for all test projects to support both net48 and modern .NET in the same test run.
-		 MSTest 4.x with EnableMSTestRunner=true would enable Microsoft.Testing.Platform,
-		 but that conflicts with net48 projects which cannot use MTP. -->
 	<PropertyGroup Condition=" $(IsTestProject) == 'true' ">
-		<EnableMSTestRunner>false</EnableMSTestRunner>
+		<NoWarn>$(NoWarn);CA1001;CA1031;CA1062;CA1301;CA1303;AC1307;CA1707;CA1716;CA1801;CA1806;CA1819;CA1822;CA1825;CA2000;CA2007;CA2227;CA2234</NoWarn>
 	</PropertyGroup>
 
 	<PropertyGroup Condition=" $(IsSampleProject) == 'true' ">
@@ -108,26 +103,44 @@
 
 	<PropertyGroup>
 		<StandardTestTfms>net48</StandardTestTfms>
+		<RestierBreakdanceVersion>[8.0.0, 9.0.0)</RestierBreakdanceVersion>
+		<RestierEasyAfVersion>[4.0.0, 5.0.0)</RestierEasyAfVersion>
+		<RestierNet9DependencyInjectionVersion>[9.*, 10.0.0)</RestierNet9DependencyInjectionVersion>
+		<RestierNet9EntityFrameworkVersion>[9.*, 10.0.0)</RestierNet9EntityFrameworkVersion>
+		<RestierNet9SystemTextJsonVersion>[9.*, 10.0.0)</RestierNet9SystemTextJsonVersion>
+		<RestierNet9UserSecretsVersion>[9.*, 10.0.0)</RestierNet9UserSecretsVersion>
+		<RestierNet9AspNetCoreTestHostVersion>[9.*, 10.0.0)</RestierNet9AspNetCoreTestHostVersion>
+		<RestierNet10DependencyInjectionVersion>[10.*, 11.0.0)</RestierNet10DependencyInjectionVersion>
+		<RestierNet10EntityFrameworkVersion>[10.*, 11.0.0)</RestierNet10EntityFrameworkVersion>
+		<RestierNet10SystemTextJsonVersion>[10.*, 11.0.0)</RestierNet10SystemTextJsonVersion>
+		<RestierNet10UserSecretsVersion>[10.*, 11.0.0)</RestierNet10UserSecretsVersion>
+		<RestierNet10AspNetCoreTestHostVersion>[10.*, 11.0.0)</RestierNet10AspNetCoreTestHostVersion>
 	</PropertyGroup>
 
+	<ItemGroup Condition="'$(TargetFramework)' == 'net9.0'">
+		<PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="$(RestierNet9DependencyInjectionVersion)" PrivateAssets="All" />
+		<PackageReference Include="Microsoft.Extensions.Configuration.Abstractions" Version="$(RestierNet9UserSecretsVersion)" PrivateAssets="All" />
+		<PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="$(RestierNet9UserSecretsVersion)" PrivateAssets="All" />
+		<PackageReference Include="Microsoft.Extensions.FileProviders.Abstractions" Version="$(RestierNet9UserSecretsVersion)" PrivateAssets="All" />
+		<PackageReference Include="Microsoft.Extensions.FileProviders.Physical" Version="$(RestierNet9UserSecretsVersion)" PrivateAssets="All" />
+		<PackageReference Include="System.Text.Json" Version="$(RestierNet9SystemTextJsonVersion)" PrivateAssets="All" />
+	</ItemGroup>
+
+
 	<ItemGroup Condition=" $(IsTestProject) != 'true' AND $(IsSampleProject) != 'true'">
 		<PackageReference Include="Microsoft.SourceLink.GitHub" Version="8.*" PrivateAssets="All" />
+
 		<InternalsVisibleTo Include="$(AssemblyName.Replace('Microsoft.Restier.', 'Microsoft.Restier.Tests.')), $(StrongNamePublicKey)" />
 	</ItemGroup>
 
-	<ItemGroup Condition=" $(IsTestProject) == 'true' and $(IsSampleProject) != 'true'">
+	<ItemGroup Condition=" $(IsTestProject) == 'true' and $(IsSampleProject) != 'true' and $(IsTestSharedProject) != 'true'">
 		<PackageReference Include="coverlet.collector" Version="6.*" />
-		<PackageReference Include="FluentAssertions" Version="6.*" PrivateAssets="All" />
-		<PackageReference Include="FluentAssertions.Analyzers" Version="0.*" PrivateAssets="All" />
-		<PackageReference Include="MSTest" Version="4.*" />
-
-        <!-- Enable parallel test execution in MSTest 4 and later. -->
-        <AssemblyAttribute Include="Microsoft.VisualStudio.TestTools.UnitTesting.Parallelize">
-            <_Parameter1>Workers = 1</_Parameter1>
-            <_Parameter1_IsLiteral>true</_Parameter1_IsLiteral>
-            <_Parameter2>Scope = Microsoft.VisualStudio.TestTools.UnitTesting.ExecutionScope.MethodLevel</_Parameter2>
-            <_Parameter2_IsLiteral>true</_Parameter2_IsLiteral>
-        </AssemblyAttribute>
+		<PackageReference Include="AwesomeAssertions" Version="8.*" PrivateAssets="All" />
+		<PackageReference Include="AwesomeAssertions.Analyzers" Version="0.*" PrivateAssets="All" />
+		<PackageReference Include="xunit.v3" Version="3.*" />
+		<PackageReference Include="xunit.runner.visualstudio" Version="3.*" />
+		<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.*" />
+		<PackageReference Include="NSubstitute" Version="5.3.0"></PackageReference>
 	</ItemGroup>
 
 	<ItemGroup>

diff --git a/RESTier.slnx b/RESTier.slnx
@@ -0,0 +1,40 @@
+<Solution>
+  <Folder Name="/Solution Items/">
+    <File Path="NuGet.Config" />
+    <File Path="README.md" />
+    <File Path=".editorconfig" />
+    <File Path="Directory.Build.props" />
+    <File Path="dotnet-logo.png" />
+  </Folder>
+  <Folder Name="/src/" Id="02ea681e-c7d8-13c7-8484-4ac65e1b71e8">
+    <Project Path="src/Microsoft.Restier.Breakdance/Microsoft.Restier.Breakdance.csproj" />
+    <Project Path="src/Microsoft.Restier.Core/Microsoft.Restier.Core.csproj" />
+  </Folder>
+  <Folder Name="/src/EntityFramework/" Id="a290b16b-6f9e-4703-8c01-135831ad90df">
+    <Project Path="src/Microsoft.Restier.EntityFramework.Shared/Microsoft.Restier.EntityFramework.Shared.shproj" Id="83ad7aa8-9ed8-4b9f-966a-73ce9cae51c6" />
+    <Project Path="src/Microsoft.Restier.EntityFramework/Microsoft.Restier.EntityFramework.csproj" />
+    <Project Path="src/Microsoft.Restier.EntityFrameworkCore/Microsoft.Restier.EntityFrameworkCore.csproj" />
+  </Folder>
+  <Folder Name="/src/Samples/">
+    <Project Path="src/Microsoft.Restier.Samples.Northwind.AspNetCore/Microsoft.Restier.Samples.Northwind.AspNetCore.csproj" />
+    <Project Path="src/Microsoft.Restier.Samples.Postgres.AspNetCore/Microsoft.Restier.Samples.Postgres.AspNetCore.csproj" />
+  </Folder>
+  <Folder Name="/src/Web/" Id="bf61c3f1-7c7e-4515-8b51-14b374a034f9">
+    <Project Path="src/Microsoft.Restier.AspNetCore.Swagger/Microsoft.Restier.AspNetCore.Swagger.csproj" />
+    <Project Path="src/Microsoft.Restier.AspNetCore/Microsoft.Restier.AspNetCore.csproj" />
+  </Folder>
+  <Folder Name="/test/" Id="67e76b39-b345-4061-b1a8-31b95b6f83a8">
+    <Project Path="test/Microsoft.Restier.Tests.Core/Microsoft.Restier.Tests.Core.csproj" />
+    <Project Path="test/Microsoft.Restier.Tests.Shared/Microsoft.Restier.Tests.Shared.csproj" />
+  </Folder>
+  <Folder Name="/test/EntityFramework/" Id="b45d57df-5e57-4cf8-9ff8-86a03f39bb09">
+    <Project Path="test/Microsoft.Restier.Tests.EntityFramework/Microsoft.Restier.Tests.EntityFramework.csproj" />
+    <Project Path="test/Microsoft.Restier.Tests.EntityFrameworkCore/Microsoft.Restier.Tests.EntityFrameworkCore.csproj" />
+    <Project Path="test/Microsoft.Restier.Tests.Shared.EntityFramework/Microsoft.Restier.Tests.Shared.EntityFramework.csproj" />
+    <Project Path="test/Microsoft.Restier.Tests.Shared.EntityFrameworkCore/Microsoft.Restier.Tests.Shared.EntityFrameworkCore.csproj" />
+  </Folder>
+  <Folder Name="/test/Web/" Id="ae160b58-fb2d-4b9f-9357-8c7648381b95">
+    <Project Path="test/Microsoft.Restier.Tests.AspNetCore.Swagger/Microsoft.Restier.Tests.AspNetCore.Swagger.csproj" />
+    <Project Path="test/Microsoft.Restier.Tests.AspNetCore/Microsoft.Restier.Tests.AspNetCore.csproj" />
+  </Folder>
+</Solution>
diff --git a/docs/.DS_Store b/docs/.DS_Store
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -10,6 +10,8 @@ pages:
     - 'Method Authorization': 'server/method-authorization.md'
     - 'Interceptors': 'server/interceptors.md'
     - 'Model Building': 'server/model-building.md'
+    - 'Naming Conventions': 'server/naming-conventions.md'
+    - 'Optimistic Concurrency': 'server/concurrency.md'
 - Extending RESTier:
     - 'Temporal Types': 'extending-restier/temporal-types.md'
     - 'In-Memory Provider': 'extending-restier/in-memory-provider.md'

diff --git a/docs/msdocs/.DS_Store b/docs/msdocs/.DS_Store
diff --git a/docs/msdocs/build.sh b/docs/msdocs/build.sh
@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Ensure .NET global tools are on PATH
+export PATH="$PATH:$HOME/.dotnet/tools"
+
+# Check if docfx is available
+if ! command -v docfx &>/dev/null; then
+    echo "docfx not found. Installing as a .NET global tool..."
+    dotnet tool install -g docfx
+fi
+
+# Clean previous output to avoid stale file warnings
+rm -rf "$SCRIPT_DIR/_site"
+
+echo "Building docs..."
+docfx build "$SCRIPT_DIR/docfx.json" --output "$SCRIPT_DIR/_site"
+
+echo ""
+echo "Build complete. Output is in: $SCRIPT_DIR/_site"
+echo "To preview locally, run: docfx serve $SCRIPT_DIR/_site"
diff --git a/docs/msdocs/clients/dot-net-standard.md b/docs/msdocs/clients/dot-net-standard.md
diff --git a/docs/msdocs/clients/dot-net.md b/docs/msdocs/clients/dot-net.md
diff --git a/docs/msdocs/clients/typescript.md b/docs/msdocs/clients/typescript.md
diff --git a/docs/msdocs/contribution-guidelines.md b/docs/msdocs/contribution-guidelines.md
@@ -23,10 +23,7 @@ before you work on the pull request. After the RESTier team has reviewed this is
 to "accepting pull request", you can work on the code change.
 
 ### Prepare Tools
-[Atom](https://atom.io/) with package [atom-beautify](https://atom.io/packages/atom-beautify) and 
-[markdown-toc](https://atom.io/packages/markdown-toc) is recommended to edit the document. 
-[MarkdownPad](http://www.markdownpad.com/) can also be used to edit the document.<br />
-Visual Studio 2015 is recommended for code contribution.
+Visual Studio 2022 or later is recommended for code contribution. VS Code and JetBrains Rider also work well.
 
 ### Steps to create a pull request
 These are the recommended steps to create a pull request:<br />
@@ -36,28 +33,28 @@ These are the recommended steps to create a pull request:<br />
 3. Add a git remote to upstream for local repository with command _git remote add upstream 
 [https://github.com/OData/RESTier.git](https://github.com/OData/RESTier.git)_
 4. Make code changes and add test cases, refer Test specification section for more details about test
-5. Test the changed codes with one-click build and test script
+5. Build and test the changes with `dotnet build RESTier.slnx && dotnet test RESTier.slnx`
 6. Commit changed code to local repository with clear message
-7. Rebase the code to upstream via command _git pull --rebase upstream master_ and resolve conflicts 
+7. Rebase the code to upstream via command _git pull --rebase upstream main_ and resolve conflicts 
 if there is any then continue rebase via command _git pull --rebase continue_
 8. Push local commit to the forked repository
 9. Create pull request from forked repository Web console via comparing with upstream.
 10. Complete a Contributor License Agreement (CLA), refer below section for more details.
 11. Pull request will be reviewed by Microsoft OData team
 12. Address comments and revise code if necessary
 13. Commit the changes to local repository or amend existing commit via command _git commit --amend_
-14. Rebase the code with upstream again via command _git pull --rebase upstream master_ and resolve 
+14. Rebase the code with upstream again via command _git pull --rebase upstream main_ and resolve 
 conflicts if there is any then continue rebase via command _git pull --rebase continue_
-15. Test the changed codes with one-click build and test script again
+15. Build and test the changes again with `dotnet build RESTier.slnx && dotnet test RESTier.slnx`
 16. Push changes to the forked repository and use _--force_ option if existing commit is amended
 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 
+All tests need to be written with **xUnit v3**. Use **FluentAssertions** for assertions and **NSubstitute** for mocking. 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`.
+- **Project name correspondence** (`Microsoft.Restier.X` -> `Microsoft.Restier.Tests.X`). For instance, all the test code of the `Microsoft.Restier.Core` project should be placed in the `Microsoft.Restier.Tests.Core` 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.Tests.Core/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.Tests.Core.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.
 - **Integration and scenario tests**. Those tests usually involve multiple modules and have some specific scenarios. They should be placed separately in `X.Tests/IntegrationTests` and `X.Tests/ScenarioTests`. There is no hard requirement of the folder structure for those tests. But they should be organized logically and systematically as possible.