EasyCore.Polly 8.3.2

🛡️ EasyCore.Polly

EasyCore.Polly is a production-ready Polly resilience wrapper for .NET 8. Apply retry, timeout, circuit breaker, bulkhead, and fallback with [PollyConfig] on interface / class / method / MVC API. Standalone NuGet (does not depend on EasyCore.Invocation); stacks with Redis / Invocation via DI IAsyncInterceptor.

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

🌍 Language

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

📚 Table of Contents

Part I — Overview & Architecture

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

Part II — Getting Started

• 4. Installation
• 5. Quick Start
• 6. Attributes & Options

Part III — Policies & Production

• 7. Policy Wrap Order
• 8. Demo Projects
• 9. Production Checklist
• 10. FAQ
• 11. License

1. 🎯 Positioning

EasyCore.Polly solves “declare resilience with attributes instead of hand-written Polly wraps”:

1.1 Design Principles

2. 🏗️ Architecture & Call Chain

2.1 Component diagram

2.2 Call sequence

[IOrderClient] ──► Castle Interface Proxy
                         │
                         ▼
              PollyStandardInterceptor
                         │
                         ▼
         PolicyCache ──► PolicyFactory
                         │
                         ▼
              Fallback → Retry → Timeout
              → CircuitBreaker → Bulkhead
                         │
                         ▼
                 OrderClient.Method()

3. 📁 Repository Layout

EasyCore.Polly/
├── src/EasyCore.Polly/
│   ├── Abstractions/     # Options, Attribute
│   ├── Discovery/       # Assembly discovery
│   ├── Hosting/         # DI extension entry
│   ├── Interception/    # Castle interceptor
│   └── Policies/        # Policy factory and cache
├── demo/
│   ├── PollyTest/                  # Shared sample services
│   ├── WebApp.EasyCorePolly/       # ASP.NET Core + Swagger
│   └── WinFormsApp.EasyCorePolly/  # WinForms
├── tests/EasyCore.Polly.Tests/
├── docs/svg/                       # README diagrams
└── png/EasyCoreLogo.png

Folders are for organization only; the public namespace stays EasyCore.Polly.

4. 📦 Installation

dotnet add package EasyCore.Polly

Requires .NET 8.

5. ⚡ Quick Start

5.1 Define an interface and implementation

using EasyCore.Polly;

public interface IOrderClient
{
    [PollyConfig(
        MaxRetry = 3,
        RetryIntervalSeconds = 1,
        TimeOutSeconds = 5,
        IsEnableCircuitBreaker = true,
        ExceptionsAllowedBeforeBreaking = 5,
        SecondsOfBreak = 30,
        ServiceDegradation = nameof(GetOrderFallbackAsync))]
    Task<string> GetOrderAsync(string id);

    Task<string> GetOrderFallbackAsync();
}

public sealed class OrderClient : IOrderClient
{
    public Task<string> GetOrderAsync(string id)
        => throw new HttpRequestException("upstream down");

    public Task<string> GetOrderFallbackAsync()
        => Task.FromResult("cached-or-default");
}

Services need an interface proxy. You can also put [PollyConfig] on Controller / Action (no global filter).

5.2 Register services

Either style works:

// Convenient: auto-scan candidate assemblies (demo / local)
builder.Services.AddEasyCorePolly();

// Production: scan an explicit assembly
builder.Services.AddEasyCorePolly(options =>
{
    options.AddAssemblyFrom<OrderClient>();
});

Resolve IOrderClient from DI — you get a Castle proxy that applies policies.

6. ⚙️ Attributes & Options

6.0 Placement

Resolution: impl method → interface method → class → interface type. Default Order is 50 (typically outside cache).

MVC / Dynamic API and retry: ActionExecutionDelegate may run only once, so the filter path forces MaxRetry = 0 (timeout / circuit breaker / bulkhead / fallback still apply). Use Castle proxies for retries (plain services, or AspNetCore.Mvc remote DispatchProxy wrapped with interceptors).

6.1 [PollyConfig] property reference

6.2 EasyCorePollyOptions

7. 🧩 Policy Wrap Order

7.1 Visual wrap

7.2 Execution order

Outermost → innermost:

Fallback → Retry → Timeout → CircuitBreaker → Bulkhead → method

This matches Polly WrapAsync composition used by EasyCore.Polly.

8. 🧪 Demo Projects

Cross-stack (host references Invocation + Redis; packages stay independent):

GET /api/demo           # A–F placement guide
GET /api/users/unstable # A interface-type [PollyConfig]
GET /api/orders         # B class-type
GET /api/reports/generate
GET /api/notify/send
GET /api/catalog/publish
GET /api/apiplacement/ping
GET /api/combo           # H three-package stack

dotnet test tests/EasyCore.Polly.Tests
dotnet run --project demo/WebApp.EasyCorePolly

9. ✅ Production Checklist

• Call AddAssemblyFrom<T>() (do not rely on base-directory DLL scanning)
• Expose services through interfaces (I{ClassName})
• Configure logging in the host (console/file/OTLP) — the library does not add sinks
• Tune circuit-breaker and timeout values for your SLOs
• Prefer returning values from degradation methods for Task<T> APIs
• Invalid [PollyConfig] values throw at first execution

10. ❓ FAQ

Q: Why must I use an interface?
A: For services, policies apply via Castle interface proxies. You can also put [PollyConfig] on Controller / Action (IFilterFactory).

Q: Why does MaxRetry not apply on Controller / EasyCoreAppService?
A: MVC filter next can execute only once; retrying would break the pipeline. PollyConfigActionFilter therefore clears MaxRetry on the filter path. Hitting a dynamic API directly (e.g. /api/Xxx/GetUnstableAsync) will not retry; MaxRetry applies on Castle service proxies and on Consumer remote proxies (Castle over HTTP).

Q: Is RateLimit a per-second throttle?
A: No. It maps to Polly Bulkhead (max concurrent executions + optional queue). See the wrap diagram above.

Q: What can a fallback method return?
A: Task, Task<T>, or a synchronous T for generic methods. It must be parameterless and on the same type.

Q: Can I use this with EasyCore.Redis / EasyCore.Invocation?
A: Yes. They are independent NuGet packages. Each registers IAsyncInterceptor via TryAddEnumerable; proxies stack with GetServices. Do not use single-slot TryAdd<IAsyncInterceptor> or only the first package wins.

Q: How does this relate to Ocelot / API gateways?
A: EasyCore.Polly is in-process resilience. Gateways handle edge traffic; use both when appropriate.

Q: Polly v8?
A: This package targets Polly 7.2.x so the attribute model stays stable. Polly v8 pipelines are a separate migration.

11. 📄 License

MIT

🤝 Contributing

1. Fork and create a feature branch
2. Add tests under tests/EasyCore.Polly.Tests
3. Run dotnet test and dotnet build EasyCore.Polly.sln
4. Open a pull request

Issues / PRs welcome 🚀