|
2 | 2 |
|
3 | 3 | A high-performance .NET 9.0 library providing Result types and railway-oriented programming patterns for robust error handling in distributed applications. |
4 | 4 |
|
5 | | -**ALWAYS follow these instructions first and only fall back to search or bash commands when you encounter unexpected information that does not match the instructions below.** |
6 | | - |
7 | | -## Working Effectively |
8 | | - |
9 | | -### Bootstrap and Build the Repository |
10 | | - |
11 | | -**NEVER CANCEL builds or tests** - they complete quickly but timeouts should be generous. |
12 | | - |
13 | | -1. **Install .NET 9.0 SDK (REQUIRED):** |
14 | | - ```bash |
15 | | - wget -q https://dot.net/v1/dotnet-install.sh && chmod +x dotnet-install.sh |
16 | | - ./dotnet-install.sh --version 9.0.100 --install-dir ~/.dotnet |
17 | | - export PATH="/home/runner/.dotnet:$PATH" |
18 | | - ``` |
19 | | - - Verification: `dotnet --version` should show `9.0.100` |
20 | | - - **CRITICAL**: The project targets .NET 9.0 and will NOT build with older SDKs |
21 | | - |
22 | | -2. **Restore packages (takes ~7 seconds):** |
23 | | - ```bash |
24 | | - dotnet restore ManagedCode.Communication/ManagedCode.Communication.csproj |
25 | | - dotnet restore ManagedCode.Communication.AspNetCore/ManagedCode.Communication.AspNetCore.csproj |
26 | | - dotnet restore ManagedCode.Communication.Orleans/ManagedCode.Communication.Orleans.csproj |
27 | | - dotnet restore ManagedCode.Communication.Tests/ManagedCode.Communication.Tests.csproj |
28 | | - dotnet restore ManagedCode.Communication.Benchmark/ManagedCode.Communication.Benchmark.csproj |
29 | | - ``` |
30 | | - - **NEVER CANCEL**: Set timeout to 300+ seconds. Build may take up to 5 minutes on slow connections. |
31 | | - |
32 | | -3. **Build all projects (takes ~12 seconds):** |
33 | | - ```bash |
34 | | - dotnet build ManagedCode.Communication/ManagedCode.Communication.csproj --configuration Release |
35 | | - dotnet build ManagedCode.Communication.AspNetCore/ManagedCode.Communication.AspNetCore.csproj --configuration Release |
36 | | - dotnet build ManagedCode.Communication.Orleans/ManagedCode.Communication.Orleans.csproj --configuration Release |
37 | | - dotnet build ManagedCode.Communication.Tests/ManagedCode.Communication.Tests.csproj --configuration Release |
38 | | - dotnet build ManagedCode.Communication.Benchmark/ManagedCode.Communication.Benchmark.csproj --configuration Release |
39 | | - ``` |
40 | | - - **NEVER CANCEL**: Set timeout to 600+ seconds. Full build may take up to 10 minutes. |
41 | | - |
42 | | -### Testing |
43 | | - |
44 | | -**Run all tests (takes ~5 seconds, 638 tests):** |
45 | | -```bash |
46 | | -dotnet test ManagedCode.Communication.Tests/ManagedCode.Communication.Tests.csproj --configuration Release --no-build --verbosity normal |
47 | | -``` |
48 | | -- **NEVER CANCEL**: Set timeout to 300+ seconds. Tests may take up to 5 minutes in CI environments. |
49 | | -- **Expected result**: All 638 tests pass with 70%+ code coverage |
50 | | -- Tests include ASP.NET Core integration tests with real HTTP requests and SignalR hubs |
| 5 | +## Project Requirements |
51 | 6 |
|
52 | | -### Code Quality and Formatting |
| 7 | +This project requires **.NET 9.0 SDK**. Install it using: |
53 | 8 |
|
54 | | -**Format code (IMPORTANT - there are known line ending issues):** |
55 | 9 | ```bash |
56 | | -# Format individual projects (the repository has CRLF line ending issues on Linux) |
57 | | -dotnet format ManagedCode.Communication/ManagedCode.Communication.csproj --verbosity minimal |
58 | | -dotnet format ManagedCode.Communication.AspNetCore/ManagedCode.Communication.AspNetCore.csproj --verbosity minimal |
59 | | -dotnet format ManagedCode.Communication.Orleans/ManagedCode.Communication.Orleans.csproj --verbosity minimal |
60 | | -dotnet format ManagedCode.Communication.Tests/ManagedCode.Communication.Tests.csproj --verbosity minimal |
| 10 | +dotnet --list-sdks # Check if 9.0.x is available |
61 | 11 | ``` |
62 | | -- **NOTE**: The repository uses CRLF line endings (.editorconfig sets `end_of_line = crlf`) which may cause formatting errors on Linux. This is expected behavior. |
63 | | -- **DO NOT** try to fix line ending issues - they are intentional for Windows compatibility |
64 | | - |
65 | | -## Validation Scenarios |
66 | | - |
67 | | -**ALWAYS test actual functionality after making changes** by running through these complete scenarios: |
68 | | - |
69 | | -### 1. Basic Library Functionality Test |
70 | | -Create a test console app to verify core Result functionality: |
71 | 12 |
|
| 13 | +If not available, install .NET 9.0: |
72 | 14 | ```bash |
73 | | -cd /tmp |
74 | | -dotnet new console -n TestLibrary |
75 | | -cd TestLibrary |
76 | | -dotnet add reference /home/runner/work/Communication/Communication/ManagedCode.Communication/ManagedCode.Communication.csproj |
| 15 | +wget -q https://dot.net/v1/dotnet-install.sh && chmod +x dotnet-install.sh |
| 16 | +./dotnet-install.sh --version 9.0.100 --install-dir ~/.dotnet |
| 17 | +export PATH="~/.dotnet:$PATH" |
77 | 18 | ``` |
78 | 19 |
|
79 | | -Test Program.cs content: |
80 | | -```csharp |
81 | | -using ManagedCode.Communication; |
82 | | -using ManagedCode.Communication.Extensions; |
83 | | -using System; |
84 | | - |
85 | | -Console.WriteLine("Testing ManagedCode.Communication Library"); |
86 | | - |
87 | | -// Test basic Result creation |
88 | | -var successResult = Result.Succeed(); |
89 | | -var failureResult = Result.Fail("Something went wrong"); |
90 | | -Console.WriteLine($"Success: {successResult.IsSuccess}, Failure: {failureResult.IsSuccess}"); |
| 20 | +## Build and Test |
91 | 21 |
|
92 | | -// Test Result<T> with values |
93 | | -var userResult = Result<string>.Succeed("John Doe"); |
94 | | -var notFoundResult = Result<string>.FailNotFound("User not found"); |
95 | | -Console.WriteLine($"User: {userResult.Value}, NotFound: {notFoundResult.Problem?.Title}"); |
96 | | - |
97 | | -// Test railway-oriented programming chain |
98 | | -var chainResult = ValidateEmail("test@example.com") |
99 | | - .Then(email => Result<string>.Succeed(email.ToLower())) |
100 | | - .Then(email => Result<string>.Succeed($"Processed: {email}")); |
101 | | -Console.WriteLine($"Chain result: {chainResult.IsSuccess}, Value: {chainResult.Value}"); |
102 | | - |
103 | | -static Result<string> ValidateEmail(string email) => |
104 | | - email.Contains("@") ? Result<string>.Succeed(email) : Result<string>.FailValidation(("email", "Invalid format")); |
| 22 | +**Restore packages:** |
| 23 | +```bash |
| 24 | +dotnet restore |
105 | 25 | ``` |
106 | 26 |
|
107 | | -Run: `dotnet run` |
108 | | -**Expected output**: Success messages showing Result types work correctly with railway-oriented programming. |
109 | | - |
110 | | -### 2. ASP.NET Core Integration Test |
111 | | -The test suite includes real ASP.NET Core integration tests that: |
112 | | -- Start an actual web server on localhost |
113 | | -- Test Result to HTTP status code mapping (200, 400, 403, 404, 500) |
114 | | -- Test SignalR hub integration with Result types |
115 | | -- Test authentication and authorization flows |
116 | | - |
117 | | -Run the integration tests to verify web functionality: |
| 27 | +**Build all projects:** |
118 | 28 | ```bash |
119 | | -dotnet test ManagedCode.Communication.Tests/ManagedCode.Communication.Tests.csproj --filter "AspNetCore" --verbosity normal |
| 29 | +dotnet build --configuration Release |
120 | 30 | ``` |
121 | 31 |
|
122 | | -### 3. Performance Benchmark Test |
123 | | -Test the benchmark suite (interactive): |
| 32 | +**Run tests:** |
124 | 33 | ```bash |
125 | | -dotnet run -c Release --project ManagedCode.Communication.Benchmark/ManagedCode.Communication.Benchmark.csproj -- --job dry |
126 | | -# When prompted, enter "*" to run all benchmarks or "0" for specific benchmark |
| 34 | +dotnet test --configuration Release --no-build |
127 | 35 | ``` |
128 | | -**Expected**: Benchmark starts and shows performance comparisons between Result types and alternatives. |
129 | | - |
130 | | -## Key Projects in the Codebase |
131 | | - |
132 | | -### Core Projects |
133 | | -- **ManagedCode.Communication** - Core Result types, railway-oriented programming extensions, command pattern |
134 | | -- **ManagedCode.Communication.AspNetCore** - ASP.NET Core filters, middleware, and Result-to-HTTP mapping |
135 | | -- **ManagedCode.Communication.Orleans** - Microsoft Orleans serialization support for distributed Result types |
136 | | -- **ManagedCode.Communication.Tests** - Comprehensive test suite (638 tests) |
137 | | -- **ManagedCode.Communication.Benchmark** - BenchmarkDotNet performance testing |
138 | 36 |
|
139 | | -### Key Source Locations |
140 | | -- **Result Types**: `ManagedCode.Communication/Result/`, `ManagedCode.Communication/ResultT/` |
141 | | -- **Railway Extensions**: `ManagedCode.Communication/Extensions/RailwayExtensions*.cs` |
142 | | -- **Command Pattern**: `ManagedCode.Communication/Commands/` |
143 | | -- **ASP.NET Core Filters**: `ManagedCode.Communication.AspNetCore/Filters/` |
144 | | -- **Orleans Serializers**: `ManagedCode.Communication.Orleans/Serializers/` |
| 37 | +## Project Structure |
145 | 38 |
|
146 | | -## Build Timing Expectations |
| 39 | +- **ManagedCode.Communication** - Core Result types and railway-oriented programming extensions |
| 40 | +- **ManagedCode.Communication.AspNetCore** - ASP.NET Core integration, filters, and middleware |
| 41 | +- **ManagedCode.Communication.Orleans** - Microsoft Orleans serialization support |
| 42 | +- **ManagedCode.Communication.Tests** - Test suite |
| 43 | +- **ManagedCode.Communication.Benchmark** - Performance benchmarks |
147 | 44 |
|
148 | | -**All times measured on standard GitHub Actions runners:** |
| 45 | +## Key Concepts |
149 | 46 |
|
150 | | -| Operation | Expected Time | Timeout Setting | |
151 | | -|-----------|---------------|-----------------| |
152 | | -| .NET 9 SDK Install | 30-60 seconds | 300 seconds | |
153 | | -| Package Restore | 5-10 seconds | 300 seconds | |
154 | | -| Full Build | 10-15 seconds | 600 seconds | |
155 | | -| Test Execution | 4-6 seconds | 300 seconds | |
156 | | -| Format Check | 3-8 seconds | 300 seconds | |
157 | | -| Single Project Build | 1-4 seconds | 300 seconds | |
158 | | - |
159 | | -**CRITICAL: NEVER CANCEL** any of these operations. Always wait for completion. |
160 | | - |
161 | | -## Common Development Tasks |
162 | | - |
163 | | -### Adding New Result Types |
164 | | -- Extend base classes in `ManagedCode.Communication/Result/` or `ManagedCode.Communication/ResultT/` |
165 | | -- Add corresponding tests in `ManagedCode.Communication.Tests/` |
166 | | -- Update ASP.NET Core mappings in `ManagedCode.Communication.AspNetCore/Extensions/ResultExtensions.cs` |
167 | | - |
168 | | -### Adding ASP.NET Core Features |
169 | | -- Create filters in `ManagedCode.Communication.AspNetCore/Filters/` |
170 | | -- Add extension methods in `ManagedCode.Communication.AspNetCore/Extensions/` |
171 | | -- Test with real HTTP scenarios in test project's TestApp |
172 | | - |
173 | | -### Performance Testing |
174 | | -- Add benchmarks to `ManagedCode.Communication.Benchmark/` |
175 | | -- Use BenchmarkDotNet attributes for proper measurement |
176 | | -- Always compare against existing baseline implementations |
177 | | - |
178 | | -## Troubleshooting |
179 | | - |
180 | | -### Build Issues |
181 | | -- **".NET 9.0 not found"**: Install .NET 9.0 SDK using the exact commands above |
182 | | -- **"Project not found"**: Use individual project files, not solution file (`.slnx` format not fully supported) |
183 | | -- **"Format errors"**: Line ending issues are expected on Linux due to CRLF settings |
184 | | - |
185 | | -### Test Issues |
186 | | -- **Tests timeout**: ASP.NET Core integration tests start real servers and may take longer in CI environments |
187 | | -- **Orleans tests fail**: Ensure all projects are built before running tests (Orleans needs compiled assemblies) |
188 | | - |
189 | | -### Expected CI Workflow |
190 | | -The `.github/workflows/ci.yml` runs: |
191 | | -1. .NET 9.0 setup |
192 | | -2. `dotnet restore` |
193 | | -3. `dotnet build --configuration Release --no-restore` |
194 | | -4. `dotnet test --configuration Release --no-build` |
195 | | -5. Code coverage upload |
196 | | - |
197 | | -**Always run the same sequence locally** to ensure CI compatibility. |
198 | | - |
199 | | -## Library Usage Examples |
200 | | - |
201 | | -The library provides Result types for error handling without exceptions: |
| 47 | +This library implements railway-oriented programming patterns using Result types for error handling without exceptions: |
202 | 48 |
|
203 | 49 | ```csharp |
204 | | -// Basic usage |
205 | | -Result<User> user = await GetUserAsync(id); |
206 | | -if (user.IsSuccess) |
207 | | - Console.WriteLine($"Found: {user.Value.Name}"); |
208 | | -else |
209 | | - Console.WriteLine($"Error: {user.Problem.Title}"); |
| 50 | +// Basic Result usage |
| 51 | +var success = Result.Succeed(); |
| 52 | +var failure = Result.Fail("Error message"); |
210 | 53 |
|
211 | | -// Railway-oriented programming |
212 | | -var result = await ValidateUserAsync(userData) |
213 | | - .ThenAsync(user => SaveUserAsync(user)) |
214 | | - .ThenAsync(user => SendWelcomeEmailAsync(user)) |
215 | | - .ThenAsync(user => LogUserCreationAsync(user)); |
216 | | - |
217 | | -// ASP.NET Core integration (automatic HTTP status mapping) |
218 | | -[HttpPost] |
219 | | -public Result<User> CreateUser(CreateUserRequest request) => |
220 | | - ValidateRequest(request) |
221 | | - .Then(CreateUserFromRequest) |
222 | | - .Then(SaveUserToDatabase); |
223 | | -``` |
| 54 | +// Generic Result with value |
| 55 | +var result = Result<string>.Succeed("Hello World"); |
| 56 | +if (result.IsSuccess) |
| 57 | +{ |
| 58 | + Console.WriteLine(result.Value); |
| 59 | +} |
224 | 60 |
|
225 | | -Always test these patterns when making changes to ensure the library's core value proposition remains intact. |
| 61 | +// Railway-oriented programming |
| 62 | +var chainResult = ValidateEmail("test@example.com") |
| 63 | + .Then(email => ProcessEmail(email)) |
| 64 | + .Then(processed => SaveToDatabase(processed)); |
| 65 | +``` |
0 commit comments