|
| 1 | +--- |
| 2 | +title: Migration Guide v2 |
| 3 | +slug: migration-guide-v2 |
| 4 | +description: Migration guide to upgrade to v2 |
| 5 | +--- |
| 6 | + |
| 7 | +# Migration Guide to v2 |
| 8 | + |
| 9 | +This guide will help you migrate to v2 |
| 10 | + |
| 11 | +## Logging |
| 12 | + |
| 13 | +### Breaking changes from v1 (dependency updates) |
| 14 | + |
| 15 | +!!! info |
| 16 | + |
| 17 | + Looking for V1 specific documentation please go to [Logging v1](/lambda/dotnet/core/logging-v1) |
| 18 | + |
| 19 | +| Change | Before (v1.x) | After (v2.0) | Migration Action | |
| 20 | +|--------|---------------|--------------|-----------------| |
| 21 | +| Amazon.Lambda.Core | 2.2.0|2.5.0 | dotnet add package Amazon.Lambda.Core | |
| 22 | +| Amazon.Lambda.Serialization.SystemTextJson | 2.4.3 | 2.4.4 | dotnet add package Amazon.Lambda.Serialization.SystemTextJson | |
| 23 | +| Microsoft.Extensions.DependencyInjection | 8.0.0 | 8.0.1 | dotnet add package Microsoft.Extensions.DependencyInjection | |
| 24 | + |
| 25 | +#### Extra keys - Breaking change |
| 26 | + |
| 27 | +In v1.x, the extra keys were added to the log entry as a dictionary. In v2.x, the extra keys are added to the log entry as |
| 28 | +a JSON object. |
| 29 | + |
| 30 | +There is no longer a method that accepts extra keys as first argument. |
| 31 | + |
| 32 | +=== "Before (v1)" |
| 33 | + |
| 34 | + ```csharp |
| 35 | + public class User |
| 36 | + { |
| 37 | + public string Name { get; set; } |
| 38 | + public int Age { get; set; } |
| 39 | + } |
| 40 | + |
| 41 | + Logger.LogInformation<User>(user, "{Name} is {Age} years old", |
| 42 | + new object[]{user.Name, user.Age}); |
| 43 | + |
| 44 | + var scopeKeys = new |
| 45 | + { |
| 46 | + PropOne = "Value 1", |
| 47 | + PropTwo = "Value 2" |
| 48 | + }; |
| 49 | + Logger.LogInformation(scopeKeys, "message"); |
| 50 | + |
| 51 | + ``` |
| 52 | + |
| 53 | +=== "After (v2)" |
| 54 | + |
| 55 | + ```csharp |
| 56 | + public class User |
| 57 | + { |
| 58 | + public string Name { get; set; } |
| 59 | + public int Age { get; set; } |
| 60 | + |
| 61 | + public override string ToString() |
| 62 | + { |
| 63 | + return $"{Name} is {Age} years old"; |
| 64 | + } |
| 65 | + } |
| 66 | + |
| 67 | + // It uses the ToString() method of the object to log the message |
| 68 | + // the extra keys are added because of the {@} in the message template |
| 69 | + Logger.LogInformation("{@user}", user); |
| 70 | + |
| 71 | + var scopeKeys = new |
| 72 | + { |
| 73 | + PropOne = "Value 1", |
| 74 | + PropTwo = "Value 2" |
| 75 | + }; |
| 76 | + |
| 77 | + // there is no longer a method that accepts extra keys as first argument. |
| 78 | + Logger.LogInformation("{@keys}", scopeKeys); |
| 79 | + ``` |
| 80 | + |
| 81 | +This change was made to improve the performance of the logger and to make it easier to work with the extra keys. |
| 82 | + |
| 83 | +## Metrics |
| 84 | + |
| 85 | +### Breaking changes from V1 |
| 86 | + |
| 87 | +!!! info |
| 88 | + |
| 89 | + Loooking for v1 specific documentation please go to [Metrics v1](/lambda/dotnet/core/metrics-v1) |
| 90 | + |
| 91 | +* **`Dimensions`** outputs as an array of arrays instead of an array of objects. Example: `Dimensions: [["service", "Environment"]]` instead of `Dimensions: ["service", "Environment"]` |
| 92 | +* **`FunctionName`** is not added as default dimension and only to cold start metric. |
| 93 | +* **`Default Dimensions`** can now be included in Cold Start metrics, this is a potential breaking change if you were relying on the absence of default dimensions in Cold Start metrics when searching. |
| 94 | + |
| 95 | +<br /> |
| 96 | + |
| 97 | +<figure> |
| 98 | + <img src="../../media/metrics_utility_showcase.png" loading="lazy" alt="Screenshot of the Amazon CloudWatch Console showing an example of business metrics in the Metrics Explorer" /> |
| 99 | + <figcaption>Metrics showcase - Metrics Explorer</figcaption> |
| 100 | +</figure> |
| 101 | + |
0 commit comments