|
| 1 | +# Migration guide — next major version (1.4.1.* -> 2.0.0.*) |
| 2 | + |
| 3 | +This guide collects every source- or behavior-breaking change introduced in the |
| 4 | +upcoming major release of `AggregatedGenericResultMessage`, plus the new APIs |
| 5 | +that replace the obsolete ones. Each item shows a **before / after** snippet |
| 6 | +so you can mechanically port your callers. |
| 7 | + |
| 8 | +> **TL;DR** |
| 9 | +> - All `ActionOn*` and `Func<Task<TResult>>`-taking `Function*` overloads are now `[Obsolete]`. Replace with `Tap` / `Match` / `*Async`. |
| 10 | +> - `Result<T>.Instance` is now `[Obsolete]`. Replace with `Result<T>.Create()`. |
| 11 | +> - Implicit `Exception → Result` / `Result<T>` operators **throw** on `null` instead of producing a silent empty failure. |
| 12 | +> - `Result<T>(Exception)` ctor adds **one** `Exception` message instead of two. |
| 13 | +> - `JoinErrors` now derives `IsSuccess` from the input collection (was a bug). |
| 14 | +> - `Success<T>(T, params RelatedObjectModel[])` no longer adds a ghost `MessageType.None` message when `relatedObjects` is empty/null. |
| 15 | +> - `ExceptionHelper.PreserveStackTrace` now returns `ExceptionDispatchInfo` instead of `void`. |
| 16 | +> - `RelatedObjectModel.ToString()` is null-safe. |
| 17 | +> - New combinators added: `Map`, `Bind`, `Match`, `Tap` (sync + async), `Validate` / `Ensure`, `FunctionExtensionsAsync.*Async`. |
| 18 | +
|
| 19 | +--- |
| 20 | + |
| 21 | +## 1. Compile-time obsoletions |
| 22 | + |
| 23 | +These changes raise `CS0618` warnings. Builds with `<TreatWarningsAsErrors>true</TreatWarningsAsErrors>` will **fail**. Either suppress with `#pragma warning disable CS0618` or migrate to the replacements below. |
| 24 | + |
| 25 | +### 1.1 `Result<T>.Instance` to `Result<T>.Create()` |
| 26 | + |
| 27 | +`Instance` was misleading, every access already returned a *new* instance. The new factory makes intent explicit. |
| 28 | + |
| 29 | +```csharp |
| 30 | +// Before |
| 31 | +var r = Result<Foo>.Instance; |
| 32 | + |
| 33 | +// After |
| 34 | +var r = Result<Foo>.Create(); |
| 35 | +``` |
| 36 | + |
| 37 | +### 1.2 `ActionOnSuccess` to `Tap` |
| 38 | + |
| 39 | +```csharp |
| 40 | +// Before |
| 41 | +result.ActionOnSuccess(r => _logger.LogInformation("ok: {V}", r.Response)); |
| 42 | + |
| 43 | +// After |
| 44 | +result.Tap(value => _logger.LogInformation("ok: {V}", value)); |
| 45 | +``` |
| 46 | + |
| 47 | +`Tap` returns the same instance for chaining and only invokes the action on success. |
| 48 | + |
| 49 | +### 1.3 `ActionOnFailure` / `ActionOn` to `Match` |
| 50 | + |
| 51 | +```csharp |
| 52 | +// Before |
| 53 | +result.ActionOn( |
| 54 | + onSuccess: r => _audit.Saved(r.Response), |
| 55 | + onFailure: r => _logger.LogError("failed: {Msg}", r.GetFirstMessage())); |
| 56 | + |
| 57 | +// After (side-effect form returns the same IResult) |
| 58 | +result.Match( |
| 59 | + onSuccess: r => _audit.Saved(((Result<Foo>)r).Response), |
| 60 | + onFailure: r => _logger.LogError("failed: {Msg}", r.GetFirstMessage())); |
| 61 | + |
| 62 | +// After (fold-into-value form — the recommended pattern when you want a return value) |
| 63 | +int httpStatus = result.Match( |
| 64 | + onSuccess: _ => 200, |
| 65 | + onFailure: _ => 500); |
| 66 | +``` |
| 67 | + |
| 68 | +### 1.4 `FunctionOn*` / `ExecuteFunction` taking `Func<Task<TResult>>` to `*Async` equivalents |
| 69 | + |
| 70 | +The seven sync-over-async overloads in `FunctionExtensions` are obsolete because awaiting a `Func<Task<T>>` from a synchronous extension is a possible deadlock. Use `RzR.ResultMessage.Extensions.Result.Functions.FunctionExtensionsAsync` instead. |
| 71 | + |
| 72 | +```csharp |
| 73 | +// Before- sync-over-async |
| 74 | +var r = result.FunctionOnSuccess(async r => await _store.SaveAsync(r.Response)); |
| 75 | + |
| 76 | +// After |
| 77 | +var r = await result.FunctionOnSuccessAsync(async r => await _store.SaveAsync(r.Response)); |
| 78 | +``` |
| 79 | + |
| 80 | +| Before | After | |
| 81 | +| --------------------------------------------------- | ------------------------------------------------------------- | |
| 82 | +| `FunctionOnSuccess(Func<TResult, Task<TOut>>)` | `FunctionOnSuccessAsync(Func<TResult, Task<TOut>>)` | |
| 83 | +| `FunctionOnFailure(Func<TResult, Task<TOut>>)` | `FunctionOnFailureAsync(Func<TResult, Task<TOut>>)` | |
| 84 | +| `FunctionOn(...) ` 4 overloads with async delegates | `FunctionOnAsync(...)` 4 overloads | |
| 85 | +| `ExecuteFunction(Func<TResult, Task<TOut>>)` | `ExecuteFunctionAsync(Func<TResult, Task<TOut>>)` | |
| 86 | + |
| 87 | +--- |
| 88 | + |
| 89 | +## 2. Runtime behavior changes (silent- read carefully) |
| 90 | + |
| 91 | +These do **not** raise warnings, but can change observable behavior. |
| 92 | + |
| 93 | +### 2.1 Implicit `Exception -> Result` / `Result<T>` throws on `null` |
| 94 | + |
| 95 | +```csharp |
| 96 | +// Before |
| 97 | +Result r = (Exception)null; // r.IsSuccess == false, r.Messages empty (silent) |
| 98 | +
|
| 99 | +// After |
| 100 | +Result r = (Exception)null; // throws ArgumentNullException |
| 101 | +``` |
| 102 | + |
| 103 | +If you previously relied on the silent fallback, guard at the call site: |
| 104 | + |
| 105 | +```csharp |
| 106 | +Exception ex = TryGetException(); |
| 107 | +Result r = ex is null ? Result.Failure() : ex; |
| 108 | +``` |
| 109 | + |
| 110 | +### 2.2 `Result<T>(Exception)` ctor adds one message instead of two |
| 111 | + |
| 112 | +```csharp |
| 113 | +// Before |
| 114 | +new Result<Foo>(ex).Messages.Count; // 2 (empty info + trace) |
| 115 | +
|
| 116 | +// After |
| 117 | +new Result<Foo>(ex).Messages.Count; // 1 (single MessageType.Exception entry) |
| 118 | +``` |
| 119 | + |
| 120 | +If your tests asserted `Count == 2`, change them to `Count == 1`. |
| 121 | + |
| 122 | +### 2.3 `GetFirstMessage` / `GetFirstError` fall back to exception messages |
| 123 | + |
| 124 | +When a result contains only exception messages (no plain `Info`/`Error` text), these helpers used to return an empty string. They now return the exception's message text. |
| 125 | + |
| 126 | +```csharp |
| 127 | +// Before |
| 128 | +new Result<Foo>(new InvalidOperationException("boom")).GetFirstMessage(); // "" |
| 129 | +
|
| 130 | +// After |
| 131 | +new Result<Foo>(new InvalidOperationException("boom")).GetFirstMessage(); // "boom" |
| 132 | +``` |
| 133 | + |
| 134 | +### 2.4 `JoinErrors(IEnumerable<Result>)` derives `IsSuccess` from the collection |
| 135 | + |
| 136 | +Previously the joined result inherited `IsSuccess` from the calling instance, which was a bug — joining a failed result with a list of successes incorrectly stayed failed (and vice versa). |
| 137 | + |
| 138 | +```csharp |
| 139 | +// Before |
| 140 | +var joined = Result<int>.Success().JoinErrors(new[] { Result.Failure("e") }); |
| 141 | +joined.IsSuccess; // true (wrong-inherited from caller) |
| 142 | +
|
| 143 | +// After |
| 144 | +var joined = Result<int>.Success().JoinErrors(new[] { Result.Failure("e") }); |
| 145 | +joined.IsSuccess; // false (correctly: not all inputs are successful) |
| 146 | +``` |
| 147 | + |
| 148 | +### 2.5 `Success<T>(T, params RelatedObjectModel[])` no longer adds a ghost message |
| 149 | + |
| 150 | +```csharp |
| 151 | +// Before |
| 152 | +Result<Foo>.Success(foo).Messages.Count; // 1 (a stray MessageType.None entry) |
| 153 | +Result<Foo>.Success(foo, related).Messages.Count; // 1 (the related-object message) |
| 154 | +
|
| 155 | +// After |
| 156 | +Result<Foo>.Success(foo).Messages.Count; // 0 |
| 157 | +Result<Foo>.Success(foo, related).Messages.Count; // 1 (unchanged) |
| 158 | +``` |
| 159 | + |
| 160 | +If you asserted `Messages.Count == 1` for a plain `Success(value)` call, update to `0`. |
| 161 | + |
| 162 | +### 2.6 `ExceptionHelper.PreserveStackTrace` signature change |
| 163 | + |
| 164 | +Rewritten on top of `ExceptionDispatchInfo`. |
| 165 | + |
| 166 | +```csharp |
| 167 | +// Before |
| 168 | +public static void PreserveStackTrace(Exception ex); |
| 169 | +ExceptionHelper.PreserveStackTrace(ex); |
| 170 | +throw ex; |
| 171 | + |
| 172 | +// After |
| 173 | +public static ExceptionDispatchInfo PreserveStackTrace(Exception ex); |
| 174 | +ExceptionHelper.PreserveStackTrace(ex).Throw(); |
| 175 | +``` |
| 176 | + |
| 177 | +### 2.7 `RelatedObjectModel.ToString()` is null-safe |
| 178 | + |
| 179 | +Calling `ToString()` on a `RelatedObjectModel` with a `null` `InDataSourceNames` no longer throws `NullReferenceException`. Output format for the null case: |
| 180 | + |
| 181 | +``` |
| 182 | +InCodeName: <name> <-> InDataSourceName: |
| 183 | +``` |
| 184 | + |
| 185 | +If you parse `ToString()` output (not recommended), allow for a trailing empty segment. |
| 186 | + |
| 187 | +--- |
| 188 | + |
| 189 | +## 3. New APIs (additive — no migration required, but recommended) |
| 190 | + |
| 191 | +### 3.1 Synchronous monadic combinators |
| 192 | + |
| 193 | +Available as instance methods on `Result<T>`: |
| 194 | + |
| 195 | +```csharp |
| 196 | +Result<int> mapped = source.Map(x => x.Length); |
| 197 | +Result<Order> bound = source.Bind(id => _repo.GetOrder(id)); |
| 198 | +int value = source.Match(onSuccess: r => 200, onFailure: _ => 500); |
| 199 | +Result<int> same = source.Tap(v => _logger.LogInformation("v={V}", v)); |
| 200 | +``` |
| 201 | + |
| 202 | +### 3.2 Async combinators |
| 203 | + |
| 204 | +Available as extension methods in `RzR.ResultMessage.Extensions.Result`. Each combinator is offered both on `Result<T>` and on `Task<Result<T>>`, with sync and async delegates, so a full pipeline composes fluently: |
| 205 | + |
| 206 | +```csharp |
| 207 | +using RzR.ResultMessage.Extensions.Result; |
| 208 | + |
| 209 | +var dto = await _repo.GetOrderByIdAsync(id) // Task<Result<Order>> |
| 210 | + .MapAsync(o => o.ToSummary()) // sync projection |
| 211 | + .BindAsync(async s => await _enricher.EnrichAsync(s)) |
| 212 | + .TapAsync(async s => await _audit.WriteAsync(s)) |
| 213 | + .MatchAsync( |
| 214 | + onSuccess: s => OrderResponse.From(s), |
| 215 | + onFailure: r => OrderResponse.Error(r.GetFirstError())); |
| 216 | +``` |
| 217 | + |
| 218 | +### 3.3 Validation aggregation: `Validate` / `Ensure` |
| 219 | + |
| 220 | +| Method | Behavior | |
| 221 | +| ------------------------------- | --------------------------------------------------------------------------------------------------- | |
| 222 | +| `Validate(predicate, error)` | Always evaluates; chain to **accumulate** every violation. Overloads for `(key, error)` and `MessageDataModel`. | |
| 223 | +| `Ensure(predicate, error)` | **Short-circuits** once `IsSuccess == false`, safe for guard chains where later predicates would NRE. | |
| 224 | +| `ValidateAsync(...)` | Async predicate, on both `Result<T>` and `Task<Result<T>>`. | |
| 225 | + |
| 226 | +```csharp |
| 227 | +// Accumulating |
| 228 | +var result = Result<Order>.Success(order) |
| 229 | + .Validate(o => o.Items.Count > 0, "items required") |
| 230 | + .Validate(o => o.Total > 0, "total > 0") |
| 231 | + .Validate(o => o.Customer != null, "customer required"); |
| 232 | + |
| 233 | +// Short-circuiting (later predicates skipped if any earlier one fails) |
| 234 | +var safe = Result<User>.Success(user) |
| 235 | + .Ensure(u => u != null, "user required") |
| 236 | + .Ensure(u => !string.IsNullOrEmpty(u.Email), "email required") |
| 237 | + .Ensure(u => u.Email.Contains("@"), "email must be valid"); |
| 238 | +``` |
| 239 | + |
| 240 | +--- |
| 241 | + |
| 242 | +## 4. Backward-compatibility shims considered |
| 243 | + |
| 244 | +The obsolete attributes still allow existing code to compile and run. There is **no compatibility shim** for the runtime behavior changes in §2 — they are intentional bug fixes. If you depended on the old behavior, you must update at the call site. |
| 245 | + |
| 246 | +If you need to stay on the old behavior temporarily, pin the previous major version in your `PackageReference` while you migrate. |
0 commit comments