EasyCore.Invocation 8.0.1

🔗 EasyCore.Invocation

EasyCore.Invocation is a Castle DynamicProxy-based method invocation pipeline. Apply custom IInvocation wrappers with attributes for before / after, try / catch / finally, retry, cache short-circuit, and argument / return mutation — no business base class required. Place attributes on service interfaces / classes / methods (Castle proxies) or directly on MVC Controllers / Actions (same IInvocation via IFilterFactory on the attribute — no global filter registration).

<p align="center"> <img src="https://raw.githubusercontent.com/RockyWang0521/EasyCore.Invocation/master/png/EasyCoreLogo.png" alt="EasyCore Logo" width="120" /> </p>

---

🌍 Language

• Chinese: README.md
• English (this document)

---

📚 Table of Contents

Part I — Overview

• 1. Positioning
• 2. Architecture & Call Chain
• 3. Repository Layout
• 4. Installation

Part II — Getting Started

• 5. Quick Start
• 6. Core APIs
• 7. InvocationContext
• 8. Attribute Discovery & Order

Part III — Capabilities & DI

• 9. Short-Circuit / Retry / Mutation / Exceptions
• 10. Return Types (Sync + Async)
• 11. DI Registration
• 12. InvocationOptions
• 13. Auto-Discovery Rules
• 14. Interface Proxy vs Class Proxy

Part IV — Limits & Practice

• 15. Castle Limitations
• 16. Demo Projects
• 17. Production Checklist
• 18. FAQ
• 19. License

---

1. 🎯 Positioning

Pain point	EasyCore.Invocation approach
Hand-written AOP / decorator boilerplate	[Audit] + IInvocation + await next()
Mistaken for ASP.NET Filters	Not a Filter — pure Castle proxy pipeline
Forced base class / marker interface	Plain business types work as-is
Unclear attribute scope	Interface / class / method placement — type-level hits all members; method-level is precise; multi-interface attrs stay scoped
Want the same AOP on Controllers / Actions	Put the attribute on the API: IFilterFactory reuses IInvocation — no hand-written global Filter
Awkward return-type handling	void / sync / Task / Task<T> / ValueTask / ValueTask<T>
Manual proxy registration per service	EasyCoreInvocation() auto-discovers and injects
Painful class proxies	Prefer interface proxies; impl methods need not be virtual

Three core concepts

Concept	Role
🏷️ InvocationAttribute	Declares which IInvocation to apply
🧩 IInvocation	Fully surrounds the call via await next()
🔌 EasyCoreInvocation()	Scans attributes and auto-registers / injects proxies

---

2. 🏗️ Architecture & Call Chain

2.1 Component diagram

2.2 Call sequence

Controller / Caller
        │
        ▼
   Castle Proxy  (interface preferred)
        │
        ▼
InvocationAsyncInterceptor
        │
        ▼
 DescriptorProvider (merge attrs → Order sort, cached)
        │
        ▼
 Pipeline: nested next
   Audit → Retry → Cache → …
        │
        ▼
   Business method (UserService)

---

3. 📁 Repository Layout

EasyCore.Invocation/
├── src/EasyCore.Invocation/            # Packable library (MIT)
│   ├── Abstractions/                     # IInvocation / Context / Delegate
│   ├── Attributes/                     # InvocationAttribute / OfT
│   ├── AspNetCore/                     # InvocationAttribute → IFilterFactory (API placement)
│   ├── Descriptors/                    # Discovery + ConcurrentDictionary cache
│   ├── Discovery/                      # Assembly scan (auto proxy registration)
│   ├── Interceptors/                   # Castle interceptor (internal)
│   ├── Proxy/                          # InvocationProxyFactory
│   ├── DependencyInjection/            # EasyCoreInvocation / Invocation / InvocationService
│   ├── Options/                        # InvocationOptions
│   └── Internal/                       # Pipeline / ReturnTypeHelper / MethodMappingCache
├── demo/WebApp.Invocation/             # Web API + Swagger (five placement demos)
│   ├── Attributes/                     # Audit / Cache / Retry
│   ├── Invocations/
│   ├── Services/                       # Interface type / class / method / iface method / multi-iface
│   └── Controllers/                    # A–E + /api/demo guide
├── tests/EasyCore.Invocation.Tests/    # xUnit + FluentAssertions (54+)
├── docs/svg/                           # README diagrams (no Mermaid)
├── png/EasyCoreLogo.png
├── README.md / README.en.md
└── LICENSE

