|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +This is a .NET library that provides distributed locking using Amazon DynamoDB. It supports .NET 8 and 9, uses nullable reference types, and follows modern C# conventions. |
| 8 | + |
| 9 | +### Key Architecture Components |
| 10 | + |
| 11 | +- **DynamoDbDistributedLock** (src/DynamoDb.DistributedLock/DynamoDbDistributedLock.cs): Main implementation of the distributed lock |
| 12 | +- **IDistributedLockHandle** (src/DynamoDb.DistributedLock/IDistributedLockHandle.cs): Handle interface with IAsyncDisposable for automatic cleanup |
| 13 | +- **DynamoDbLockOptions** (src/DynamoDb.DistributedLock/DynamoDbLockOptions.cs): Configuration options with retry settings |
| 14 | +- **Retry System** (src/DynamoDb.DistributedLock/Retry/): Exponential backoff retry policy with jitter |
| 15 | +- **Dependency Injection** (src/DynamoDb.DistributedLock/Extensions/ServiceCollectionExtensions.cs): Configuration binding and service registration |
| 16 | + |
| 17 | +## Development Commands |
| 18 | + |
| 19 | +### Build |
| 20 | +```bash |
| 21 | +dotnet build |
| 22 | +``` |
| 23 | + |
| 24 | +### Run Tests (uses Microsoft Testing Platform) |
| 25 | +```bash |
| 26 | +dotnet run --project test/DynamoDb.DistributedLock.Tests |
| 27 | +``` |
| 28 | + |
| 29 | +### Run Tests for Specific Framework |
| 30 | +```bash |
| 31 | +dotnet run --project test/DynamoDb.DistributedLock.Tests --framework net8.0 |
| 32 | +dotnet run --project test/DynamoDb.DistributedLock.Tests --framework net9.0 |
| 33 | +``` |
| 34 | + |
| 35 | +### Run Single Test Class |
| 36 | +```bash |
| 37 | +dotnet run --project test/DynamoDb.DistributedLock.Tests -- --filter "ClassName=DynamoDbDistributedLockTests" |
| 38 | +``` |
| 39 | + |
| 40 | +### Pack NuGet Package |
| 41 | +```bash |
| 42 | +dotnet pack --configuration Release |
| 43 | +``` |
| 44 | + |
| 45 | +## Testing Framework |
| 46 | + |
| 47 | +- **xUnit v3** with Microsoft Testing Platform runner |
| 48 | +- **AutoFixture + NSubstitute** for test data generation and mocking |
| 49 | +- **FluentAssertions (AwesomeAssertions)** for assertions |
| 50 | +- **Custom TestKit** with specialized attributes and specimen builders: |
| 51 | + - `DynamoDbDistributedLockAutoDataAttribute` for streamlined tests |
| 52 | + - Specimen builders for consistent test object creation |
| 53 | + |
| 54 | +## Configuration Notes |
| 55 | + |
| 56 | +- The library uses **Directory.Build.props** for shared MSBuild properties |
| 57 | +- Test projects are automatically excluded from packing via `IsTestProject=true` |
| 58 | +- Both main library and tests target .NET 8.0 and 9.0 |
| 59 | +- Tests use `UseMicrosoftTestingPlatformRunner=true` for modern test execution |
| 60 | + |
| 61 | +## Code Patterns |
| 62 | + |
| 63 | +- Uses nullable reference types throughout |
| 64 | +- Implements IAsyncDisposable pattern for lock handles |
| 65 | +- Dependency injection follows Microsoft.Extensions patterns |
| 66 | +- Configuration binding supports both programmatic and JSON configuration |
| 67 | +- Internal visibility is granted to test projects via InternalsVisibleTo |
| 68 | + |
| 69 | +## AWS Integration |
| 70 | + |
| 71 | +- Uses AWSSDK.DynamoDBv2 for DynamoDB operations |
| 72 | +- Supports configurable table structure (partition key, sort key attributes) |
| 73 | +- Implements TTL-based lock expiration |
| 74 | +- Handles DynamoDB-specific exceptions for retry logic |
0 commit comments