Merge pull request #1 from sliedig/amirkaws-feature-parameters

docs: updates and fixes to docs for parametes

Author: amirkaws

README.md

@@ -1,6 +1,6 @@
 # AWS Lambda Powertools for .NET
 
-![aws provider](https://img.shields.io/badge/provider-AWS-orange?logo=amazon-aws&color=ff9900) 
+![aws provider](https://img.shields.io/badge/provider-AWS-orange?logo=amazon-aws&color=ff9900)
 [![Build](https://github.com/awslabs/aws-lambda-powertools-dotnet/actions/workflows/build.yml/badge.svg?branch=develop)](https://github.com/awslabs/aws-lambda-powertools-dotnet/actions/workflows/build.yml)
 [![Join our Discord](https://dcbadge.vercel.app/api/server/B8zZKbbyET)](https://discord.gg/B8zZKbbyET)
 
@@ -20,9 +20,11 @@ Lambda Powertools provides three core utilities:
 
 * **[Tracing](https://awslabs.github.io/aws-lambda-powertools-dotnet/core/tracing/)** - provides a simple way to send traces from functions to AWS X-Ray to provide visibility into function calls, interactions with other AWS services, or external HTTP requests. Annotations can easily be added to traces to allow filtering traces based on key information. For example, when using Tracer, a ColdStart annotation is created for you so you can easily group and analyze traces where there was an initialization overhead.
 
+* **[Parameters (developer preview)](https://awslabs.github.io/aws-lambda-powertools-dotnet/core/parameters/)** - provides high-level functionality to retrieve one or multiple parameter values from [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html){target="_blank"}, [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/){target="_blank"}, or [Amazon DynamoDB](https://aws.amazon.com/dynamodb/){target="_blank"}. We also provide extensibility to bring your own providers.
+
 ### Installation
 
-The AWS Lambda Powertools for .NET utilities (.NET 6) are available as NuGet packages. You can install the packages from the NuGet gallery or from within the Visual Studio IDE. Search `AWS.Lambda.Powertools*` to see various utilities available. Powertools is available on NuGet.
+The AWS Lambda Powertools for .NET utilities (.NET 6) are available as NuGet packages. You can install the packages from [NuGet Gallery](https://www.nuget.org/packages?q=AWS+Lambda+Powertools*){target="_blank"} or from Visual Studio editor by searching `AWS.Lambda.Powertools*` to see various utilities available.
 
 * [AWS.Lambda.Powertools.Logging](https://www.nuget.org/packages?q=AWS.Lambda.Powertools.Logging):
 
@@ -36,6 +38,10 @@ The AWS Lambda Powertools for .NET utilities (.NET 6) are available as NuGet pac
 
     `dotnet add package AWS.Lambda.Powertools.Tracing`
 
+* [AWS.Lambda.Powertools.Parameters](https://www.nuget.org/packages?q=AWS.Lambda.Powertools.Parameters):
+
+    `dotnet add package AWS.Lambda.Powertools.AWS.Lambda.Powertools.Parameters`
+
 ## Examples
 
 We have provided examples focused specifically on each of the utilities. Each solution comes with an AWS Serverless Application Model (AWS SAM) templates to run your functions as a Zip package using the AWS Lambda .NET 6 managed runtime; or as a container package using the AWS base images for .NET.
@@ -66,7 +72,7 @@ We welcome contributions from developers of all levels to our open-source projec
 ## Connect
 
 * **AWS Lambda Powertools on Discord**: `#dotnet` - **[Invite link](https://discord.gg/B8zZKbbyET)**
-* **Email**: [email protected]
+* **Email**: <[email protected]>
 
 ## License
 

docs/core/logging.md

@@ -12,6 +12,14 @@ The logging utility provides a Lambda optimized logger with output structured as
 * Log sampling enables DEBUG log level for a percentage of requests (disabled by default)
 * Append additional keys to structured log at any point in time
 
+## Installation
+
+Powertools are available as NuGet packages. You can install the packages from [NuGet Gallery](https://www.nuget.org/packages?q=AWS+Lambda+Powertools*){target="_blank"} or from Visual Studio editor by searching `AWS.Lambda.Powertools*` to see various utilities available.
+
+* [AWS.Lambda.Powertools.Logging](https://www.nuget.org/packages?q=AWS.Lambda.Powertools.Logging):
+
+    `dotnet add package AWS.Lambda.Powertools.Logging`
+
 ## Getting started
 
 Logging requires two settings:

docs/core/metrics.md

@@ -9,7 +9,7 @@ These metrics can be visualized through [Amazon CloudWatch Console](https://aws.
 
 ## Key features
 
-* Aggregate up to 100 metrics using a single CloudWatch EMF object (large JSON blob)
+* Aggregate up to 100 metrics using a single [CloudWatch EMF](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Specification.html){target="_blank"} object (large JSON blob)
 * Validating your metrics against common metric definitions mistakes (for example, metric unit, values, max dimensions, max metrics)
 * Metrics are created asynchronously by the CloudWatch service. You do not need any custom stacks, and there is no impact to Lambda function latency
 * Context manager to create a one off metric with a different dimension
@@ -21,6 +21,14 @@ These metrics can be visualized through [Amazon CloudWatch Console](https://aws.
   <figcaption>Metrics showcase - Metrics Explorer</figcaption>
 </figure>
 
+## Installation
+
+Powertools are available as NuGet packages. You can install the packages from [NuGet Gallery](https://www.nuget.org/packages?q=AWS+Lambda+Powertools*){target="_blank"} or from Visual Studio editor by searching `AWS.Lambda.Powertools*` to see various utilities available.
+
+* [AWS.Lambda.Powertools.Metrics](https://www.nuget.org/packages?q=AWS.Lambda.Powertools.Metrics):
+
+    `dotnet nuget add AWS.Lambda.Powertools.Metrics`
+
 ## Terminologies
 
 If you're new to Amazon CloudWatch, there are two terminologies you must be aware of before using this utility:
@@ -378,3 +386,21 @@ CloudWatch EMF uses the same dimensions across all your metrics. Use **`PushSing
                     });
         ...
     ```
+
+## Testing your code
+
+### Environment variables
+
+???+ tip
+	Ignore this section, if:
+
+    * You are explicitly setting namespace/default dimension via `namespace` and `service` parameters
+    * You're not instantiating `Metrics` in the global namespace
+
+	For example, `Metrics(namespace="ExampleApplication", service="booking")`
+
+Make sure to set `POWERTOOLS_METRICS_NAMESPACE` and `POWERTOOLS_SERVICE_NAME` before running your tests to prevent failing on `SchemaValidation` exception. You can set it before you run tests by adding the environment variable.
+
+```csharp title="Injecting Metric Namespace before running tests"
+Environment.SetEnvironmentVariable("POWERTOOLS_METRICS_NAMESPACE","AWSLambdaPowertools");
+```

docs/core/tracing.md

@@ -10,12 +10,20 @@ a provides functionality to reduce the overhead of performing common tracing tas
 
 ## Key Features
 
-* Helper methods to improve the developer experience for creating [custom AWS X-Ray subsegments](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-dotnet-subsegments.html).
+* Helper methods to improve the developer experience for creating [custom AWS X-Ray subsegments](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-dotnet-subsegments.html){target=blank}.
 * Capture cold start as annotation.
 * Capture function responses and full exceptions as metadata.
 * Better experience when developing with multiple threads.
 * Auto-patch supported modules by AWS X-Ray
 
+## Installation
+
+Powertools are available as NuGet packages. You can install the packages from [NuGet Gallery](https://www.nuget.org/packages?q=AWS+Lambda+Powertools*){target="_blank"} or from Visual Studio editor by searching `AWS.Lambda.Powertools*` to see various utilities available.
+
+* [AWS.Lambda.Powertools.Tracing](https://www.nuget.org/packages?q=AWS.Lambda.Powertools.Tracing):
+
+    `dotnet nuget add AWS.Lambda.Powertools.Tracing`
+
 ## Getting Started
 
 Before you use this utility, your AWS Lambda function [must have permissions](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html#services-xray-permissions) to send traces to AWS X-Ray.

docs/utilities/parameters.md

@@ -3,19 +3,22 @@ title: Parameters
 description: Utility
 ---
 
+???+ warning
+	**This utility is currently in developer preview** and is intended strictly for feedback and testing purposes **and not for production workloads**. The version and all future versions tagged with the `-preview` suffix should be treated as not stable. Until this utility is [General Availability](https://github.com/awslabs/aws-lambda-powertools-dotnet/milestone/2) we may introduce significant breaking changes and improvements in response to customers feedback.
+
 <!-- markdownlint-disable MD013 -->
-The parameters utility provides high-level functions to retrieve one or multiple parameter values from [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html){target="_blank"}, [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/){target="_blank"}, [Amazon DynamoDB](https://aws.amazon.com/dynamodb/){target="_blank"}, or bring your own.
+The Parameters utility provides high-level functionality to retrieve one or multiple parameter values from [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html){target="_blank"}, [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/){target="_blank"}, or [Amazon DynamoDB](https://aws.amazon.com/dynamodb/){target="_blank"}. We also provide extensibility to bring your own providers.
 
 ## Key features
 
 * Retrieve one or multiple parameters from the underlying provider
 * Cache parameter values for a given amount of time (defaults to 5 seconds)
 * Transform parameter values from JSON or base 64 encoded strings
-* Bring Your Own Parameter Store Provider
+* Bring your own parameter store provider
 
-## Install
+## Installation
 
-Powertools are available as NuGet packages. You can install the packages from NuGet gallery or from Visual Studio editor. Search `AWS.Lambda.Powertools*` to see various utilities available.
+Powertools are available as NuGet packages. You can install the packages from [NuGet Gallery](https://www.nuget.org/packages?q=AWS+Lambda+Powertools*){target="_blank"} or from Visual Studio editor by searching `AWS.Lambda.Powertools*` to see various utilities available.
 
 * [AWS.Lambda.Powertools.Parameters](https://www.nuget.org/packages?q=AWS.Lambda.Powertools.Parameters):
 
@@ -35,8 +38,8 @@ DynamoDB | `DynamoDBProvider.GetMultiple(string)` `DynamoDBProvider.GetMultiple<
 
 ## SSM Parameter Store
 
-You can retrieve a single parameter using SsmProvider.Get() and pass the key of the parameter.
-For multiple parameters, you can use SsmProvider.GetMultiple() and pass the path to retrieve them all.
+You can retrieve a single parameter using `SsmProvider.Get()` and pass the key of the parameter.
+For multiple parameters, you can use `SsmProvider.GetMultiple()` and pass the path to retrieve them all.
 
 Alternatively, you can retrieve the instance of provider and configure its underlying SDK client,
 in order to get data from other regions or use specific credentials.
@@ -179,10 +182,9 @@ For secrets stored in Secrets Manager, use `SecretsProvider`.
 Alternatively, you can retrieve the instance of provider and configure its underlying SDK client,
 in order to get data from other regions or use specific credentials.
 
-
 === "SecretsProvider"
 
-     ```c# hl_lines="13-15"
+    ```c# hl_lines="13-15"
     using AWS.Lambda.Powertools.Parameters;
     using AWS.Lambda.Powertools.Parameters.SecretsManager;
 
@@ -224,7 +226,7 @@ in order to get data from other regions or use specific credentials.
     }
     ```
 
-=== "SecretsProvider with a custom clieent"
+=== "SecretsProvider with a custom client"
 
     ```c# hl_lines="11 14 15"
     using Amazon.SecretsManager;
@@ -263,16 +265,15 @@ For single parameters, you must use `id` as the [partition key](https://docs.aws
 
 	DynamoDB table with `id` partition key and `value` as attribute
 
- | id           | value    |
- | ------------ | -------- |
- | my-parameter | my-value |
-
-With this table, `DynamoDBProvider.Get("my-param")` will return `my-value`.
+    | id           | value    |
+    | ------------ | -------- |
+    | my-parameter | my-value |
 
+    With this table, `DynamoDBProvider.Get("my-param")` will return `my-value`.
 
 === "DynamoDBProvider"
 
-     ```c# hl_lines="10 11 14-16"
+    ```c# hl_lines="10 11 14-16"
     using AWS.Lambda.Powertools.Parameters;
     using AWS.Lambda.Powertools.Parameters.DynamoDB;
 
@@ -301,17 +302,17 @@ You can retrieve multiple parameters sharing the same `id` by having a sort key
 
 	DynamoDB table with `id` primary key, `sk` as sort key` and `value` as attribute
 
- | id          | sk      | value      |
- | ----------- | ------- | ---------- |
- | my-hash-key | param-a | my-value-a |
- | my-hash-key | param-b | my-value-b |
- | my-hash-key | param-c | my-value-c |
+    | id          | sk      | value      |
+    | ----------- | ------- | ---------- |
+    | my-hash-key | param-a | my-value-a |
+    | my-hash-key | param-b | my-value-b |
+    | my-hash-key | param-c | my-value-c |
 
-With this table, `DynamoDBProvider.GetMultiple("my-hash-key")` will return a dictionary response in the shape of `sk:value`.
+    With this table, `DynamoDBProvider.GetMultiple("my-hash-key")` will return a dictionary response in the shape of `sk:value`.
 
 === "DynamoDBProvider"
 
-     ```c# hl_lines="10 11 14-16"
+    ```c# hl_lines="10 11 14-16"
     using AWS.Lambda.Powertools.Parameters;
     using AWS.Lambda.Powertools.Parameters.DynamoDB;
 
@@ -354,7 +355,7 @@ DynamoDB provider can be customized at initialization to match your table struct
 
 === "DynamoDBProvider"
 
-     ```c# hl_lines="10-17"
+    ```c# hl_lines="10-17"
     using AWS.Lambda.Powertools.Parameters;
     using AWS.Lambda.Powertools.Parameters.DynamoDB;
 
@@ -383,7 +384,7 @@ DynamoDB provider can be customized at initialization to match your table struct
 By default, all parameters and their corresponding values are cached for 5 seconds.
 
 You can customize this default value using `DefaultMaxAge`. You can also customize this value for each parameter using 
-`WithMaxAge`. 
+`WithMaxAge`.
 
 If you'd like to always ensure you fetch the latest parameter from the store regardless if already available in cache, use `ForceFetch`.
 

libraries/src/AWS.Lambda.Powertools.Parameters/README.md

@@ -0,0 +1,51 @@
+# AWS.Lambda.Powertools.Parameters
+
+The Parameters utility provides high-level functionality to retrieve one or multiple parameter values from [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html), [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/), or [Amazon DynamoDB](https://aws.amazon.com/dynamodb/). Or bring your own providers.
+
+## Key features
+
+* Retrieve one or multiple parameters from the underlying provider
+* Cache parameter values for a given amount of time (defaults to 5 seconds)
+* Transform parameter values from JSON or base 64 encoded strings
+* Bring your own parameter store provider
+
+## Read the docs
+
+For a full list of features go to [awslabs.github.io/aws-lambda-powertools-dotnet/utilities/parameters/](awslabs.github.io/aws-lambda-powertools-dotnet/utilities/parameters/)
+
+GitHub: <https://github.com/awslabs/aws-lambda-powertools-dotnet/>
+
+## Sample Function using AWS Systems Manager Parameter Store
+
+```csharp
+using AWS.Lambda.Powertools.Logging;
+using AWS.Lambda.Powertools.Parameters;
+using AWS.Lambda.Powertools.Parameters.SimpleSystemsManagement;
+
+namespace HelloWorld;
+
+public class Function
+{
+    [Logging(LogEvent = true)]
+    public async Task<APIGatewayProxyResponse> FunctionHandler(APIGatewayProxyRequest apigwProxyEvent,
+        ILambdaContext context)
+    {    
+        // Get SSM Provider instance
+        ISsmProvider ssmProvider = ParametersManager.SsmProvider;
+
+        // Retrieve a single parameter
+        string? value = await ssmProvider
+            .GetAsync("/my/parameter")
+            .ConfigureAwait(false);
+
+        // Retrieve multiple parameters from a path prefix
+        // This returns a Dictionary with the parameter name as key
+        IDictionary<string, string?> values = await ssmProvider
+            .GetMultipleAsync("/my/path/prefix")
+            .ConfigureAwait(false);
+
+        ...
+
+    }
+}
+```