|
| 1 | +# WeihanLi.Common - Copilot Instructions |
| 2 | + |
| 3 | +## Project Overview |
| 4 | + |
| 5 | +WeihanLi.Common is a comprehensive .NET utility library providing common helpers, extensions, and utilities for .NET applications. The library includes dependency injection, AOP (Aspect-Oriented Programming), event handling, logging, data access extensions, TOTP implementation, template engine, and much more. |
| 6 | + |
| 7 | +## Project Structure |
| 8 | + |
| 9 | +``` |
| 10 | +├── src/ # Main source code |
| 11 | +│ ├── WeihanLi.Common/ # Core library |
| 12 | +│ ├── WeihanLi.Common.Logging.Serilog/ # Serilog integration |
| 13 | +│ └── WeihanLi.Extensions.Hosting/ # Hosting extensions |
| 14 | +├── test/ # Unit tests |
| 15 | +│ └── WeihanLi.Common.Test/ # Test projects using xUnit |
| 16 | +├── samples/ # Sample applications |
| 17 | +│ ├── AspNetCoreSample/ # ASP.NET Core examples |
| 18 | +│ └── DotNetCoreSample/ # Console app examples |
| 19 | +├── perf/ # Performance benchmarks |
| 20 | +├── docs/ # Documentation using DocFX |
| 21 | +├── build/ # Build scripts and tools |
| 22 | +└── .github/ # CI/CD workflows |
| 23 | +``` |
| 24 | + |
| 25 | +## Key Components |
| 26 | + |
| 27 | +### Core Features |
| 28 | +- **Dependency Injection**: Custom DI container similar to Microsoft's framework |
| 29 | +- **Fluent Aspects (AOP)**: Dynamic proxy-based AOP framework |
| 30 | +- **Event System**: EventBus, EventQueue, and EventStore implementations |
| 31 | +- **Logging Framework**: Integration with Serilog and Microsoft logging |
| 32 | +- **Data Extensions**: Dapper-like ADO.NET extensions for database operations |
| 33 | +- **TOTP Implementation**: Time-based One-Time Password algorithm |
| 34 | +- **Template Engine**: Custom template processing engine |
| 35 | +- **HTTP Utilities**: HTTP client extensions and utilities |
| 36 | +- **Guard Utilities**: Parameter validation helpers |
| 37 | +- **Compression**: Data compression utilities |
| 38 | +- **Extensions**: Extensive extension methods for common types |
| 39 | + |
| 40 | +### Namespace Organization |
| 41 | +- `WeihanLi.Common` - Core utilities and Guard classes |
| 42 | +- `WeihanLi.Common.Aspect` - AOP framework components |
| 43 | +- `WeihanLi.Common.Data` - Database and data access utilities |
| 44 | +- `WeihanLi.Common.DependencyInjection` - DI container implementation |
| 45 | +- `WeihanLi.Common.Event` - Event handling system |
| 46 | +- `WeihanLi.Common.Extensions` - Extension methods for various types |
| 47 | +- `WeihanLi.Common.Helpers` - Utility helper classes |
| 48 | +- `WeihanLi.Common.Http` - HTTP-related utilities |
| 49 | +- `WeihanLi.Common.Logging` - Logging abstractions and implementations |
| 50 | +- `WeihanLi.Common.Otp` - TOTP and OTP implementations |
| 51 | +- `WeihanLi.Common.Services` - Common service implementations |
| 52 | +- `WeihanLi.Common.Template` - Template engine components |
| 53 | + |
| 54 | +## Code Style and Conventions |
| 55 | + |
| 56 | +### General Guidelines |
| 57 | +- **Target Frameworks**: netstandard2.0, net8.0, net9.0, net10.0 |
| 58 | +- **Language Features**: C# with nullable reference types enabled, implicit usings |
| 59 | +- **License**: Apache License 2.0 |
| 60 | +- **Naming**: PascalCase for public members, camelCase for private fields, following the editorconfig |
| 61 | +- **Null Safety**: Extensive use of nullable annotations and Guard utilities |
| 62 | + |
| 63 | +### Common Patterns |
| 64 | + |
| 65 | +#### Guard Usage |
| 66 | +Always validate parameters using the Guard class: |
| 67 | +```csharp |
| 68 | +public static string Process(string input) |
| 69 | +{ |
| 70 | + Guard.NotNullOrEmpty(input); |
| 71 | + // implementation |
| 72 | +} |
| 73 | +``` |
| 74 | + |
| 75 | +#### Extension Method Pattern |
| 76 | +Extension methods should be in dedicated files with descriptive names: |
| 77 | +```csharp |
| 78 | +namespace WeihanLi.Extensions; |
| 79 | + |
| 80 | +public static class StringExtension |
| 81 | +{ |
| 82 | + public static bool IsNullOrEmpty(this string? str) => string.IsNullOrEmpty(str); |
| 83 | +} |
| 84 | +``` |
| 85 | + |
| 86 | +#### Configuration Pattern |
| 87 | +Use options pattern for configuration: |
| 88 | +```csharp |
| 89 | +public sealed class ServiceOptions |
| 90 | +{ |
| 91 | + public string ConnectionString { get; set; } = string.Empty; |
| 92 | + public int Timeout { get; set; } = 30; |
| 93 | +} |
| 94 | +``` |
| 95 | + |
| 96 | +#### Fluent API Design |
| 97 | +Many components use fluent interfaces: |
| 98 | +```csharp |
| 99 | +FluentAspects.Configure(options => |
| 100 | + options.InterceptAll() |
| 101 | + .With<LoggingInterceptor>() |
| 102 | +); |
| 103 | +``` |
| 104 | + |
| 105 | +## Testing Guidelines |
| 106 | + |
| 107 | +### Test Structure |
| 108 | +- Use xUnit as the testing framework |
| 109 | +- Test files should be named `{ComponentName}Test.cs` |
| 110 | +- Tests should be in the `WeihanLi.Common.Test` namespace |
| 111 | +- Use descriptive test method names that explain the scenario |
| 112 | + |
| 113 | +### Test Patterns |
| 114 | +```csharp |
| 115 | +[Fact] |
| 116 | +public void MethodName_Scenario_ExpectedResult() |
| 117 | +{ |
| 118 | + // Arrange |
| 119 | + var input = "test"; |
| 120 | + |
| 121 | + // Act |
| 122 | + var result = SystemUnderTest.Process(input); |
| 123 | + |
| 124 | + // Assert |
| 125 | + Assert.NotNull(result); |
| 126 | +} |
| 127 | + |
| 128 | +[Theory] |
| 129 | +[InlineData("input1", "expected1")] |
| 130 | +[InlineData("input2", "expected2")] |
| 131 | +public void MethodName_MultipleInputs_ReturnsExpected(string input, string expected) |
| 132 | +{ |
| 133 | + var result = SystemUnderTest.Process(input); |
| 134 | + Assert.Equal(expected, result); |
| 135 | +} |
| 136 | +``` |
| 137 | + |
| 138 | +## Build and Development |
| 139 | + |
| 140 | +### Build System |
| 141 | +- Uses .NET 10 SDK |
| 142 | +- Custom build scripts in `build/` directory using dotnet-execute |
| 143 | +- Multi-targeting for compatibility across .NET versions |
| 144 | +- Automated CI/CD with GitHub Actions and Azure DevOps |
| 145 | + |
| 146 | +### .NET SDK Setup |
| 147 | +The project requires .NET 10 SDK (with rollForward enabled to support newer versions). For development setup: |
| 148 | + |
| 149 | +1. **Install .NET SDK**: Download and install .NET 10 SDK or later from [dotnet.microsoft.com](https://dotnet.microsoft.com/download) |
| 150 | +2. **Multiple SDK Versions**: The GitHub Actions workflow (`.github/workflows/default.yml`) shows the supported SDK versions: |
| 151 | + ```yaml |
| 152 | + dotnet-version: | |
| 153 | + 8.0.x |
| 154 | + 9.0.x |
| 155 | + 10.0.x |
| 156 | + ``` |
| 157 | +3. **Verify Installation**: Run `dotnet --info` to confirm the SDK is properly installed |
| 158 | +4. **SDK Configuration**: The `global.json` file specifies the minimum SDK version with `rollForward: "latestMajor"` enabled |
| 159 | + |
| 160 | +### Development Commands |
| 161 | +```bash |
| 162 | +# Build the solution |
| 163 | +dotnet build |
| 164 | +
|
| 165 | +# Run tests |
| 166 | +dotnet test |
| 167 | +
|
| 168 | +# Run custom build script |
| 169 | +./build.sh |
| 170 | +
|
| 171 | +# Format code |
| 172 | +dotnet format |
| 173 | +``` |
| 174 | + |
| 175 | +### Code Generation |
| 176 | +Some files are generated using T4 templates (.tt files): |
| 177 | +- Database extension methods |
| 178 | +- Service container registration methods |
| 179 | + |
| 180 | +## Common Tasks |
| 181 | + |
| 182 | +### Adding New Extensions |
| 183 | +1. Create extension class in appropriate `Extensions/` subdirectory |
| 184 | +2. Use proper namespace (typically `WeihanLi.Extensions`) |
| 185 | +3. Add comprehensive XML documentation |
| 186 | +4. Write corresponding unit tests |
| 187 | +5. Follow existing patterns for parameter validation |
| 188 | + |
| 189 | +### Adding New Services |
| 190 | +1. Define interface in `Abstractions/` if needed |
| 191 | +2. Implement service in `Services/` directory |
| 192 | +3. Add configuration options class if configurable |
| 193 | +4. Register with DI container if applicable |
| 194 | +5. Add integration tests |
| 195 | + |
| 196 | +### Working with AOP |
| 197 | +The Fluent Aspects framework allows method interception: |
| 198 | +```csharp |
| 199 | +// Configure interceptors |
| 200 | +FluentAspects.Configure(options => |
| 201 | +{ |
| 202 | + options.InterceptMethod<IService>(s => s.Process(Argument.Any<string>())) |
| 203 | + .With<ValidationInterceptor>(); |
| 204 | +}); |
| 205 | +
|
| 206 | +// Create proxy |
| 207 | +var service = FluentAspects.AspectOptions.ProxyFactory |
| 208 | + .CreateProxy<IService>(new ServiceImplementation()); |
| 209 | +``` |
| 210 | + |
| 211 | +### Database Operations |
| 212 | +Use the data extensions for database operations: |
| 213 | +```csharp |
| 214 | +// Query data |
| 215 | +var users = connection.Select<User>("SELECT * FROM Users WHERE Age > @age", new { age = 18 }); |
| 216 | +
|
| 217 | +// Repository pattern |
| 218 | +var repository = new Repository<User>(() => connectionFactory.GetConnection()); |
| 219 | +var user = repository.Fetch(u => u.Id == userId); |
| 220 | +``` |
| 221 | + |
| 222 | +## Dependencies and Compatibility |
| 223 | + |
| 224 | +### Key Dependencies |
| 225 | +- Microsoft.Extensions.Configuration |
| 226 | +- Microsoft.Extensions.Logging |
| 227 | +- Newtonsoft.Json |
| 228 | +- System.ComponentModel.Annotations (for .NET Standard 2.0) |
| 229 | + |
| 230 | +### Compatibility Notes |
| 231 | +- Supports .NET Standard 2.0 for broad compatibility |
| 232 | +- Modern .NET versions (8.0+) for latest features |
| 233 | +- Conditional compilation for framework-specific optimizations |
| 234 | +- AOT compatibility for .NET 8.0+ |
| 235 | + |
| 236 | +## Documentation |
| 237 | + |
| 238 | +- XML documentation is required for all public APIs |
| 239 | +- Use DocFX for generating documentation website |
| 240 | +- Examples should be provided in the `samples/` directory |
| 241 | +- README files should be updated when adding major features |
| 242 | + |
| 243 | +## Performance Considerations |
| 244 | + |
| 245 | +- Use `Span<T>` and `Memory<T>` where appropriate for modern .NET versions |
| 246 | +- Avoid allocations in hot paths |
| 247 | +- Use object pooling for frequently allocated objects |
| 248 | +- Benchmark performance-critical code in `perf/` directory |
| 249 | + |
| 250 | +## Security Guidelines |
| 251 | + |
| 252 | +- Input validation using Guard utilities |
| 253 | +- Proper disposal of resources |
| 254 | +- Secure random number generation for cryptographic operations |
| 255 | +- Avoid hardcoded secrets or credentials |
| 256 | + |
| 257 | +## Contributing Guidelines |
| 258 | + |
| 259 | +When contributing to this repository: |
| 260 | +1. Follow existing code style and patterns |
| 261 | +2. Add comprehensive tests for new functionality |
| 262 | +3. Update documentation and examples |
| 263 | +4. Ensure compatibility across target frameworks |
| 264 | +5. Use conventional commit messages |
| 265 | +6. Consider performance implications |
| 266 | +7. Validate with existing build and test processes |
0 commit comments