Skip to content

Commit f6a90e5

Browse files
hjgracahjgraca
authored
docs(parameters): extract inline code examples into snippet files (#1197)
1 parent 63cec90 commit f6a90e5

9 files changed

Lines changed: 680 additions & 544 deletions

File tree

‎docs/snippets/parameters/AppConfigProvider.cs‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
// This file is referenced by docs/utilities/parameters.md
2+
// via pymdownx.snippets (mkdocs).
3+
4+
namespace AWS.Lambda.Powertools.Docs.Snippets.Parameters;
5+
6+
// --8<-- [start:app_config_provider]
7+
using AWS.Lambda.Powertools.Parameters;
8+
using AWS.Lambda.Powertools.Parameters.AppConfig;
9+
10+
public class Function
11+
{
12+
public async Task<APIGatewayProxyResponse> FunctionHandler
13+
(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
14+
{
15+
// Get AppConfig Provider instance
16+
IAppConfigProvider appConfigProvider = ParametersManager.AppConfigProvider
17+
.DefaultApplication("MyApplicationId")
18+
.DefaultEnvironment("MyEnvironmentId")
19+
.DefaultConfigProfile("MyConfigProfileId");
20+
21+
// Retrieve a single configuration, latest version
22+
IDictionary<string, string?> value = await appConfigProvider
23+
.GetAsync()
24+
.ConfigureAwait(false);
25+
}
26+
}
27+
// --8<-- [end:app_config_provider]
28+
29+
// --8<-- [start:app_config_provider_explicit_region]
30+
using AWS.Lambda.Powertools.Parameters;
31+
using AWS.Lambda.Powertools.Parameters.AppConfig;
32+
33+
public class Function
34+
{
35+
public async Task<APIGatewayProxyResponse> FunctionHandler
36+
(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
37+
{
38+
// Get AppConfig Provider instance
39+
IAppConfigProvider appConfigProvider = ParametersManager.AppConfigProvider
40+
.ConfigureClient(RegionEndpoint.EUCentral1)
41+
.DefaultApplication("MyApplicationId")
42+
.DefaultEnvironment("MyEnvironmentId")
43+
.DefaultConfigProfile("MyConfigProfileId");
44+
45+
// Retrieve a single configuration, latest version
46+
IDictionary<string, string?> value = await appConfigProvider
47+
.GetAsync()
48+
.ConfigureAwait(false);
49+
}
50+
}
51+
// --8<-- [end:app_config_provider_explicit_region]
52+
53+
// --8<-- [start:app_config_feature_flags]
54+
using AWS.Lambda.Powertools.Parameters;
55+
using AWS.Lambda.Powertools.Parameters.AppConfig;
56+
57+
public class Function
58+
{
59+
public async Task<APIGatewayProxyResponse> FunctionHandler
60+
(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
61+
{
62+
// Get AppConfig Provider instance
63+
IAppConfigProvider appConfigProvider = ParametersManager.AppConfigProvider
64+
.DefaultApplication("MyApplicationId")
65+
.DefaultEnvironment("MyEnvironmentId")
66+
.DefaultConfigProfile("MyConfigProfileId");
67+
68+
// Check if feature flag is enabled
69+
var isFeatureFlagEnabled = await appConfigProvider
70+
.IsFeatureFlagEnabledAsync("MyFeatureFlag")
71+
.ConfigureAwait(false);
72+
73+
if (isFeatureFlagEnabled)
74+
{
75+
// Retrieve an attribute value of the feature flag
76+
var strAttValue = await appConfigProvider
77+
.GetFeatureFlagAttributeValueAsync<string>("MyFeatureFlag", "StringAttribute")
78+
.ConfigureAwait(false);
79+
80+
// Retrieve another attribute value of the feature flag
81+
var numberAttValue = await appConfigProvider
82+
.GetFeatureFlagAttributeValueAsync<int>("MyFeatureFlag", "NumberAttribute")
83+
.ConfigureAwait(false);
84+
}
85+
}
86+
}
87+
// --8<-- [end:app_config_feature_flags]

‎docs/snippets/parameters/Caching.cs‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
// This file is referenced by docs/utilities/parameters.md
2+
// via pymdownx.snippets (mkdocs).
3+
4+
namespace AWS.Lambda.Powertools.Docs.Snippets.Parameters;
5+
6+
// --8<-- [start:default_max_age]
7+
using AWS.Lambda.Powertools.Parameters;
8+
using AWS.Lambda.Powertools.Parameters.SimpleSystemsManagement;
9+
10+
public class Function
11+
{
12+
public async Task<APIGatewayProxyResponse> FunctionHandler
13+
(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
14+
{
15+
// Get SSM Provider instance
16+
ISsmProvider ssmProvider = ParametersManager.SsmProvider
17+
.DefaultMaxAge(TimeSpan.FromSeconds(10));
18+
19+
// Retrieve a single parameter
20+
string? value = await ssmProvider
21+
.GetAsync("/my/parameter")
22+
.ConfigureAwait(false);
23+
}
24+
}
25+
// --8<-- [end:default_max_age]
26+
27+
// --8<-- [start:max_age_per_parameter]
28+
using AWS.Lambda.Powertools.Parameters;
29+
using AWS.Lambda.Powertools.Parameters.SimpleSystemsManagement;
30+
31+
public class Function
32+
{
33+
public async Task<APIGatewayProxyResponse> FunctionHandler
34+
(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
35+
{
36+
// Get SSM Provider instance
37+
ISsmProvider ssmProvider = ParametersManager.SsmProvider;
38+
39+
// Retrieve a single parameter
40+
string? value = await ssmProvider
41+
.WithMaxAge(TimeSpan.FromSeconds(10))
42+
.GetAsync("/my/parameter")
43+
.ConfigureAwait(false);
44+
}
45+
}
46+
// --8<-- [end:max_age_per_parameter]
47+
48+
// --8<-- [start:force_fetch]
49+
using AWS.Lambda.Powertools.Parameters;
50+
using AWS.Lambda.Powertools.Parameters.SimpleSystemsManagement;
51+
52+
public class Function
53+
{
54+
public async Task<APIGatewayProxyResponse> FunctionHandler
55+
(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
56+
{
57+
// Get SSM Provider instance
58+
ISsmProvider ssmProvider = ParametersManager.SsmProvider;
59+
60+
// Retrieve a single parameter
61+
string? value = await ssmProvider
62+
.ForceFetch()
63+
.GetAsync("/my/parameter")
64+
.ConfigureAwait(false);
65+
}
66+
}
67+
// --8<-- [end:force_fetch]

‎docs/snippets/parameters/CustomProvider.cs‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
// This file is referenced by docs/utilities/parameters.md
2+
// via pymdownx.snippets (mkdocs).
3+
4+
namespace AWS.Lambda.Powertools.Docs.Snippets.Parameters;
5+
6+
// --8<-- [start:s3_provider]
7+
public class S3Provider : ParameterProvider
8+
{
9+
10+
private string _bucket;
11+
private readonly IAmazonS3 _client;
12+
13+
public S3Provider()
14+
{
15+
_client = new AmazonS3Client();
16+
}
17+
18+
public S3Provider(IAmazonS3 client)
19+
{
20+
_client = client;
21+
}
22+
23+
public S3Provider WithBucket(string bucket)
24+
{
25+
_bucket = bucket;
26+
return this;
27+
}
28+
29+
protected override async Task<string?> GetAsync(string key, ParameterProviderConfiguration? config)
30+
{
31+
if (string.IsNullOrEmpty(key))
32+
throw new ArgumentNullException(nameof(key));
33+
34+
if (string.IsNullOrEmpty(_bucket))
35+
throw new ArgumentException("A bucket must be specified, using withBucket() method");
36+
37+
var request = new GetObjectRequest
38+
{
39+
Key = key,
40+
BucketName = _bucket
41+
};
42+
43+
using var response = await _client.GetObjectAsync(request);
44+
await using var responseStream = response.ResponseStream;
45+
using var reader = new StreamReader(responseStream);
46+
return await reader.ReadToEndAsync();
47+
}
48+
49+
protected override async Task<IDictionary<string, string?>> GetMultipleAsync(string path, ParameterProviderConfiguration? config)
50+
{
51+
if (string.IsNullOrEmpty(path))
52+
throw new ArgumentNullException(nameof(path));
53+
54+
if (string.IsNullOrEmpty(_bucket))
55+
throw new ArgumentException("A bucket must be specified, using withBucket() method");
56+
57+
var request = new ListObjectsV2Request
58+
{
59+
Prefix = path,
60+
BucketName = _bucket
61+
};
62+
var response = await _client.ListObjectsV2Async(request);
63+
64+
var result = new Dictionary<string, string?>();
65+
foreach (var s3Object in response.S3Objects)
66+
{
67+
var value = await GetAsync(s3Object.Key);
68+
result.Add(s3Object.Key, value);
69+
}
70+
71+
return result;
72+
}
73+
}
74+
// --8<-- [end:s3_provider]
75+
76+
// --8<-- [start:using_custom_provider]
77+
var provider = new S3Provider();
78+
79+
var value = await provider
80+
.WithBucket("myBucket")
81+
.GetAsync("myKey")
82+
.ConfigureAwait(false);
83+
// --8<-- [end:using_custom_provider]

‎docs/snippets/parameters/CustomTransformer.cs‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
// This file is referenced by docs/utilities/parameters.md
2+
// via pymdownx.snippets (mkdocs).
3+
4+
namespace AWS.Lambda.Powertools.Docs.Snippets.Parameters;
5+
6+
// --8<-- [start:xml_transformer]
7+
public class XmlTransformer : ITransformer
8+
{
9+
public T? Transform<T>(string value)
10+
{
11+
if (string.IsNullOrEmpty(value))
12+
return default;
13+
14+
var serializer = new XmlSerializer(typeof(T));
15+
using var reader = new StringReader(value);
16+
return (T?)serializer.Deserialize(reader);
17+
}
18+
}
19+
// --8<-- [end:xml_transformer]
20+
21+
// --8<-- [start:using_xml_transformer]
22+
var value = await ssmProvider
23+
.WithTransformation(new XmlTransformer())
24+
.GetAsync<MyObj>("/my/parameter/xml")
25+
.ConfigureAwait(false);
26+
// --8<-- [end:using_xml_transformer]
27+
28+
// --8<-- [start:adding_xml_transformer]
29+
// Get SSM Provider instance
30+
ISsmProvider ssmProvider = ParametersManager.SsmProvider
31+
.AddTransformer("XML", new XmlTransformer());
32+
33+
// Retrieve a single parameter
34+
var value = await ssmProvider
35+
.WithTransformation("XML")
36+
.GetAsync<MyObj>("/my/parameter/xml")
37+
.ConfigureAwait(false);
38+
// --8<-- [end:adding_xml_transformer]
39+
40+
// --8<-- [start:fluent_api]
41+
ssmProvider
42+
.DefaultMaxAge(TimeSpan.FromSeconds(10)) // will set 10 seconds as the default cache TTL
43+
.WithMaxAge(TimeSpan.FromMinutes(1)) // will set the cache TTL for this value at 1 minute
44+
.WithTransformation(Transformation.Json) // Will use JSON transfomer to deserializes JSON to an object
45+
.WithDecryption() // enable decryption of the parameter value
46+
.Get<MyObj>("/my/param"); // finally get the value
47+
// --8<-- [end:fluent_api]

‎docs/snippets/parameters/DynamoDbProvider.cs‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
// This file is referenced by docs/utilities/parameters.md
2+
// via pymdownx.snippets (mkdocs).
3+
4+
namespace AWS.Lambda.Powertools.Docs.Snippets.Parameters;
5+
6+
// --8<-- [start:dynamodb_provider_single]
7+
using AWS.Lambda.Powertools.Parameters;
8+
using AWS.Lambda.Powertools.Parameters.DynamoDB;
9+
10+
public class Function
11+
{
12+
public async Task<APIGatewayProxyResponse> FunctionHandler
13+
(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
14+
{
15+
// Get DynamoDB Provider instance
16+
IDynamoDBProvider dynamoDbProvider = ParametersManager.DynamoDBProvider
17+
.UseTable("my-table");
18+
19+
// Retrieve a single parameter
20+
string? value = await dynamoDbProvider
21+
.GetAsync("my-param")
22+
.ConfigureAwait(false);
23+
}
24+
}
25+
// --8<-- [end:dynamodb_provider_single]
26+
27+
// --8<-- [start:dynamodb_provider_multiple]
28+
using AWS.Lambda.Powertools.Parameters;
29+
using AWS.Lambda.Powertools.Parameters.DynamoDB;
30+
31+
public class Function
32+
{
33+
public async Task<APIGatewayProxyResponse> FunctionHandler
34+
(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
35+
{
36+
// Get DynamoDB Provider instance
37+
IDynamoDBProvider dynamoDbProvider = ParametersManager.DynamoDBProvider
38+
.UseTable("my-table");
39+
40+
// Retrieve a single parameter
41+
IDictionary<string, string?> value = await dynamoDbProvider
42+
.GetMultipleAsync("my-hash-key")
43+
.ConfigureAwait(false);
44+
}
45+
}
46+
// --8<-- [end:dynamodb_provider_multiple]
47+
48+
// --8<-- [start:dynamodb_provider_customizing]
49+
using AWS.Lambda.Powertools.Parameters;
50+
using AWS.Lambda.Powertools.Parameters.DynamoDB;
51+
52+
public class Function
53+
{
54+
public async Task<APIGatewayProxyResponse> FunctionHandler
55+
(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
56+
{
57+
// Get DynamoDB Provider instance
58+
IDynamoDBProvider dynamoDbProvider = ParametersManager.DynamoDBProvider
59+
.UseTable
60+
(
61+
tableName: "TableName", // DynamoDB table name, Required.
62+
primaryKeyAttribute: "id", // Partition Key attribute name, optional, default is 'id'
63+
sortKeyAttribute: "sk", // Sort Key attribute name, optional, default is 'sk'
64+
valueAttribute: "value" // Value attribute name, optional, default is 'value'
65+
);
66+
}
67+
}
68+
// --8<-- [end:dynamodb_provider_customizing]

0 commit comments

Comments
 (0)