Folders are organizational only; the public namespace stays EasyCore.Invocation.

Package / project	Role	Required
EasyCore.Invocation	Core library	✅
demo/WebApp.Invocation	Swagger demo (five placements)	Sample
tests/EasyCore.Invocation.Tests	Unit tests	Dev

---

4. 📦 Installation

dotnet add package EasyCore.Invocation

Item	Value
TFMs	net6.0 / net7.0 / net8.0
Dependencies	Castle.Core.AsyncInterceptor 2.1.0, ME DI / Options 8.0.0
License	MIT

---

5. ⚡ Quick Start

5.1 Register (one line)

services.EasyCoreInvocation();

// Optional: pin wrapper lifetime (independent; explicit wins)
services.Invocation<AuditInvocation>(ServiceLifetime.Singleton);
services.Invocation<CacheInvocation>(ServiceLifetime.Singleton);

5.2 Custom attribute + Invocation

public sealed class AuditAttribute : InvocationAttribute<AuditInvocation>
{
}

public sealed class AuditInvocation : IInvocation
{
    public async ValueTask<object?> InvokeAsync(
        InvocationContext context,
        InvocationDelegate next)
    {
        Console.WriteLine($"Before {context.MethodName}");
        try
        {
            var result = await next();
            Console.WriteLine($"After {context.MethodName}");
            return result;
        }
        catch (Exception ex)
        {
            Console.WriteLine(ex.Message);
            throw;
        }
        finally
        {
            Console.WriteLine($"Finally {context.MethodName}");
        }
    }
}

5.3 Business method (where to put attributes)

Placement	Hits	Mechanism
Interface type [Audit] interface IUserService	All methods on that interface	Castle interface proxy
Interface method [Audit] Task Foo()	Only that method	Castle interface proxy
Class [Audit] class UserService	All methods on that class	Castle proxy
Impl method [Cache] Task GetAsync()	Only that method	Castle proxy
Controller class [Audit] class XxxController	All actions on that controller	IFilterFactory → same IInvocation
Action method [Audit] IActionResult Foo()	Only that action	IFilterFactory → same IInvocation
AppService contract [Audit] interface IOrderAppService	Actions mapped from that contract	MVC convention merges interface attrs → IFilterFactory
AppService contract method [Cache] Task GetOrderAsync()	Only that action	MVC convention merges interface attrs → IFilterFactory

// EasyCoreAppService dynamic API — attributes on the contract only
[Audit]
public interface IOrderAppService
{
    Task<string> GetOrderAsync(int id);
}

public class OrderAppService : EasyCoreAppService, IOrderAppService
{
    public Task<string> GetOrderAsync(int id) => Task.FromResult($"order-{id}");
}

builder.Services.EasyCoreDynamicApi();
builder.Services.EasyCoreInvocation();
// GET /api/Order/GetOrderAsync?id=1 → [Audit] in console

// Service (Castle proxy)
[Audit]
public interface IUserService
{
    Task CreateAsync();
    Task<string> GetNameAsync(int id);
}

public sealed class UserService : IUserService
{
    public Task CreateAsync() => Task.CompletedTask;

    // Method-level: only GetNameAsync uses Cache
    [Cache]
    public Task<string> GetNameAsync(int id) => Task.FromResult($"user-{id}");
}

// API-level: put attributes on the controller / action (no AddControllersAsServices / global Filter)
[ApiController]
[Route("api/hello")]
[Audit] // all actions on this controller
public sealed class HelloController : ControllerBase
{
    [HttpGet]
    public IActionResult Get() => Ok("hello");

    [HttpGet("cached")]
    [Cache]
    public IActionResult Cached() => Ok("cached");
}

⚠️ Resolve service interfaces from DI; do not new UserService().
⚠️ Controller attributes run through IFilterFactory (still your IInvocation — not a separate Filter codebase).
⚠️ Multi-await next() retry fits service methods best; MVC action next is typically once-only.

---

6. 🧩 Core APIs

6.1 InvocationDelegate

public delegate ValueTask<object?> InvocationDelegate();

