Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,8 @@ jobs:
runs-on: ubuntu-latest
permissions:
contents: read
# NuGet Trusted Publishing: the job's OIDC token is exchanged for a short-lived API key.
id-token: write
needs: [build, test]
# This environment gates the publish behind whatever protection rules are configured for it in
# the repo's Settings -> Environments (e.g. required reviewers). GitHub auto-creates an environment
Expand All @@ -109,7 +111,15 @@ jobs:
pattern: nupkg-*
path: artifacts
merge-multiple: true
# nuget.org's trusted publishing policy for this repository names this workflow (release.yml) and
# the nuget-release environment, so renaming either one stops the login here, before any push.
# The key it returns lives one hour: the push right after it is the only step that uses it.
- name: Log in to nuget.org
id: nuget
uses: NuGet/login@8d196754b4036150537f80ac539e15c2f1028841 # v1.2.0
with:
user: ${{ secrets.NUGET_USER }}
- name: Push to NuGet.org
env:
NUGET_KEY: ${{ secrets.nuget_key }}
NUGET_KEY: ${{ steps.nuget.outputs.NUGET_API_KEY }}
run: dotnet nuget push "artifacts/*.nupkg" --skip-duplicate -k "$NUGET_KEY" -s https://api.nuget.org/v3/index.json
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,8 +95,8 @@ native engine as well, reference it yourself; the two implement the same contrac

This package is the **Entity Framework Core implementation** of those contracts. It translates a single
`QueryOptions<TEntity>` into an EF `IQueryable` — applying, in order, custom *before* hooks, the
specification and predicate filter, eager `Include`s, sortings (server-side / EF-translatable),
`AsNoTracking`, `IgnoreQueryFilters`, query tags and custom *after* hooks — and returns `PagedResult<T>`
specification and predicate filter, eager `Include`s (shaped ones through a filtered include), sortings
(server-side / EF-translatable, nulls placed first or last on request), `Skip`/`Take`, `AsNoTracking`, `IgnoreQueryFilters`, query tags and custom *after* hooks — and returns `PagedResult<T>`
from paged reads. The relational providers also carry a parameterized raw-SQL executor (functions and
stored procedures, always via `DbParameter`).

Expand Down
52 changes: 52 additions & 0 deletions Repository.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ An entity is a plain class that implements `IEntity<TKey>`. The key is exposed t

```csharp
using System;
using System.Collections.Generic;
using eQuantic.Core.Data.Repository;

public enum OrderStatus { Pending, Paid, Cancelled }
Expand All @@ -34,13 +35,24 @@ public class OrderData : IEntity<Guid>
public decimal Total { get; set; }
public OrderStatus Status { get; set; }
public DateTime CreatedAt { get; set; }
public DateTime? ShippedAt { get; set; }

public Guid CustomerId { get; set; }
public CustomerData Customer { get; set; } = default!;

public List<OrderLineData> Lines { get; set; } = [];

public Guid GetKey() => Id;
public void SetKey(Guid key) => Id = key;
}

public class OrderLineData
{
public Guid Id { get; set; }
public Guid OrderId { get; set; }
public string Status { get; set; } = string.Empty;
public DateTime AddedAt { get; set; }
}
```

## 2. The DbContext
Expand Down Expand Up @@ -180,6 +192,46 @@ public record OrderSummary(Guid Id, decimal Total, string Customer);

Every method has a synchronous twin on the queryable repository (`GetPaged`, `Get`, `Count`, `Sum`, …).

### Read shapes: a page without its total, nulls placed, related rows chosen

`QueryOptions` (eQuantic.Core.Data.Abstractions 7.0) also says which rows a read returns, and these
repositories honour it as the eQuantic.Core.Data engines do:

