EasyCore.Polly 8.0.1

🛡️ 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 methods — powered by Castle DynamicProxy.

<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
{
    Task<string> GetOrderAsync(string id);
}

public sealed class OrderClient : IOrderClient
{
    [PollyConfig(
        MaxRetry = 3,
        RetryIntervalSeconds = 1,
        TimeOutSeconds = 5,
        IsEnableCircuitBreaker = true,
        ExceptionsAllowedBeforeBreaking = 5,
        SecondsOfBreak = 30,
        ServiceDegradation = nameof(GetOrderFallbackAsync))]
    public Task<string> GetOrderAsync(string id)
        => throw new HttpRequestException("upstream down");

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

Interface proxy is required. The implementation type name OrderClient pairs with interface IOrderClient.

5.2 Register services

Either style works:

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

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

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

6. ⚙️ Attributes & Options

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

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: Policies are applied via Castle interface proxies. Class-only registration is not proxied.

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: 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 🚀