Represents the next wrapper or the original method.

6.2 IInvocation

public interface IInvocation
{
    ValueTask<object?> InvokeAsync(InvocationContext context, InvocationDelegate next);
}

Do not split into Before/After/Exception — surround the call in one method with try/catch/finally + await next().

6.3 InvocationAttribute

[AttributeUsage(
    AttributeTargets.Class | AttributeTargets.Method | AttributeTargets.Interface,
    AllowMultiple = true,
    Inherited = true)]
public class InvocationAttribute : Attribute, IFilterFactory, IOrderedFilter
{
    public InvocationAttribute(Type invocationType); // non-abstract IInvocation implementor
    public Type InvocationType { get; }
    public int Order { get; set; } // lower = outer; same Order keeps declaration order
    // CreateInstance → runs the same IInvocation on MVC Controller/Action
}

6.4 InvocationAttribute<TInvocation>

public abstract class InvocationAttribute<TInvocation> : InvocationAttribute
    where TInvocation : class, IInvocation
{
    protected InvocationAttribute() : base(typeof(TInvocation)) { }
}

public sealed class AuditAttribute : InvocationAttribute<AuditInvocation> { }

---

7. 🧾 InvocationContext

Each proxied call gets a mutable context:

Member	Meaning
ServiceProvider	Current scope DI
Proxy	Castle proxy instance
Target	Real business object
Method	Implementation method (preferred)
Arguments	Castle argument array (mutable, visible to original method)
ReturnValue	Readable / writable result
Exception	Last exception if any
CancellationToken	Detected from args, else None
Items	Per-call shared bag
TargetType / MethodName / Parameters	Convenience read-only props
GetArgument<T>(int\|string)	Read arguments
GetRequiredService<T>\|Type	Resolve from DI

public async ValueTask<object?> InvokeAsync(InvocationContext context, InvocationDelegate next)
{
    var id = context.GetArgument<int>("id");
    var logger = context.GetRequiredService<ILogger<AuditInvocation>>();
    context.Arguments[0] = id + 1;
    var result = await next();
    return result + "!";
}

---

8. 🔍 Attribute Discovery & Order

8.1 Merge order

interface type attrs → interface method attrs → class attrs → implementation method attrs

• Interface type attributes apply only to methods that belong to that interface.
• Class attributes apply to all methods on the class.

Then sort by Order ascending; same Order keeps stable discovery order.

Toggles: EnableInterfaceAttributes / EnableClassAttributes / EnableMethodAttributes — see InvocationOptions.

8.2 Nesting

[Audit(Order = 0)]
[Transaction(Order = 10)]
[Retry(Order = 20)]
Task CreateAsync();

Audit before
  Transaction before
    Retry before
      original method
    Retry after
  Transaction after
Audit after

Descriptors are cached in a ConcurrentDictionary (including generic method signatures).

---

9. 🔁 Short-Circuit / Retry / Mutation / Exceptions

9.1 Short-circuit

public ValueTask<object?> InvokeAsync(InvocationContext context, InvocationDelegate next)
    => ValueTask.FromResult<object?>(_cache.Get(key)); // do not call next

9.2 Retry

for (var i = 0; i < 3; i++)
{
    try { return await next(); }
    catch when (i < 2) { /* retry */ }
}

next may be called multiple times.

9.3 Mutate args / return

context.Arguments[0] = "mutated";
var result = await next();
return result + "!";

9.4 Exceptions

Capability	Notes
Catch / transform / swallow + fallback / rethrow	Supported
context.Exception	Records last exception
No pointless TargetInvocationException / AggregateException wrapping	Prefer ExceptionDispatchInfo
Incompatible return type	Clear exception with method name + expected / actual types

---

10. 🔄 Return Types (Sync + Async)

Signature	Supported
void	✅
T (sync)	✅
Task	✅
Task<T>	✅
ValueTask	✅
ValueTask<T>	✅

Pipeline normalizes to ValueTask<object?>, then restores. Async business methods are never blocked with .Wait() / .Result / GetAwaiter().GetResult().

---

11. 🔌 DI Registration

services.EasyCoreInvocation(); // auto-discover + inject business proxies