```csharp
// rows 11 to 20 of an order, with no count run (pair Skip/Take with an order):
IEnumerable<OrderData> second = await orders.GetAllAsync(
new QueryOptions<OrderData>().OrderByDescending(o => o.CreatedAt).Skip(10).Take(10));

// nulls first or last whatever the store's default (PostgreSQL puts them last ascending, the others first):
IEnumerable<OrderData> byShipping = await orders.GetAllAsync(
new QueryOptions<OrderData>().OrderBy(o => o.ShippedAt, NullsOrder.Last));

// each order with only its three newest lines that are not cancelled, newest first:
IEnumerable<OrderData> recent = await orders.GetAllAsync(new QueryOptions<OrderData>()
.Include(o => o.Lines, lines => lines
.Where(l => l.Status != "cancelled")
.OrderByDescending(l => l.AddedAt)
.Take(3)));
```

- `Skip`/`Take` shape the rows a read returns. `CountAsync`, `AnyAsync`, `AllAsync`, `SumAsync` and
`GetPagedAsync` do not return rows that way, so they refuse them with a `NotSupportedException` rather than
count a page or page twice. With `GetFirstAsync` and `GetSingleAsync` the window applies before the read's own
limit.
- A placement of nulls on a relational store becomes a leading "is null" key. MongoDB and Cosmos DB sort nulls as
the smallest value, so first ascending and last descending are a plain sort there. Cosmos DB orders by
document paths only, so it refuses the other two placements before sending anything.
- A shaped include is Entity Framework's filtered include (`Include(o => o.Lines.Where(…).OrderBy(…).Take(3))`).
As Entity Framework documents for filtered includes, a tracking read in a context that already tracks some
of those lines fixes them up into the collection too. Read with `NoTracking()`, or in a fresh context, when the
collection must hold exactly the shape.

The other additions of 7.0 are capabilities a repository opts into (`IUpsertRepository`,
`IReturningUpdateRepository`, `IPartialModifyRepository`, `IDistinctReadRepository`, `ILockingUnitOfWork`) and
the native engine's modeling attributes (`[EnumType]`, `[StoreGenerated]`, JSON members). These repositories do
not implement them: test for the interface before you use one, and map columns through Entity Framework's own
model configuration.

## 6. Specifications

Encapsulate a reusable rule as an `ISpecification<T>` (base class `Specification<T>`).
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,24 +4,24 @@
<PropertyGroup>
<Description>Core Data library for Entity Framework and Azure Cosmos DB</Description>
<AssemblyTitle>eQuantic.Core.Data.EntityFramework.CosmosDb</AssemblyTitle>
<Version>10.5.0.0</Version>
<Version>10.6.0.0</Version>
<TargetFramework>net10.0</TargetFramework>
<AssemblyName>eQuantic.Core.Data.EntityFramework.CosmosDb</AssemblyName>
<PackageId>eQuantic.Core.Data.EntityFramework.CosmosDb</PackageId>
<PackageTags>eQuantic;Core;Data;Library;Repository;Pattern;CosmosDB;Azure</PackageTags>
<PackageReleaseNotes>Entity ignorant persistance with Repository Pattern for Entity
Framework</PackageReleaseNotes>

<AssemblyVersion>10.5.0.0</AssemblyVersion>
<FileVersion>10.5.0.0</FileVersion>
<AssemblyVersion>10.6.0.0</AssemblyVersion>
<FileVersion>10.6.0.0</FileVersion>

<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
</PropertyGroup>

<ItemGroup>
<PackageReference Include="eQuantic.Core" Version="1.8.4" />
<PackageReference Include="eQuantic.Core.Data.Abstractions" Version="6.9.0" />
<PackageReference Include="eQuantic.Core.Data.Abstractions" Version="7.0.0" />
<PackageReference Include="Microsoft.EntityFrameworkCore" Version="10.0.10" />
<PackageReference Include="Microsoft.EntityFrameworkCore.Cosmos" Version="10.0.10" />
</ItemGroup>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,24 +4,24 @@
<PropertyGroup>
<Description>Core Data library for Entity Framework and Azure Cosmos DB</Description>
<AssemblyTitle>eQuantic.Core.Data.EntityFramework.CosmosDb</AssemblyTitle>
<Version>8.6.0.0</Version>
<Version>8.7.0.0</Version>
<TargetFramework>net8.0</TargetFramework>
<AssemblyName>eQuantic.Core.Data.EntityFramework.CosmosDb</AssemblyName>
<PackageId>eQuantic.Core.Data.EntityFramework.CosmosDb</PackageId>
<PackageTags>eQuantic;Core;Data;Library;Repository;Pattern;CosmosDB;Azure</PackageTags>
<PackageReleaseNotes>Entity ignorant persistance with Repository Pattern for Entity
Framework</PackageReleaseNotes>

