Version 9 - Epic

[fiseni]

This issue will act as an Epic and lists all planned changes for version 9. I'll keep updating the list as we work toward the new version.

Version 9 will focus on performance improvement, specifically reducing allocations and the memory footprint of using specifications. We'll try to avoid breaking changes for the public API surface, but the internals will be refactored. Folks who have been relying on the internals or have custom extensions might be affected by these changes.

Version 9.0.0

• Update TFMs #438
• Update Specification constructors as public. #413
• Remove IEntity #414
• Reduce the Specification size. Set the initial state to null. #415
• Refactor Take/Skip state to non-nullable int. Define the default value to -1. #416
• Remove the Evaluator and Validator state from Specifications. #417
• Remove the state for the Query builder. Update it as a calculated property. #418
• Improve the specification builders. Select/SelectMany should be applied in the end. #419
• Add IsChainDiscarded thread-static field. #420
• Improve the C# implementation of the Like operator. #421
• Improve the Search in-memory evaluator. Implement a custom iterator and reduce allocations. #422
• Refactor Search validator to allocation-free implementation. #424
• Improve the Search EF evaluator. Reduce allocations. #423
• Refactor Include evaluator. Implement caching. #425
• Update expression constructs. Reduce size. #426
• Remove obsolete API #346
• Add Readme file in the NuGet package #385

Community requests:

• Add TagWith feature #428
• Add EF IgnoreAutoIncludes support #436
• Fix EnableCache to not append a dash if you pass in no args #412
• Why do the Update and Delete not returning anything? #361

Breaking Changes

The "standard" use of the library remains fairly intact.

• The obsolete GetBySpec repository methods are removed.
• The IEntity interface is removed.
• The Select/SelectMany are applied at the end of the chain or in a separate Query clause. These extension methods return void and no further chaining is possible.

In this version, we refactored the internals and the building blocks significantly. The "advanced" use cases are affected by these changes. Users who have custom extensions or have been relying on the internals need to migrate accordingly.

• The expression collections no longer are initialized to a new List<T> by default and will return Enumerable.Empty<T> if empty.
• The default value for Take and Skip properties no longer is null. They're updated to non nullable int type with a default value of -1.
• The specification constructors no longer accept IInMemorySpecificationEvaluator and ISpecificationValidator parameters. The properties are still defined as virtual and can be overridden.
• The builder infrastructure is refactored to accommodate better flow for specs with projections. All extensions should be written for both ISpecificationBuilder<T> and ISpecificationBuilder<T, TResult> builders.
• The OrderedSpecificationBuilder and CacheSpecificationBuilder are removed.
• The in-memory SearchEvaluator is renamed to SearchMemoryEvaluator.
• The IncludeEvaluator.Default and IncludeEvaluator.Cached singleton instances are removed. Instead, use the IncludeEvaluator.Instance.
• The SpecificationEvaluator no longer accepts bool cacheEnabled parameter. The caching is applied by default wherever necessary.
• The EntityType, PropertyType, and PreviousPropertyType are removed from IncludeExpressionInfo.
• The Update and Delete repository methods return Task<int> (the affected rows).

---

Version 9.0.1

• Re-add the inheritance in the builders Add converter from ISpecificationBuilder<T, TResult> to ISpecificationBuilder<T> #456

---

Version 9.1.0

• Add WithProjectionOf feature Allow combination of Specification with different projections #389
• Fix type inference for ThenInclude with casting InvalidCastException when using ThenInclude on IReadOnlyCollection #463

Breaking Changes

The PreviousPropertyType is re-added to IncludeExpressionInfo. The constructors of IncludeExpressionInfo are modified.

---

Version 9.2.0

• Add support for multiple TagWith multiple TagWith support? #468

---

Version 9.3.0

• Use OneOrMany for all internal collections #506
• Avoid List allocation for PostProcessingAction. #501
• Update dependencies. #526

Breaking Changes

• Rename TagWithEvaluator to QueryTagEvaluator #515
• Redefine WithProjectionOf as an extension to Specification instead of ISpecification #516

---

Version 9.3.1

• Fix allocations of an unreachable fallback code #528

---

[neozhu]

@fiseni @ardalis
It looks like NuGet hasn't been updated to the latest 9.0 version yet. Would it be possible to release it?

[vchirikov]

Hi @fiseni / @ardalis first of all thanks for your work!
NuGet api key is expired:
https://github.com/ardalis/Specification/actions/runs/13812184362/job/38636126255#step:7:10

[fiseni]

Yeah we're aware of it. @ardalis will update the API key today and we'll push it.

[ardalis]

It's live! https://www.nuget.org/packages/Ardalis.Specification

[park-bord]

would adding back EntityType and PropertyType to IncludeExpressionInfo be considered?

EDIT: actually, this can be easily retrieved from the lambdaexpression that is still available, im pretty sure. my application has a row-level security feature which inserts filters where appropriate for a given user and these properties were being used but i think i can get by with just looking at the current lambda. will test :)

[fiseni]

Hey @park-bord

You can find the rationale for this change in the following issue #426. I explained the details there.

The EntityType is already available as the T generic parameter, so we don't need to store it. The PropertyType is already contained in the lambda expression, it's the same as LambdaExpression.ReturnType. The expressions are applied sequentially in the evaluator, so the PreviousPropertyType can be easily deduced during the evaluation. By removing these properties we'll save 24 bytes per instance.

In version 9.1.0, the PreviousPropertyType is re-added. However, we don't plan to add back the EntityType and PropertyType, as they are redundant data and can be easily retrieved by other means.