// Optional: wrapper lifetime (explicit wins; independent from EasyCoreInvocation)
services.Invocation<AuditInvocation>(ServiceLifetime.Scoped);
services.Invocation<CacheInvocation>(ServiceLifetime.Singleton);

// Optional: manual business proxy (usually unnecessary)
services.InvocationService<IUserService, UserService>(ServiceLifetime.Scoped);
services.InvocationService<UserServiceClass>(ServiceLifetime.Scoped); // class proxy

API	Role	Default lifetime	Precedence
EasyCoreInvocation()	Scan attrs, register business proxies	See DiscoveredServiceLifetime (default Scoped)	Discovery TryAdd — never overwrites explicit regs
Invocation<T>(lifetime)	Register wrapper	Parameter (API default Transient)	Replace — always wins
InvocationService<TI, TImpl>(lifetime)	Manual interface proxy	Parameter (API default Scoped)	Replace
InvocationService<TImpl>(lifetime)	Manual class proxy	Parameter (API default Scoped)	Replace

Defaults when only EasyCoreInvocation() is used

Object	Default
Business proxies (e.g. IUserService)	Scoped (DiscoveredServiceLifetime)
Wrappers (e.g. AuditInvocation)	If not Invocation<T>: created per call via ActivatorUtilities (≈ transient)

Core services use TryAdd; safe to call repeatedly.

---

12. ⚙️ InvocationOptions

services.EasyCoreInvocation(options =>
{
    // Production: narrow the scan
    options.AddAssemblyFrom<UserService>();
    // options.AddAssembly(typeof(UserService).Assembly);

    options.AutoDiscoverServices = true;                    // default true
    options.DiscoveredServiceLifetime = ServiceLifetime.Scoped; // default Scoped
    options.AutoRegisterInvocations = true;                 // default true

    options.EnableClassAttributes = true;                   // default true
    options.EnableInterfaceAttributes = true;               // default true
    options.EnableMethodAttributes = true;                  // default true
    options.EnableMvcInterfaceAttributes = true;            // default true (merge contract attrs onto Controller/AppService actions)
});

Option	Default	Meaning
AutoDiscoverServices	true	Scan types with InvocationAttribute and register proxies
DiscoveredServiceLifetime	Scoped	Lifetime for auto-discovered business proxies
AutoRegisterInvocations	true	Create wrappers at call time if not Invocation<T>()
EnableClassAttributes	true	Merge class-level attributes
EnableInterfaceAttributes	true	Merge interface-level attributes
EnableMethodAttributes	true	Merge method-level attributes
EnableMvcInterfaceAttributes	true	Merge contract/interface attrs onto Controller / EasyCoreAppService actions
AddAssemblyFrom<T>()	(empty → broad scan)	Add assembly containing T
AddAssembly(Assembly)	(empty → broad scan)	Add assembly explicitly
Assemblies	read-only list	Current scan set

Everyday: services.EasyCoreInvocation();
Pin wrapper lifetime: services.Invocation<AuditInvocation>(ServiceLifetime.Singleton);

---

13. 🧭 Auto-Discovery Rules

When AutoDiscoverServices=true:

1. Assemblies: use Assemblies if non-empty; otherwise scan entry / references / base-directory candidate DLLs (skip Microsoft.*, System.*, Castle.*, self, etc.).
2. Find concrete types with InvocationAttribute on class / methods / implemented interfaces (and their methods).
3. Skip: abstract, interface, open generic, value types, IInvocation implementors, Attribute subclasses.
4. Register all business interfaces on the type (skip System.* / Microsoft.* / Castle.*), e.g. CatalogService → IAuditedCatalog + IPlainCatalog.
5. No business interface and non-sealed → class proxy; sealed without interfaces → skip.

---

14. 🪞 Interface Proxy vs Class Proxy

Mode	Requirements	Recommend
Interface proxy IUserService / UserService	Impl methods need not be virtual; class may be sealed	✅ Preferred
Class proxy UserService	Class not sealed; methods must be virtual	Fallback
new UserService()	No proxy	❌ No interception

---

15. ⚠️ Castle Limitations

Scenario	Intercepted?
✅ Interface members on an interface proxy	Yes
✅ virtual instance methods on a class proxy	Yes
❌ Class proxy for a sealed class	No
❌ Non-virtual / private / static	No
❌ Instances from new	No
❌ In-place weaving	No

