From b5c0286a714245d28ed75250e6f472ea11203f02 Mon Sep 17 00:00:00 2001 From: Jonas Ha Date: Thu, 4 Dec 2025 08:39:23 -0500 Subject: [PATCH 1/8] docs(configuration): clarify environment variable handling in `CreateBuilder()` - Updated configuration documentation to specify the exclusion of `ASPNETCORE_` prefixed variables. - Added warning about manually handling `ASPNETCORE_ENVIRONMENT` when using `CreateBuilder()`. --- docs/guides/configuration.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/guides/configuration.md b/docs/guides/configuration.md index b7975ce8..b0d7a386 100644 --- a/docs/guides/configuration.md +++ b/docs/guides/configuration.md @@ -10,10 +10,13 @@ shutdown windows, serializer choices, etc.). This guide covers both layers. `LambdaApplication.CreateBuilder()` wires up the standard .NET defaults: 1. `appsettings.json` (optional) in the application root. -2. `appsettings.{Environment}.json` (optional) based on `DOTNET_ENVIRONMENT`/`ASPNETCORE_ENVIRONMENT`. +2. `appsettings.{Environment}.json` (optional) based on `DOTNET_ENVIRONMENT` environment variable. 3. User secrets (Development only). 4. Environment variables (`AWS_`, `DOTNET_`, and general variables). +!!! warning "`ASPNETCORE_` Prefixed Environment Variable" + Enviroment variables with the `ASPNETCORE_` prefix are not automatically loaded by `CreateBuilder()` and must be added manually. As such, the enviroment cannot be set using the `ASPNETCORE_ENVIRONMENT` environment variable. + The builder also binds the `AwsLambdaHost` section (from JSON or environment variables) into `LambdaHostOptions` so framework settings can live next to your app configuration. From 0e5f81d6e4c6fccb8535dd58e7ab4efa92e1e8ad Mon Sep 17 00:00:00 2001 From: Jonas Ha Date: Thu, 4 Dec 2025 08:39:32 -0500 Subject: [PATCH 2/8] feat(local-dev): add `run-docs` task to run MKDocs server locally - Introduced a new `run-docs` task in LocalDevTasks.yml for running MKDocs with live reload. - Ensured compatibility with the existing developer workflow. --- tasks/LocalDevTasks.yml | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/tasks/LocalDevTasks.yml b/tasks/LocalDevTasks.yml index 9bcbf9b3..b6b5d94a 100644 --- a/tasks/LocalDevTasks.yml +++ b/tasks/LocalDevTasks.yml @@ -47,4 +47,11 @@ tasks: desc: Start the AWS Lambda test tool silent: true cmds: - - dotnet lambda-test-tool start --lambda-emulator-port 5050 \ No newline at end of file + - dotnet lambda-test-tool start --lambda-emulator-port 5050 + + run-docs: + desc: Run MKDocs server locally + silent: true + cmds: + - uv sync + - uv run mkdocs serve --livereload \ No newline at end of file From 42149b87075d6e3907d3deae8649a89f765f2dc4 Mon Sep 17 00:00:00 2001 From: Jonas Ha Date: Thu, 4 Dec 2025 08:40:39 -0500 Subject: [PATCH 3/8] refactor(environment): replace `ASPNETCORE_ENVIRONMENT` with `DOTNET_ENVIRONMENT` - Updated `launchSettings.json` across multiple examples to use `DOTNET_ENVIRONMENT` instead. - Ensures consistency with modern .NET environment variable standards. --- .../Properties/launchSettings.json | 2 +- .../Properties/launchSettings.json | 2 +- .../Properties/launchSettings.json | 2 +- .../Properties/launchSettings.json | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/examples/AwsLambda.Host.Example.Events/Properties/launchSettings.json b/examples/AwsLambda.Host.Example.Events/Properties/launchSettings.json index 6b37dc1a..a348821c 100644 --- a/examples/AwsLambda.Host.Example.Events/Properties/launchSettings.json +++ b/examples/AwsLambda.Host.Example.Events/Properties/launchSettings.json @@ -5,7 +5,7 @@ "commandName": "Project", "environmentVariables": { "AWS_LAMBDA_RUNTIME_API": "localhost:5050", - "ASPNETCORE_ENVIRONMENT": "Development", + "DOTNET_ENVIRONMENT": "Development", "AWS_LAMBDA_LOG_FORMAT": "JSON", "AWS_LAMBDA_LOG_LEVEL": "DEBUG" } diff --git a/examples/AwsLambda.Host.Example.HelloWorldAot/Properties/launchSettings.json b/examples/AwsLambda.Host.Example.HelloWorldAot/Properties/launchSettings.json index 6b37dc1a..a348821c 100644 --- a/examples/AwsLambda.Host.Example.HelloWorldAot/Properties/launchSettings.json +++ b/examples/AwsLambda.Host.Example.HelloWorldAot/Properties/launchSettings.json @@ -5,7 +5,7 @@ "commandName": "Project", "environmentVariables": { "AWS_LAMBDA_RUNTIME_API": "localhost:5050", - "ASPNETCORE_ENVIRONMENT": "Development", + "DOTNET_ENVIRONMENT": "Development", "AWS_LAMBDA_LOG_FORMAT": "JSON", "AWS_LAMBDA_LOG_LEVEL": "DEBUG" } diff --git a/examples/AwsLambda.Host.Example.Lifecycle/Properties/launchSettings.json b/examples/AwsLambda.Host.Example.Lifecycle/Properties/launchSettings.json index 6b37dc1a..a348821c 100644 --- a/examples/AwsLambda.Host.Example.Lifecycle/Properties/launchSettings.json +++ b/examples/AwsLambda.Host.Example.Lifecycle/Properties/launchSettings.json @@ -5,7 +5,7 @@ "commandName": "Project", "environmentVariables": { "AWS_LAMBDA_RUNTIME_API": "localhost:5050", - "ASPNETCORE_ENVIRONMENT": "Development", + "DOTNET_ENVIRONMENT": "Development", "AWS_LAMBDA_LOG_FORMAT": "JSON", "AWS_LAMBDA_LOG_LEVEL": "DEBUG" } diff --git a/examples/AwsLambda.Host.Example.OpenTelemetry/Properties/launchSettings.json b/examples/AwsLambda.Host.Example.OpenTelemetry/Properties/launchSettings.json index 075e2dbb..5353021c 100644 --- a/examples/AwsLambda.Host.Example.OpenTelemetry/Properties/launchSettings.json +++ b/examples/AwsLambda.Host.Example.OpenTelemetry/Properties/launchSettings.json @@ -5,7 +5,7 @@ "commandName": "Project", "environmentVariables": { "AWS_LAMBDA_RUNTIME_API": "localhost:5050", - "ASPNETCORE_ENVIRONMENT": "Development", + "DOTNET_ENVIRONMENT": "Development", "AWS_LAMBDA_LOG_FORMAT": "JSON", "AWS_LAMBDA_LOG_LEVEL": "DEBUG" } From 4c3862d8ad40ed748e38f43e3519453014690170 Mon Sep 17 00:00:00 2001 From: Jonas Ha Date: Thu, 4 Dec 2025 08:43:50 -0500 Subject: [PATCH 4/8] feat(docs): enable permalinks for section headings in TOC - Added `permalink` and `permalink_title` configuration to `toc` extension in `mkdocs.yml`. - Allows users to easily reference specific sections with anchor links. --- mkdocs.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/mkdocs.yml b/mkdocs.yml index ccc88842..d8d76c79 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -86,6 +86,9 @@ markdown_extensions: - def_list - pymdownx.tasklist: custom_checkbox: true + - toc: + permalink: true + permalink_title: Anchor link to this section for reference watch: - ./docs/ From 863b6fe42be2ad83b5388025d5a6b82daae126ff Mon Sep 17 00:00:00 2001 From: Jonas Ha Date: Thu, 4 Dec 2025 08:51:11 -0500 Subject: [PATCH 5/8] docs(configuration): add examples for handling `ASPNETCORE_` prefixed environment variables - Included code snippets for loading `ASPNETCORE_` prefixed environment variables after `CreateBuilder()`. - Added guidance for using `ASPNETCORE_` variables when creating `LambdaApplicationBuilder`. --- docs/guides/configuration.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/guides/configuration.md b/docs/guides/configuration.md index b0d7a386..782268f2 100644 --- a/docs/guides/configuration.md +++ b/docs/guides/configuration.md @@ -17,6 +17,24 @@ shutdown windows, serializer choices, etc.). This guide covers both layers. !!! warning "`ASPNETCORE_` Prefixed Environment Variable" Enviroment variables with the `ASPNETCORE_` prefix are not automatically loaded by `CreateBuilder()` and must be added manually. As such, the enviroment cannot be set using the `ASPNETCORE_ENVIRONMENT` environment variable. + To load environment variables prefixed with `ASPNETCORE_` after calling `CreateBuilder()`, you can add the following code: + + ```csharp + var builder = LambdaApplication.CreateBuilder(); + builder.Configuration.AddEnvironmentVariables("ASPNETCORE_"); + ``` + + If you need to use `ASPNETCORE_` prefixed environment variables when creating the `LambdaApplicationBuilder`, you can add the following code: + + ```csharp + var configuration = new ConfigurationManager(); + configuration.AddEnvironmentVariables("ASPNETCORE_"); + + var builder = LambdaApplication.CreateBuilder( + new LambdaApplicationOptions { Configuration = configuration } + ); + ``` + The builder also binds the `AwsLambdaHost` section (from JSON or environment variables) into `LambdaHostOptions` so framework settings can live next to your app configuration. From a7b022d58612451f71597ef90877591b31619d58 Mon Sep 17 00:00:00 2001 From: Jonas Ha Date: Thu, 4 Dec 2025 09:19:37 -0500 Subject: [PATCH 6/8] ci(validate-pr-title): add `docs` to the allowed PR title scopes - Updated `validate-pr-title.yaml` to include `docs` in the list of valid PR title scopes. - Ensures consistency with recent documentation-related contributions. --- .github/workflows/validate-pr-title.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/validate-pr-title.yaml b/.github/workflows/validate-pr-title.yaml index f9394fcc..38fae0aa 100644 --- a/.github/workflows/validate-pr-title.yaml +++ b/.github/workflows/validate-pr-title.yaml @@ -44,6 +44,7 @@ jobs: ci github core + docs requireScope: false subjectPattern: ^[a-z].* subjectPatternError: Subject must start with lowercase letter From 0973f914a8d88fddb41868793df4fab0ce001c88 Mon Sep 17 00:00:00 2001 From: Jonas Ha Date: Thu, 4 Dec 2025 09:20:08 -0500 Subject: [PATCH 7/8] docs(configuration): update configuration provider order in `CreateBuilder()` docs - Clarified the order in which configuration providers are added when defaults are enabled. - Added details about disabling defaults with `LambdaApplicationOptions.DisableDefaults`. - Expanded provider list to include all relevant environment variable categories. --- docs/guides/configuration.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/guides/configuration.md b/docs/guides/configuration.md index 782268f2..fc5f82e9 100644 --- a/docs/guides/configuration.md +++ b/docs/guides/configuration.md @@ -7,12 +7,16 @@ shutdown windows, serializer choices, etc.). This guide covers both layers. ## How Configuration Is Built -`LambdaApplication.CreateBuilder()` wires up the standard .NET defaults: - -1. `appsettings.json` (optional) in the application root. -2. `appsettings.{Environment}.json` (optional) based on `DOTNET_ENVIRONMENT` environment variable. -3. User secrets (Development only). -4. Environment variables (`AWS_`, `DOTNET_`, and general variables). +`LambdaApplication.CreateBuilder()` wires up the standard .NET defaults unless you pass +`new LambdaApplicationOptions { DisableDefaults = true }`. When defaults are enabled, configuration +providers are added in the following order (later entries override earlier ones): + +1. Environment variables prefixed with `AWS_` (Lambda metadata such as `AWS_LAMBDA_FUNCTION_NAME`). +2. Environment variables prefixed with `DOTNET_` (host defaults such as `DOTNET_ENVIRONMENT` or `DOTNET_CONTENTROOT`). +3. `appsettings.json` (optional) in the application root. +4. `appsettings.{Environment}.json` (optional) based on `DOTNET_ENVIRONMENT`. +5. User secrets (Development only, resolved from the entry assembly). +6. All remaining environment variables (no prefix filter). !!! warning "`ASPNETCORE_` Prefixed Environment Variable" Enviroment variables with the `ASPNETCORE_` prefix are not automatically loaded by `CreateBuilder()` and must be added manually. As such, the enviroment cannot be set using the `ASPNETCORE_ENVIRONMENT` environment variable. From 32175167a6fb63ac5cb73ed6ebe561b352952a59 Mon Sep 17 00:00:00 2001 From: Jonas Ha Date: Thu, 4 Dec 2025 09:22:10 -0500 Subject: [PATCH 8/8] docs(index): add front matter to index.md - Added YAML front matter to `index.md` to define metadata like `title`. - Prepares `index.md` for compatibility with static site generators like MkDocs. --- docs/index.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/index.md b/docs/index.md index 1b1a0a15..965af824 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,7 @@ +--- +title: "" +--- + # Build AWS Lambda Functions with .NET Hosting Patterns [![Main Build](https://github.com/j-d-ha/aws-lambda-host/actions/workflows/main-build.yaml/badge.svg)](https://github.com/j-d-ha/aws-lambda-host/actions/workflows/main-build.yaml)