<AssemblyVersion>8.6.0.0</AssemblyVersion>
<FileVersion>8.6.0.0</FileVersion>
<AssemblyVersion>8.7.0.0</AssemblyVersion>
<FileVersion>8.7.0.0</FileVersion>

<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
</PropertyGroup>

<ItemGroup>
<PackageReference Include="eQuantic.Core" Version="1.8.4" />
<PackageReference Include="eQuantic.Core.Data.Abstractions" Version="6.9.0" />
<PackageReference Include="eQuantic.Core.Data.Abstractions" Version="7.0.0" />
<PackageReference Include="Microsoft.EntityFrameworkCore" Version="8.0.29" />
<PackageReference Include="Microsoft.EntityFrameworkCore.Cosmos" Version="8.0.29" />
</ItemGroup>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,24 +4,24 @@
<PropertyGroup>
<Description>Core Data library for Entity Framework and Mongo DB</Description>
<AssemblyTitle>eQuantic.Core.Data.EntityFramework.MongoDb</AssemblyTitle>
<Version>10.5.0.0</Version>
<Version>10.6.0.0</Version>
<TargetFramework>net10.0</TargetFramework>
<AssemblyName>eQuantic.Core.Data.EntityFramework.MongoDb</AssemblyName>
<PackageId>eQuantic.Core.Data.EntityFramework.MongoDb</PackageId>
<PackageTags>eQuantic;Core;Data;Library;Repository;Pattern;MongoDB</PackageTags>
<PackageReleaseNotes>Entity ignorant persistance with Repository Pattern for Entity
Framework</PackageReleaseNotes>

<AssemblyVersion>10.5.0.0</AssemblyVersion>
<FileVersion>10.5.0.0</FileVersion>
<AssemblyVersion>10.6.0.0</AssemblyVersion>
<FileVersion>10.6.0.0</FileVersion>

<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
</PropertyGroup>

<ItemGroup>
<PackageReference Include="eQuantic.Core" Version="1.8.4" />
<PackageReference Include="eQuantic.Core.Data.Abstractions" Version="6.9.0" />
<PackageReference Include="eQuantic.Core.Data.Abstractions" Version="7.0.0" />
<PackageReference Include="Microsoft.EntityFrameworkCore" Version="10.0.10" />
<PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="10.0.10">
<PrivateAssets>all</PrivateAssets>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,24 +4,24 @@
<PropertyGroup>
<Description>Core Data library for Entity Framework and Mongo DB</Description>
<AssemblyTitle>eQuantic.Core.Data.EntityFramework.MongoDb</AssemblyTitle>
<Version>8.6.0.0</Version>
<Version>8.7.0.0</Version>
<TargetFramework>net8.0</TargetFramework>
<AssemblyName>eQuantic.Core.Data.EntityFramework.MongoDb</AssemblyName>
<PackageId>eQuantic.Core.Data.EntityFramework.MongoDb</PackageId>
<PackageTags>eQuantic;Core;Data;Library;Repository;Pattern;MongoDB</PackageTags>
<PackageReleaseNotes>Entity ignorant persistance with Repository Pattern for Entity
Framework</PackageReleaseNotes>

<AssemblyVersion>8.6.0.0</AssemblyVersion>
<FileVersion>8.6.0.0</FileVersion>
<AssemblyVersion>8.7.0.0</AssemblyVersion>
<FileVersion>8.7.0.0</FileVersion>

<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
</PropertyGroup>