Always call through the DI-resolved proxy.

---

16. 🧪 Demo Projects

Project	Description	Command
WebApp.Invocation	Web API + Swagger: service placements + API controller placement + Audit / Cache / Retry	dotnet run --project demo/WebApp.Invocation

builder.Services.EasyCoreDynamicApi();   // G: EasyCoreAppService dynamic APIs
builder.Services.EasyCoreInvocation();
builder.Services.Invocation<CacheInvocation>(ServiceLifetime.Singleton);

Open: http://localhost:5188/swagger · Guide: http://localhost:5188/api/demo
Watch the console for [Audit] / [Cache] / [Retry].

Scenario	Placement	Route prefix	What to verify
A	Interface type [Audit] IUserService	/api/users	All interface methods audited; /{id} + [Cache]; /unstable + [Retry]
B	Class [Audit] OrderService	/api/orders	Every class method audited
C	Impl method	/api/reports	Only generate has [Cache]+[Audit]; preview stays clean
D	Interface method	/api/notify	Only send audited; ping stays clean
E	Multi-interface	/api/catalog	Only IAuditedCatalog audited; plain list/describe are not
F	API Controller / Action	/api/apiplacement · /api/apimethodonly	Controller-level and action-level attributes

dotnet test
dotnet run --project demo/WebApp.Invocation

---

17. ✅ Production Checklist

• Use EasyCoreInvocation(); prefer AddAssemblyFrom<T>() in production
• Service attrs on interface / class / method; API attrs may sit on Controller / Action
• Prefer interface proxies (IXxx / Xxx naming)
• Shared wrappers (e.g. in-memory cache) → Invocation<T>(Singleton)
• Avoid Singleton wrappers capturing Scoped dependencies incorrectly
• Never new implementations expecting interception
• For class proxies: virtual + non-sealed
• CI runs dotnet test

---

18. ❓ FAQ

Q: Is EasyCoreInvocation() enough?
A: Yes. It discovers and injects proxies. Wrappers are created per call by default; use Invocation<T>(lifetime) to pin lifetime.

Q: Do EasyCoreInvocation and Invocation<T> overwrite each other?
A: No. Discovery uses TryAdd; Invocation<T> uses Replace — explicit lifetime wins.

Q: Are business proxies Transient by default?
A: No. Auto-discovered business proxies default to Scoped. Unregistered wrappers are ≈ transient per call.

Q: Attribute applied but nothing happens?
A: For services, call the DI proxy (IUserService), not a new-ed implementation. On Controllers / Actions, put InvocationAttribute directly (IFilterFactory) — no global Filter needed.

Q: What do interface / class / method / API placements hit?
A: Interface type / service class / controller class → all members on that type; interface method / impl method / action → that member only. With multiple interfaces, an interface-type attribute applies only to methods belonging to that interface.

Q: Can EasyCoreAppService dynamic APIs use attributes on the contract interface only?
A: Yes. With EnableMvcInterfaceAttributes=true (default), contract InvocationAttributes are merged onto matching actions over HTTP. You may still add method-level attrs on the AppService class.

Q: Are controller attributes Filters?
A: You still write [Audit] + IInvocation. Castle cannot intercept non-virtual actions, so the attribute implements IFilterFactory to plug into MVC — you do not write/register a separate global Filter.

Q: Class proxy method not intercepted?
A: Class must not be sealed; method must be virtual. Prefer an interface proxy.

Q: Is this an ASP.NET Filter?
A: No. Works in Console / Worker / Web.

Q: Short-circuit / retry?
A: Skip next to short-circuit; call await next() multiple times to retry.

Q: Sync methods?
A: Supported — void, sync T, plus Task / ValueTask families.

Q: Wrong return type?
A: Throws InvalidOperationException with method name + expected / actual types.

Q: Service not discovered?
A: Ensure InvocationAttribute exists; prefer I{ClassName}; or AddAssemblyFrom<T>(); don't leave AutoDiscoverServices=false on the host by mistake.

---

19. 📄 License

MIT

---

🤝 Contributing

1. Fork and create a feature branch
2. Add tests under tests/EasyCore.Invocation.Tests
3. Run dotnet test and dotnet build EasyCore.Invocation.sln
4. Open a Pull Request

Issues / PRs welcome 🚀