Powertools for AWS Lambda (.NET) are available as NuGet packages. You can install the packages from NuGet Gallery or from Visual Studio editor by searching AWS.Lambda.Powertools* to see various utilities available.
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.
1 2 3 4 5 6 7 8 91011121314151617181920212223
usingAWS.Lambda.Powertools.Parameters;usingAWS.Lambda.Powertools.Parameters.SimpleSystemsManagement;publicclassFunction{publicasyncTask<APIGatewayProxyResponse>FunctionHandler(APIGatewayProxyRequestapigProxyEvent,ILambdaContextcontext){// Get SSM Provider instanceISsmProviderssmProvider=ParametersManager.SsmProvider;// Retrieve a single parameterstring?value=awaitssmProvider.GetAsync("/my/parameter").ConfigureAwait(false);// Retrieve multiple parameters from a path prefix// This returns a Dictionary with the parameter name as keyIDictionary<string,string?>values=awaitssmProvider.GetMultipleAsync("/my/path/prefix").ConfigureAwait(false);}}
1 2 3 4 5 6 7 8 9101112131415161718192021222324
usingAWS.Lambda.Powertools.Parameters;usingAWS.Lambda.Powertools.Parameters.SimpleSystemsManagement;publicclassFunction{publicasyncTask<APIGatewayProxyResponse>FunctionHandler(APIGatewayProxyRequestapigProxyEvent,ILambdaContextcontext){// Get SSM Provider instanceISsmProviderssmProvider=ParametersManager.SsmProvider.ConfigureClient(RegionEndpoint.EUCentral1);// Retrieve a single parameterstring?value=awaitssmProvider.GetAsync("/my/parameter").ConfigureAwait(false);// Retrieve multiple parameters from a path prefix// This returns a Dictionary with the parameter name as keyIDictionary<string,string?>values=awaitssmProvider.GetMultipleAsync("/my/path/prefix").ConfigureAwait(false);}}
usingAmazon.SimpleSystemsManagement;usingAWS.Lambda.Powertools.Parameters;usingAWS.Lambda.Powertools.Parameters.SimpleSystemsManagement;publicclassFunction{publicasyncTask<APIGatewayProxyResponse>FunctionHandler(APIGatewayProxyRequestapigProxyEvent,ILambdaContextcontext){// Create a new instance of clientIAmazonSimpleSystemsManagementclient=newAmazonSimpleSystemsManagementClient();// Get SSM Provider instanceISsmProviderssmProvider=ParametersManager.SsmProvider.UseClient(client);// Retrieve a single parameterstring?value=awaitssmProvider.GetAsync("/my/parameter").ConfigureAwait(false);// Retrieve multiple parameters from a path prefix// This returns a Dictionary with the parameter name as keyIDictionary<string,string?>values=awaitssmProvider.GetMultipleAsync("/my/path/prefix").ConfigureAwait(false);}}
The AWS Systems Manager Parameter Store provider supports two additional arguments for the Get() and GetMultiple() methods:
Option
Default
Description
WithDecryption()
False
Will automatically decrypt the parameter.
Recursive()
False
For GetMultiple() only, will fetch all parameter values recursively based on a path prefix.
You can create SecureString parameters, which are parameters that have a plaintext parameter name and an encrypted parameter value. If you don't use the WithDecryption() option, you will get an encrypted value. Read here about best practices using KMS to secure your parameters.
Example:
1 2 3 4 5 6 7 8 910111213141516171819202122232425
usingAWS.Lambda.Powertools.Parameters;usingAWS.Lambda.Powertools.Parameters.SimpleSystemsManagement;publicclassFunction{publicasyncTask<APIGatewayProxyResponse>FunctionHandler(APIGatewayProxyRequestapigProxyEvent,ILambdaContextcontext){// Get SSM Provider instanceISsmProviderssmProvider=ParametersManager.SsmProvider;// Retrieve a single parameterstring?value=awaitssmProvider.WithDecryption().GetAsync("/my/parameter").ConfigureAwait(false);// Retrieve multiple parameters from a path prefix// This returns a Dictionary with the parameter name as keyIDictionary<string,string?>values=awaitssmProvider.Recursive().GetMultipleAsync("/my/path/prefix").ConfigureAwait(false);}}
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.
1 2 3 4 5 6 7 8 91011121314151617
usingAWS.Lambda.Powertools.Parameters;usingAWS.Lambda.Powertools.Parameters.SecretsManager;publicclassFunction{publicasyncTask<APIGatewayProxyResponse>FunctionHandler(APIGatewayProxyRequestapigProxyEvent,ILambdaContextcontext){// Get Secrets Provider instanceISecretsProvidersecretsProvider=ParametersManager.SecretsProvider;// Retrieve a single secretstring?value=awaitsecretsProvider.GetAsync("/my/secret").ConfigureAwait(false);}}
1 2 3 4 5 6 7 8 9101112131415161718
usingAWS.Lambda.Powertools.Parameters;usingAWS.Lambda.Powertools.Parameters.SecretsManager;publicclassFunction{publicasyncTask<APIGatewayProxyResponse>FunctionHandler(APIGatewayProxyRequestapigProxyEvent,ILambdaContextcontext){// Get Secrets Provider instanceISecretsProvidersecretsProvider=ParametersManager.SecretsProvider.ConfigureClient(RegionEndpoint.EUCentral1);// Retrieve a single secretstring?value=awaitsecretsProvider.GetAsync("/my/secret").ConfigureAwait(false);}}
1 2 3 4 5 6 7 8 910111213141516171819202122
usingAmazon.SecretsManager;usingAWS.Lambda.Powertools.Parameters;usingAWS.Lambda.Powertools.Parameters.SecretsManager;publicclassFunction{publicasyncTask<APIGatewayProxyResponse>FunctionHandler(APIGatewayProxyRequestapigProxyEvent,ILambdaContextcontext){// Create a new instance of clientIAmazonSecretsManagerclient=newAmazonSecretsManagerClient();// Get Secrets Provider instanceISecretsProvidersecretsProvider=ParametersManager.SecretsProvider.UseClient(client);// Retrieve a single secretstring?value=awaitsecretsProvider.GetAsync("/my/secret").ConfigureAwait(false);}}
For parameters stored in a DynamoDB table, use DynamoDBProvider.
DynamoDB table structure for single parameters
For single parameters, you must use id as the partition key for that table.
Example
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.
1 2 3 4 5 6 7 8 9101112131415161718
usingAWS.Lambda.Powertools.Parameters;usingAWS.Lambda.Powertools.Parameters.DynamoDB;publicclassFunction{publicasyncTask<APIGatewayProxyResponse>FunctionHandler(APIGatewayProxyRequestapigProxyEvent,ILambdaContextcontext){// Get DynamoDB Provider instanceIDynamoDBProviderdynamoDbProvider=ParametersManager.DynamoDBProvider.UseTable("my-table");// Retrieve a single parameterstring?value=awaitdynamoDbProvider.GetAsync("my-param").ConfigureAwait(false);}}
DynamoDB table structure for multiple values parameters
You can retrieve multiple parameters sharing the same id by having a sort key named sk.
Example
DynamoDB table with id primary key, sk as sort keyandvalue` 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
With this table, DynamoDBProvider.GetMultiple("my-hash-key") will return a dictionary response in the shape of sk:value.
1 2 3 4 5 6 7 8 9101112131415161718
usingAWS.Lambda.Powertools.Parameters;usingAWS.Lambda.Powertools.Parameters.DynamoDB;publicclassFunction{publicasyncTask<APIGatewayProxyResponse>FunctionHandler(APIGatewayProxyRequestapigProxyEvent,ILambdaContextcontext){// Get DynamoDB Provider instanceIDynamoDBProviderdynamoDbProvider=ParametersManager.DynamoDBProvider.UseTable("my-table");// Retrieve a single parameterIDictionary<string,string?>value=awaitdynamoDbProvider.GetMultipleAsync("my-hash-key").ConfigureAwait(false);}}
For application configurations in AWS AppConfig, use AppConfigProvider.
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.
1 2 3 4 5 6 7 8 91011121314151617181920
usingAWS.Lambda.Powertools.Parameters;usingAWS.Lambda.Powertools.Parameters.AppConfig;publicclassFunction{publicasyncTask<APIGatewayProxyResponse>FunctionHandler(APIGatewayProxyRequestapigProxyEvent,ILambdaContextcontext){// Get AppConfig Provider instanceIAppConfigProviderappConfigProvider=ParametersManager.AppConfigProvider.DefaultApplication("MyApplicationId").DefaultEnvironment("MyEnvironmentId").DefaultConfigProfile("MyConfigProfileId");// Retrieve a single configuration, latest versionIDictionary<string,string?>value=awaitappConfigProvider.GetAsync().ConfigureAwait(false);}}
1 2 3 4 5 6 7 8 9101112131415161718192021
usingAWS.Lambda.Powertools.Parameters;usingAWS.Lambda.Powertools.Parameters.AppConfig;publicclassFunction{publicasyncTask<APIGatewayProxyResponse>FunctionHandler(APIGatewayProxyRequestapigProxyEvent,ILambdaContextcontext){// Get AppConfig Provider instanceIAppConfigProviderappConfigProvider=ParametersManager.AppConfigProvider.ConfigureClient(RegionEndpoint.EUCentral1).DefaultApplication("MyApplicationId").DefaultEnvironment("MyEnvironmentId").DefaultConfigProfile("MyConfigProfileId");// Retrieve a single configuration, latest versionIDictionary<string,string?>value=awaitappConfigProvider.GetAsync().ConfigureAwait(false);}}
Using AWS AppConfig Feature Flags
Feature flagging is a powerful tool that allows safely pushing out new features in a measured and usually gradual way. AppConfig provider offers helper methods to make it easier to work with feature flags.
usingAWS.Lambda.Powertools.Parameters;usingAWS.Lambda.Powertools.Parameters.AppConfig;publicclassFunction{publicasyncTask<APIGatewayProxyResponse>FunctionHandler(APIGatewayProxyRequestapigProxyEvent,ILambdaContextcontext){// Get AppConfig Provider instanceIAppConfigProviderappConfigProvider=ParametersManager.AppConfigProvider.DefaultApplication("MyApplicationId").DefaultEnvironment("MyEnvironmentId").DefaultConfigProfile("MyConfigProfileId");// Check if feature flag is enabledvarisFeatureFlagEnabled=awaitappConfigProvider.IsFeatureFlagEnabledAsync("MyFeatureFlag").ConfigureAwait(false);if(isFeatureFlagEnabled){// Retrieve an attribute value of the feature flagvarstrAttValue=awaitappConfigProvider.GetFeatureFlagAttributeValueAsync<string>("MyFeatureFlag","StringAttribute").ConfigureAwait(false);// Retrieve another attribute value of the feature flagvarnumberAttValue=awaitappConfigProvider.GetFeatureFlagAttributeValueAsync<int>("MyFeatureFlag","NumberAttribute").ConfigureAwait(false);}}}
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.
If you'd like to always ensure you fetch the latest parameter from the store regardless if already available in cache, use ForceFetch.
1 2 3 4 5 6 7 8 9101112131415161718
usingAWS.Lambda.Powertools.Parameters;usingAWS.Lambda.Powertools.Parameters.SimpleSystemsManagement;publicclassFunction{publicasyncTask<APIGatewayProxyResponse>FunctionHandler(APIGatewayProxyRequestapigProxyEvent,ILambdaContextcontext){// Get SSM Provider instanceISsmProviderssmProvider=ParametersManager.SsmProvider.DefaultMaxAge(TimeSpan.FromSeconds(10));// Retrieve a single parameterstring?value=awaitssmProvider.GetAsync("/my/parameter").ConfigureAwait(false);}}
1 2 3 4 5 6 7 8 9101112131415161718
usingAWS.Lambda.Powertools.Parameters;usingAWS.Lambda.Powertools.Parameters.SimpleSystemsManagement;publicclassFunction{publicasyncTask<APIGatewayProxyResponse>FunctionHandler(APIGatewayProxyRequestapigProxyEvent,ILambdaContextcontext){// Get SSM Provider instanceISsmProviderssmProvider=ParametersManager.SsmProvider;// Retrieve a single parameterstring?value=awaitssmProvider.WithMaxAge(TimeSpan.FromSeconds(10)).GetAsync("/my/parameter").ConfigureAwait(false);}}
1 2 3 4 5 6 7 8 9101112131415161718
usingAWS.Lambda.Powertools.Parameters;usingAWS.Lambda.Powertools.Parameters.SimpleSystemsManagement;publicclassFunction{publicasyncTask<APIGatewayProxyResponse>FunctionHandler(APIGatewayProxyRequestapigProxyEvent,ILambdaContextcontext){// Get SSM Provider instanceISsmProviderssmProvider=ParametersManager.SsmProvider;// Retrieve a single parameterstring?value=awaitssmProvider.ForceFetch().GetAsync("/my/parameter").ConfigureAwait(false);}}
Parameter values can be transformed using WithTransformation(). Base64 and JSON transformations are provided.
For more complex transformation, you need to specify how to deserialize by writing your own transfomer.
1 2 3 4 5 6 7 8 9101112131415161718
usingAWS.Lambda.Powertools.Parameters;usingAWS.Lambda.Powertools.Parameters.SimpleSystemsManagement;publicclassFunction{publicasyncTask<APIGatewayProxyResponse>FunctionHandler(APIGatewayProxyRequestapigProxyEvent,ILambdaContextcontext){// Get SSM Provider instanceISsmProviderssmProvider=ParametersManager.SsmProvider;// Retrieve a single parametervarvalue=awaitssmProvider.WithTransformation(Transformation.Json).GetAsync<MyObj>("/my/parameter/json").ConfigureAwait(false);}}
1 2 3 4 5 6 7 8 9101112131415161718
usingAWS.Lambda.Powertools.Parameters;usingAWS.Lambda.Powertools.Parameters.SimpleSystemsManagement;publicclassFunction{publicasyncTask<APIGatewayProxyResponse>FunctionHandler(APIGatewayProxyRequestapigProxyEvent,ILambdaContextcontext){// Get SSM Provider instanceISsmProviderssmProvider=ParametersManager.SsmProvider;// Retrieve a single parametervarvalue=awaitssmProvider.WithTransformation(Transformation.Base64).GetAsync("/my/parameter/b64").ConfigureAwait(false);}}
If you use Transformation with GetMultiple(), you can have a single malformed parameter value. To prevent failing the entire request, the method will return a Null value for the parameters that failed to transform.
You can override this by using RaiseTransformationError(). If you do so, a single transform error will raise a TransformationException exception.
1 2 3 4 5 6 7 8 910111213141516171819
usingAWS.Lambda.Powertools.Parameters;usingAWS.Lambda.Powertools.Parameters.SimpleSystemsManagement;publicclassFunction{publicasyncTask<APIGatewayProxyResponse>FunctionHandler(APIGatewayProxyRequestapigProxyEvent,ILambdaContextcontext){// Get SSM Provider instanceISsmProviderssmProvider=ParametersManager.SsmProvider.RaiseTransformationError();// Retrieve a single parametervarvalue=awaitssmProvider.WithTransformation(Transformation.Json).GetAsync<MyObj>("/my/parameter/json").ConfigureAwait(false);}}
If you use Transformation with GetMultiple(), you might want to retrieve and transform parameters encoded in different formats.
You can do this with a single request by using Transformation.Auto. This will instruct any Parameter to to infer its type based on the suffix and transform it accordingly.
1 2 3 4 5 6 7 8 910111213141516171819
usingAWS.Lambda.Powertools.Parameters;usingAWS.Lambda.Powertools.Parameters.SimpleSystemsManagement;publicclassFunction{publicasyncTask<APIGatewayProxyResponse>FunctionHandler(APIGatewayProxyRequestapigProxyEvent,ILambdaContextcontext){// Get SSM Provider instanceISsmProviderssmProvider=ParametersManager.SsmProvider;// Retrieve multiple parameters from a path prefix// This returns a Dictionary with the parameter name as keyIDictionary<string,object?>values=awaitssmProvider.WithTransformation(Transformation.Auto).GetMultipleAsync("/param").ConfigureAwait(false);}}
For example, if you have two parameters with the following suffixes .json and .binary:
Parameter name
Parameter value
/param/a.json
[some encoded value]
/param/a.binary
[some encoded value]
The return of GetMultiple() with Transformation.Auto will be a dictionary like:
You can write your own transformer, by implementing the ITransformer interface and the Transform<T>(string) method.
For example, if you wish to deserialize XML into an object.
// Get SSM Provider instanceISsmProviderssmProvider=ParametersManager.SsmProvider.AddTransformer("XML",newXmlTransformer());// Retrieve a single parametervarvalue=awaitssmProvider.WithTransformation("XML").GetAsync<MyObj>("/my/parameter/xml").ConfigureAwait(false);
To simplify the use of the library, you can chain all method calls before a get.
123456
ssmProvider.DefaultMaxAge(TimeSpan.FromSeconds(10))// will set 10 seconds as the default cache TTL.WithMaxAge(TimeSpan.FromMinutes(1))// will set the cache TTL for this value at 1 minute.WithTransformation(Transformation.Json)// Will use JSON transfomer to deserializes JSON to an object.WithDecryption()// enable decryption of the parameter value.Get<MyObj>("/my/param");// finally get the value
You can create your own custom parameter provider by inheriting the BaseProvider class and implementing the
String getValue(String key) method to retrieve data from your underlying store. All transformation and caching logic is handled by the get() methods in the base class.
publicclassS3Provider:ParameterProvider{privatestring_bucket;privatereadonlyIAmazonS3_client;publicS3Provider(){_client=newAmazonS3Client();}publicS3Provider(IAmazonS3client){_client=client;}publicS3ProviderWithBucket(stringbucket){_bucket=bucket;returnthis;}protectedoverrideasyncTask<string?>GetAsync(stringkey,ParameterProviderConfiguration?config){if(string.IsNullOrEmpty(key))thrownewArgumentNullException(nameof(key));if(string.IsNullOrEmpty(_bucket))thrownewArgumentException("A bucket must be specified, using withBucket() method");varrequest=newGetObjectRequest{Key=key,BucketName=_bucket};usingvarresponse=await_client.GetObjectAsync(request);awaitusingvarresponseStream=response.ResponseStream;usingvarreader=newStreamReader(responseStream);returnawaitreader.ReadToEndAsync();}protectedoverrideasyncTask<IDictionary<string,string?>>GetMultipleAsync(stringpath,ParameterProviderConfiguration?config){if(string.IsNullOrEmpty(path))thrownewArgumentNullException(nameof(path));if(string.IsNullOrEmpty(_bucket))thrownewArgumentException("A bucket must be specified, using withBucket() method");varrequest=newListObjectsV2Request{Prefix=path,BucketName=_bucket};varresponse=await_client.ListObjectsV2Async(request);varresult=newDictionary<string,string?>();foreach(vars3Objectinresponse.S3Objects){varvalue=awaitGetAsync(s3Object.Key);result.Add(s3Object.Key,value);}returnresult;}}