<ItemGroup>
<PackageReference Include="eQuantic.Core" Version="1.8.4" />
<PackageReference Include="eQuantic.Core.Data.Abstractions" Version="6.9.0" />
<PackageReference Include="eQuantic.Core.Data.Abstractions" Version="7.0.0" />
<PackageReference Include="Microsoft.EntityFrameworkCore" Version="8.0.29" />
<PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="8.0.29">
<PrivateAssets>all</PrivateAssets>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,21 +4,21 @@
<PropertyGroup>
<Description>Core Data library for Entity Framework and MySQL</Description>
<AssemblyTitle>eQuantic.Core.Data.EntityFramework.MySql</AssemblyTitle>
<Version>10.4.0.0</Version>
<Version>10.5.0.0</Version>
<TargetFramework>net10.0</TargetFramework>
<AssemblyName>eQuantic.Core.Data.EntityFramework.MySql</AssemblyName>
<PackageId>eQuantic.Core.Data.EntityFramework.MySql</PackageId>
<PackageTags>eQuantic;Core;Data;Library;Repository;Pattern;SQL</PackageTags>
<PackageReleaseNotes>Entity ignorant persistance with Repository Pattern for Entity
Framework</PackageReleaseNotes>

<AssemblyVersion>10.4.0.0</AssemblyVersion>
<FileVersion>10.4.0.0</FileVersion>
<AssemblyVersion>10.5.0.0</AssemblyVersion>
<FileVersion>10.5.0.0</FileVersion>
</PropertyGroup>

<ItemGroup>
<PackageReference Include="eQuantic.Core" Version="1.8.4" />
<PackageReference Include="eQuantic.Core.Data.Abstractions" Version="6.9.0" />
<PackageReference Include="eQuantic.Core.Data.Abstractions" Version="7.0.0" />
<PackageReference Include="Microsoft.EntityFrameworkCore" Version="10.0.10" />
<PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="10.0.10">
<PrivateAssets>all</PrivateAssets>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,21 +4,21 @@
<PropertyGroup>
<Description>Core Data library for Entity Framework and MySQL</Description>
<AssemblyTitle>eQuantic.Core.Data.EntityFramework.MySql</AssemblyTitle>
<Version>8.5.0.0</Version>
<Version>8.6.0.0</Version>
<TargetFramework>net8.0</TargetFramework>
<AssemblyName>eQuantic.Core.Data.EntityFramework.MySql</AssemblyName>
<PackageId>eQuantic.Core.Data.EntityFramework.MySql</PackageId>
<PackageTags>eQuantic;Core;Data;Library;Repository;Pattern;SQL</PackageTags>
<PackageReleaseNotes>Entity ignorant persistance with Repository Pattern for Entity
Framework</PackageReleaseNotes>

<AssemblyVersion>8.5.0.0</AssemblyVersion>
<FileVersion>8.5.0.0</FileVersion>
<AssemblyVersion>8.6.0.0</AssemblyVersion>
<FileVersion>8.6.0.0</FileVersion>
</PropertyGroup>

<ItemGroup>
<PackageReference Include="eQuantic.Core" Version="1.8.4" />
<PackageReference Include="eQuantic.Core.Data.Abstractions" Version="6.9.0" />
<PackageReference Include="eQuantic.Core.Data.Abstractions" Version="7.0.0" />
<PackageReference Include="Microsoft.EntityFrameworkCore" Version="8.0.29" />
<PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="8.0.29">
<PrivateAssets>all</PrivateAssets>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,21 +4,21 @@
<PropertyGroup>
<Description>Core Data library for Entity Framework and PostgreSQL</Description>
<AssemblyTitle>eQuantic.Core.Data.EntityFramework.PostgreSql</AssemblyTitle>
<Version>10.4.0.0</Version>
<Version>10.5.0.0</Version>
<TargetFramework>net10.0</TargetFramework>
<AssemblyName>eQuantic.Core.Data.EntityFramework.PostgreSql</AssemblyName>
<PackageId>eQuantic.Core.Data.EntityFramework.PostgreSql</PackageId>
<PackageTags>eQuantic;Core;Data;Library;Repository;Pattern;SQL</PackageTags>
<PackageReleaseNotes>Entity ignorant persistance with Repository Pattern for Entity
Framework</PackageReleaseNotes>

