docs(metadata): extract inline code examples into snippet files (#1191)

Author: hjgraca

docs/snippets/metadata/GettingStarted.cs

@@ -0,0 +1,38 @@
+// This file is referenced by docs/utilities/metadata.md
+// via pymdownx.snippets (mkdocs).
+
+namespace AWS.Lambda.Powertools.Docs.Snippets.Metadata;
+
+// --8<-- [start:getting_started]
+using AWS.Lambda.Powertools.Metadata;
+
+public class Function
+{
+    public string Handler(object input, ILambdaContext context)
+    {
+        var azId = LambdaMetadata.AvailabilityZoneId;
+        return $"Running in AZ: {azId}";
+    }
+}
+// --8<-- [end:getting_started]
+
+// --8<-- [start:error_handling]
+using AWS.Lambda.Powertools.Metadata;
+using AWS.Lambda.Powertools.Metadata.Exceptions;
+
+try
+{
+    var azId = LambdaMetadata.AvailabilityZoneId;
+}
+catch (LambdaMetadataException ex)
+{
+    Console.WriteLine($"Failed to get metadata: {ex.Message}");
+
+    if (ex.StatusCode != -1)
+        Console.WriteLine($"HTTP Status: {ex.StatusCode}");
+}
+// --8<-- [end:error_handling]
+
+// --8<-- [start:refresh_metadata]
+LambdaMetadata.Refresh();
+// --8<-- [end:refresh_metadata]

docs/snippets/metadata/UseCases.cs

@@ -0,0 +1,43 @@
+// This file is referenced by docs/utilities/metadata.md
+// via pymdownx.snippets (mkdocs).
+
+namespace AWS.Lambda.Powertools.Docs.Snippets.Metadata;
+
+// --8<-- [start:multi_az_routing]
+using AWS.Lambda.Powertools.Metadata;
+
+public class Function
+{
+    public async Task<string> Handler(OrderRequest request, ILambdaContext context)
+    {
+        var endpoint = LambdaMetadata.AvailabilityZoneId switch
+        {
+            "use1-az1" => "https://service-az1.internal",
+            "use1-az2" => "https://service-az2.internal",
+            _ => "https://service.internal"
+        };
+
+        return await ProcessOrder(request, endpoint);
+    }
+}
+// --8<-- [end:multi_az_routing]
+
+// --8<-- [start:logging_with_metadata]
+using AWS.Lambda.Powertools.Logging;
+using AWS.Lambda.Powertools.Metadata;
+
+public class Function
+{
+    public Function()
+    {
+        Logger.AppendKey("az_id", LambdaMetadata.AvailabilityZoneId);
+    }
+
+    [Logging]
+    public string Handler(object input, ILambdaContext context)
+    {
+        Logger.LogInformation("Processing request");
+        return "Success";
+    }
+}
+// --8<-- [end:logging_with_metadata]

docs/utilities/metadata.md

@@ -22,16 +22,7 @@ dotnet add package AWS.Lambda.Powertools.Metadata
 ## Getting started
 
 ```csharp
-using AWS.Lambda.Powertools.Metadata;
-
-public class Function
-{
-    public string Handler(object input, ILambdaContext context)
-    {
-        var azId = LambdaMetadata.AvailabilityZoneId;
-        return $"Running in AZ: {azId}";
-    }
-}
+--8<-- "docs/snippets/metadata/GettingStarted.cs:getting_started"
 ```
 
 ## Available metadata
@@ -43,28 +34,15 @@ public class Function
 ## Error handling
 
 ```csharp
-using AWS.Lambda.Powertools.Metadata;
-using AWS.Lambda.Powertools.Metadata.Exceptions;
-
-try
-{
-    var azId = LambdaMetadata.AvailabilityZoneId;
-}
-catch (LambdaMetadataException ex)
-{
-    Console.WriteLine($"Failed to get metadata: {ex.Message}");
-    
-    if (ex.StatusCode != -1)
-        Console.WriteLine($"HTTP Status: {ex.StatusCode}");
-}
+--8<-- "docs/snippets/metadata/GettingStarted.cs:error_handling"
 ```
 
 ## Refreshing metadata
 
 Metadata remains constant for the Lambda sandbox lifetime. If you need to force a refresh:
 
 ```csharp
-LambdaMetadata.Refresh();
+--8<-- "docs/snippets/metadata/GettingStarted.cs:refresh_metadata"
 ```
 
 ## Thread safety
@@ -76,42 +54,11 @@ LambdaMetadata.Refresh();
 ### Multi-AZ routing
 
 ```csharp
-using AWS.Lambda.Powertools.Metadata;
-
-public class Function
-{
-    public async Task<string> Handler(OrderRequest request, ILambdaContext context)
-    {
-        var endpoint = LambdaMetadata.AvailabilityZoneId switch
-        {
-            "use1-az1" => "https://service-az1.internal",
-            "use1-az2" => "https://service-az2.internal",
-            _ => "https://service.internal"
-        };
-        
-        return await ProcessOrder(request, endpoint);
-    }
-}
+--8<-- "docs/snippets/metadata/UseCases.cs:multi_az_routing"
 ```
 
 ### Logging
 
 ```csharp
-using AWS.Lambda.Powertools.Logging;
-using AWS.Lambda.Powertools.Metadata;
-
-public class Function
-{
-    public Function()
-    {
-        Logger.AppendKey("az_id", LambdaMetadata.AvailabilityZoneId);
-    }
-
-    [Logging]
-    public string Handler(object input, ILambdaContext context)
-    {
-        Logger.LogInformation("Processing request");
-        return "Success";
-    }
-}
+--8<-- "docs/snippets/metadata/UseCases.cs:logging_with_metadata"
 ```