<AssemblyVersion>10.4.0.0</AssemblyVersion>
<FileVersion>10.4.0.0</FileVersion>
<AssemblyVersion>10.5.0.0</AssemblyVersion>
<FileVersion>10.5.0.0</FileVersion>
</PropertyGroup>

<ItemGroup>
<PackageReference Include="eQuantic.Core" Version="1.8.4" />
<PackageReference Include="eQuantic.Core.Data.Abstractions" Version="6.9.0" />
<PackageReference Include="eQuantic.Core.Data.Abstractions" Version="7.0.0" />
<PackageReference Include="Microsoft.EntityFrameworkCore" Version="10.0.10" />
<PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="10.0.10">
<PrivateAssets>all</PrivateAssets>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,21 +4,21 @@
<PropertyGroup>
<Description>Core Data library for Entity Framework and PostgreSQL</Description>
<AssemblyTitle>eQuantic.Core.Data.EntityFramework.PostgreSql</AssemblyTitle>
<Version>8.5.0.0</Version>
<Version>8.6.0.0</Version>
<TargetFramework>net8.0</TargetFramework>
<AssemblyName>eQuantic.Core.Data.EntityFramework.PostgreSql</AssemblyName>
<PackageId>eQuantic.Core.Data.EntityFramework.PostgreSql</PackageId>
<PackageTags>eQuantic;Core;Data;Library;Repository;Pattern;SQL</PackageTags>
<PackageReleaseNotes>Entity ignorant persistance with Repository Pattern for Entity
Framework</PackageReleaseNotes>

<AssemblyVersion>8.5.0.0</AssemblyVersion>
<FileVersion>8.5.0.0</FileVersion>
<AssemblyVersion>8.6.0.0</AssemblyVersion>
<FileVersion>8.6.0.0</FileVersion>
</PropertyGroup>

<ItemGroup>
<PackageReference Include="eQuantic.Core" Version="1.8.4" />
<PackageReference Include="eQuantic.Core.Data.Abstractions" Version="6.9.0" />
<PackageReference Include="eQuantic.Core.Data.Abstractions" Version="7.0.0" />
<PackageReference Include="Microsoft.EntityFrameworkCore" Version="8.0.29" />
<PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="8.0.29">
<PrivateAssets>all</PrivateAssets>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,20 @@
<PropertyGroup>
<Description>Shared relational implementation for eQuantic Core Data Entity Framework providers</Description>
<AssemblyTitle>eQuantic.Core.Data.EntityFramework.Relational</AssemblyTitle>
<Version>4.3.0.0</Version>
<Version>4.4.0.0</Version>
<TargetFrameworks>net8.0;net10.0</TargetFrameworks>
<AssemblyName>eQuantic.Core.Data.EntityFramework.Relational</AssemblyName>
<PackageId>eQuantic.Core.Data.EntityFramework.Relational</PackageId>
<PackageTags>eQuantic;Core;Data;Library;Repository;Pattern;SQL;Relational</PackageTags>
<PackageReleaseNotes>Shared relational base used by the SqlServer, PostgreSql and MySql providers</PackageReleaseNotes>

<AssemblyVersion>4.3.0.0</AssemblyVersion>
<FileVersion>4.3.0.0</FileVersion>
<AssemblyVersion>4.4.0.0</AssemblyVersion>
<FileVersion>4.4.0.0</FileVersion>
</PropertyGroup>

<ItemGroup>
<PackageReference Include="eQuantic.Core" Version="1.8.4" />
<PackageReference Include="eQuantic.Core.Data.Abstractions" Version="6.9.0" />
<PackageReference Include="eQuantic.Core.Data.Abstractions" Version="7.0.0" />
</ItemGroup>

<ItemGroup Condition=" '$(TargetFramework)' == 'net8.0' ">
Expand Down
Loading
Loading