In the fast-paced world of software development, building robust, scalable, and maintainable full-stack applications often feels like navigating a labyrinth. From backend APIs and databases to frontend frameworks and deployment pipelines, the sheer complexity can be daunting. But what if there was a way to significantly streamline this process, making distributed application development not just manageable, but genuinely enjoyable?

Enter ASP.NET Core and the exciting innovation that is .NET Aspire. This powerful combination is rapidly changing how we approach full-stack development, especially for us .NET and C# enthusiasts. Recently, I came across an excellent guide on building a full-stack React app with an ASP.NET Core Web API and Aspire, and it really solidified my belief in the direction Microsoft is taking with our ecosystem. It's time to dive into why this matters and how you can leverage these tools to elevate your development workflow.

The Power Duo: ASP.NET Core and .NET Aspire

The core of modern web development in .NET has been ASP.NET Core for years a high-performance, cross-platform framework for building cloud-based, modern internet-connected applications. It's flexible, fast, and constantly evolving. However, even with ASP.NET Core's strengths, orchestrating multiple services, databases, and frontend applications in a local development environment, let alone for deployment, still presented significant challenges.

This is precisely where .NET Aspire steps in. .NET Aspire is an opinionated, cloud-native stack for building observable, production-ready distributed applications. Think of it as your intelligent orchestrator and development helper for complex application topologies. It takes the pain out of managing disparate services, database connections, and frontend integration during local development, providing a cohesive and observable experience from day one. The recent focus on integrating Aspire seamlessly with front-end technologies like React, as highlighted in the community's recent step-by-step guides, is a game-changer. It means we can now build interconnected systems with an unmatched level of local development ease.

Why This Matters for .NET/C# Developers

For seasoned .NET and C# developers, Aspire isn't just another library; it's a paradigm shift for distributed application development. Here’s why it’s a big deal:

• Simplified Local Development: Gone are the days of wrestling with Docker Compose files or manually starting multiple services. Aspire's AppHost project orchestrates everything. Spin up your backend API, database, and frontend with a single command, and they all "just work" together. This drastically reduces setup time and cognitive load.

• Enhanced Observability Out-of-the-Box: Aspire provides a brilliant interactive dashboard that offers real-time insights into your application's health, logs, traces, and metrics. This centralized view for all your distributed components (ASP.NET Core APIs, databases, message queues, and even your React app!) is invaluable for debugging and understanding system behavior, especially when things go awry.

• Seamless Frontend Integration: Integrating a React, Angular, or Vue.js frontend with your ASP.NET Core backend can often involve tricky proxy configurations and environment variable management. Aspire simplifies this by providing dedicated hosting integrations (like builder.AddViteApp for React/Vite), allowing your frontend to discover and communicate with your backend services automatically.

• Production-Ready Foundations: Aspire isn't just for local dev. Its design philosophy extends to deployment, providing patterns and integrations that make your distributed applications easier to deploy to cloud environments like Azure Container Apps. This consistency from development to production is a huge win for reliability and developer confidence.

• Accelerated Development Cycle: By abstracting away much of the boilerplate and configuration, Aspire allows you to focus on writing business logic. This increased velocity means features get built faster, and developers spend less time on infrastructure plumbing.

Practical Application: Building a Todo App with Aspire, ASP.NET Core, and React

Let's illustrate with a common scenario: building a simple Todo application. Traditionally, this might involve setting up an ASP.NET Core Web API, configuring a database (say, SQLite), and then setting up a React project that knows how to talk to that API. Each piece has its own setup, and getting them to communicate during local development can be fiddly.

With .NET Aspire, the workflow becomes remarkably smooth.

1. Start with Aspire: You begin by creating an Aspire Starter App. This gives you an AppHost project, which acts as the control plane for your distributed application.

dotnet new aspire-starter -n MyTodoApp
cd MyTodoApp

2. ASP.NET Core Web API: You'd then add your ASP.NET Core Web API project. What's neat here is how effortlessly Aspire integrates with Entity Framework Core and a database like SQLite. Instead of manually configuring connection strings everywhere, Aspire uses references:

// In MyTodoApp.AppHost/Program.cs
var db = builder.AddSqlite("tododb").WithSqliteWeb(); // Aspire handles SQLite setup
var apiService = builder.AddProject<Projects.MyTodoApp_ApiService>("apiservice")
    .WithReference(db) // API service automatically gets the database connection
    .WithHttpHealthCheck("/health");

And in your API's Program.cs, you simply use builder.AddSqliteDbContext to hook up your DbContext:

// In MyTodoApp.ApiService/Program.cs
builder.AddSqliteDbContext<TodoDbContext>("tododb");

This removes the need for explicit connection strings in appsettings.json for local development, simplifying configuration significantly. You can even use dotnet scaffold to quickly generate API endpoints for your models, further accelerating backend development.

3. React Frontend Integration: This is where Aspire truly shines for full-stack developers. Adding a React app (using Vite, for instance) is integrated directly into your Aspire orchestration:

npm create vite@latest todo-frontend -- --template react
aspire add nodejs // Adds Aspire.Hosting.NodeJs to AppHost
aspire add ct-extensions // Adds CommunityToolkit.Aspire.Hosting.NodeJS.Extensions for Vite support

Then, in your AppHost.cs, you tell Aspire about your frontend:

// In MyTodoApp.AppHost/Program.cs
builder.AddViteApp(name: "todo-frontend", workingDirectory: "../todo-frontend")
    .WithReference(apiService) // Frontend knows about the API service
    .WaitFor(apiService)
    .WithNpmPackageInstallation();

Crucially, vite.config.js in your React project can leverage environment variables injected by Aspire to proxy API requests, meaning your React app automatically knows where its backend lives without hardcoding URLs:

// In todo-frontend/vite.config.js
import { defineConfig, loadEnv } from 'vite'
// ...
export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '');
  return {
    // ...
    server: {
      port: parseInt(env.VITE_PORT),
      proxy: {
        '/api': {
          target: process.env.services__apiservice__https__0 || process.env.services__apiservice__http__0,
          changeOrigin: true,
          secure: false,
          rewrite: (path) => path.replace(/^\/api/, '')
        }
      }
    },
    // ...
  }
})

With this setup, running your AppHost project brings up the entire distributed application – the ASP.NET Core API, the SQLite database, and the React frontend – all interconnected and observable from the Aspire dashboard. This level of integrated development experience is a significant leap forward.

My Take: The Future of Full-Stack .NET Development

I've been building applications with .NET for years, and one consistent challenge in distributed systems has been the friction of local development setup and unified observability. Aspire directly addresses these pain points. It's not just about writing C# code; it's about making the entire development lifecycle smoother and more efficient.

For .NET developers who are either new to distributed systems or looking to modernize their existing architectures, Aspire provides a gentle on-ramp. It abstracts away much of the underlying complexity (like Docker networking or Kubernetes manifests for local dev) while still exposing the power of these technologies when you need it. This means you can focus on architecting your business logic and user experience, rather than spending hours debugging environment variables or service discovery issues.

Moreover, the built-in observability is a game-changer for debugging. Being able to see logs, traces, and metrics from every part of your application in a single, coherent dashboard provides a level of insight that was previously difficult to achieve without significant setup. It fosters a more proactive approach to problem-solving, allowing developers to quickly pinpoint issues across service boundaries.

This emphasis on developer experience, combined with the robustness of ASP.NET Core and the flexibility of modern front-end frameworks, truly positions the .NET ecosystem as a top-tier choice for building complex, scalable, full-stack applications. It's an exciting time to be a .NET developer!

Key Takeaways & Call to Action

The journey towards building complex, distributed applications doesn't have to be a struggle. With ASP.NET Core providing the solid foundation and .NET Aspire acting as your intelligent orchestrator, you gain:

• Simplified local development of distributed applications.

• Out-of-the-box observability via a centralized dashboard.

• Seamless integration with popular frontend frameworks like React.

• A clearer path from local development to cloud deployment.

I highly encourage you to explore .NET Aspire yourself. Dive into the documentation, try out the quickstarts, and experience the difference it makes in your daily workflow.

What are your thoughts on .NET Aspire? Have you already integrated it into your projects, or are you planning to? Share your experiences, tips, and any challenges you've faced in the comments below! Let's continue this conversation and build something amazing together.

In this post, we'll explain required parameters, how they differ from optional and nullable ones, and how to start using them immediately.

The Problem with Traditional Method Parameters

Traditionally, when a method expects non-null input, you’re forced to write boilerplate like this:

public void SendEmail(string? recipient)
{
    if (string.IsNullOrWhiteSpace(recipient))
        throw new ArgumentException("Recipient is required", nameof(recipient));

    // logic here
}

Even with nullable annotations, the compiler won't enforce non-null at compile time unless you're using nullable reference types strictly.

The New required Parameters

C# 13 now lets you mark parameters as required, just like you do with properties. The compiler ensures they’re supplied at the call site.

public void SendEmail(required string recipient)
{
    // No need for null checks unless you're doing deeper validation
    Console.WriteLine($"Sending to {recipient}");
}

If the caller omits the parameter or passes null, the compiler throws an error — before runtime.

Syntax

void MyMethod(required string name, int age)

• Only applies to reference types (currently).

• Cannot be combined with params or optional parameters.

• Works well with overloading and pattern-matching.

Real-World Use Case

Suppose you're building an API layer:

public IActionResult RegisterUser(required string username, required string email)
{
    // No need to write null/empty validation unless you're doing regex/email format checks
    _logger.LogInformation($"User: {username}, Email: {email}");
    return Ok();
}

The controller is cleaner, and contract enforcement is built into the compiler.

Gotchas and Edge Cases

• Required is not yet compatible with value types (though they must be passed anyway).

• Default values are not allowed on required parameters.

• Refactoring existing methods to include required might break existing call sites.

• This is a preview feature, so you’ll need the latest .NET 10 SDK and enable preview features in your .csproj:

<LangVersion>preview</LangVersion>

Summary

Required parameters in C# 13 are a simple but powerful addition that promotes cleaner, more self-documenting code. By shifting enforcement to compile time, they reduce runtime bugs and eliminate redundant checks.

If you're already using required for object properties, this method-level enhancement will feel like a natural progression.

References

• C# 13 Language Proposal (GitHub)

• .NET 10 Preview Features

• Required Members in C#

In this post, we'll cover:

• What LocalStack is

• How to set it up

• Common use cases

• C#/.NET example with S3

• Edge cases and gotchas

What Is LocalStack?

LocalStack is an open-source tool that emulates a wide range of AWS services on your local machine. It runs in Docker and supports services like:

• S3, Lambda, API Gateway, DynamoDB, SQS, SNS, IAM, CloudWatch, and more.

With LocalStack, you can run your AWS infrastructure locally, making it easier to test without incurring costs or relying on cloud connectivity.

Setting Up LocalStack

Requirements

• Docker is installed and running

• Python & pip (for LocalStack CLI)

Installation

pip install localstack
localstack start

Or using Docker Compose (recommended):

# docker-compose.yml
version: '3.8'
services:
  localstack:
    image: localstack/localstack
    ports:
      - "4566:4566"  # Gateway to all services
      - "4571:4571"
    environment:
      - SERVICES=s3,sqs,lambda
      - DEBUG=1
      - DATA_DIR=/tmp/localstack/data
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock"
      - "./.localstack:/tmp/localstack"

Run:

docker-compose up

Use Case: Working with S3 in .NET

Install the AWS SDK:

dotnet add package AWSSDK.S3

S3 Client Setup in C

var s3Client = new AmazonS3Client(
    new BasicAWSCredentials("test", "test"),
    new AmazonS3Config
    {
        ServiceURL = "http://localhost:4566",
        ForcePathStyle = true
    });

Create a Bucket and Upload a File

await s3Client.PutBucketAsync("my-test-bucket");

await s3Client.PutObjectAsync(new PutObjectRequest
{
    BucketName = "my-test-bucket",
    Key = "hello.txt",
    ContentBody = "Hello from LocalStack"
});

Verify with:

aws --endpoint-url=http://localhost:4566 s3 ls s3://my-test-bucket

Edge Cases and Gotchas

• Credentials: Use dummy credentials like test/test — LocalStack doesn’t validate them.

• Service URL: Always set ServiceURL = "http://localhost:4566".

• ForcePathStyle: Required for S3 to avoid virtual host-style addressing.

• Persistence: Use DATA_DIR in Docker Compose to persist state across restarts.

• Feature Support: Not all AWS service features are supported (especially newer ones or deep integrations).

Summary

LocalStack is a powerful tool for local AWS development. It cuts costs, increases speed, and allows testing even offline. Whether you're building with Lambda, API Gateway, or S3, LocalStack can significantly improve your dev workflow.

References

• LocalStack Docs

• GitHub Repo

• AWS SDK for .NET

• Docker Compose

In this post, we’ll walk through how to set up a CI/CD pipeline using GitHub Actions to build, test, and deploy .NET AWS Lambda functions automatically.

Prerequisites

To follow along, you’ll need:

• A .NET Lambda project (for example, created with dotnet new lambda.EmptyFunction)

• An AWS account with IAM credentials

• AWS CLI installed locally (for initial setup)

• An S3 bucket to store deployment artifacts (optional)

• The AWS CLI and Amazon.Lambda.Tools installed:

dotnet tool install -g Amazon.Lambda.Tools

Project Structure

Let’s assume the following structure:

MyLambdaFunction/
├── src/
│   └── MyLambdaFunction/
├── tests/
│   └── MyLambdaFunction.Tests/
├── .github/
│   └── workflows/
│       └── deploy.yml

Step 1: Create a GitHub Actions Workflow

Create the file .github/workflows/deploy.yml:

name: CI/CD for .NET Lambda

on:
  push:
    branches:
      - main

jobs:
  build-test-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '8.x'

      - name: Restore dependencies
        run: dotnet restore

      - name: Build
        run: dotnet build --configuration Release --no-restore

      - name: Run tests
        run: dotnet test --no-build --verbosity normal

      - name: Get Lambda Role ARN from SSM
        id: ssm
        run: |
          ROLE_ARN=$(aws ssm get-parameter --name "/lambda/MyLambdaFunction/RoleArn" --query "Parameter.Value" --output text)
          echo "role_arn=$ROLE_ARN" >> $GITHUB_OUTPUT
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          AWS_REGION: us-east-1

      - name: Deploy to AWS Lambda
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          AWS_REGION: us-east-1
        run: |
          cd src/MyLambdaFunction
          dotnet lambda deploy-function MyLambdaFunction \
            --region $AWS_REGION \
            --function-role ${{ steps.ssm.outputs.role_arn }}

Step 2: Set Up AWS Credentials for GitHub Actions

To securely authenticate your GitHub Actions workflow with AWS, you need to create an IAM user and store its access keys as GitHub secrets.

Create an IAM User in AWS

1. Sign in to the AWS Console

2. Go to IAM > Users > Add users

3. Choose a username (e.g., github-actions-deploy)

4. Enable Programmatic access

5. Attach the AWSLambdaFullAccess policy or a custom policy with only necessary permissions

6. Save the Access Key ID and Secret Access Key

Add Secrets to GitHub

1. In your GitHub repo, go to Settings > Secrets and variables > Actions

2. Add the following secrets:

   • AWS_ACCESS_KEY_ID

   • AWS_SECRET_ACCESS_KEY

Step 3: Use SSM Parameters to Avoid Manual Setup

You can avoid hardcoding values like the Lambda role ARN in your workflow by storing them in AWS Systems Manager (SSM) Parameter Store.

Store Required Values in SSM

Run this command locally to store the role ARN:

aws ssm put-parameter --name "/lambda/MyLambdaFunction/RoleArn" \
  --type String \
  --value "arn:aws:iam::<account-id>:role/<lambda-execution-role>"

Your GitHub Actions workflow can then retrieve this value dynamically before deployment.

Step 4: Do You Still Need Manual Deployment?

Yes, unless you ensure everything required for the deployment is pre-configured. Here's why:

• The dotnet lambda deploy-function command creates the Lambda function if it doesn't exist, but requires details like the function role, memory size, etc.

• If any required input is missing or the IAM role is misconfigured, the deployment will fail.

• GitHub Actions is non-interactive, so any CLI prompts will break the pipeline.

When Manual First-Time Deployment is Needed

You should deploy manually the first time if:

• The Lambda function does not yet exist

• You haven't scripted or automated the full configuration

cd src/MyLambdaFunction
dotnet lambda deploy-function MyLambdaFunction

This confirms that the function, role, region, and permissions are all set up correctly.

When You Can Skip Manual Deployment

You can skip it if:

• The Lambda function and IAM role already exist

• You’ve stored the function role in SSM and reference it in your workflow

• You pass all required CLI arguments directly in the workflow

This approach makes your pipeline truly hands-off from the beginning.

Conclusion

With this setup:

• Every push to the main branch triggers your CI/CD pipeline

• The pipeline builds, tests, and deploys your Lambda function

• SSM parameters allow dynamic configuration without hardcoding

• Manual setup can be avoided if resources are pre-provisioned

This makes your Lambda deployments consistent, automated, and production-ready.

References

• AWS Lambda Tools for .NET CLI

• GitHub Actions Documentation

• AWS CLI Configuration

• AWS Systems Manager Parameter Store

• Deploying Lambda with dotnet CLI

What is .NET Aspire?

.NET Aspire is not a new framework, but an application model designed to simplify the development, orchestration, and observability of multi-service .NET applications. It provides tooling and conventions that make it easier to define, compose, and run cloud-native apps locally while remaining production-ready.

This model is especially relevant for developers working with:

• Microservices

• Background worker services

• APIs

• Blazor frontends

• Message-based systems

Getting Started: A Minimal Example

Here is a basic example of how you can define an Aspire app host and include a simple web project and a Redis container:

var builder = DistributedApplication.CreateBuilder(args);

var redis = builder.AddRedisContainer("cache");
builder.AddProject<Projects.WebApp>("webapp")
       .WithReference(redis);

builder.Build().Run();

This short snippet defines a web application and a Redis container. The .WithReference(redis) call tells Aspire to inject the correct connection string and configure discovery between the services automatically.

Key Advantages of .NET Aspire

Local-First, Cloud-Ready

.NET Aspire emphasizes a "local-first" development experience. You can run your entire application—including databases, background workers, and frontends—on your machine with minimal setup. Aspire ensures that the same structure can later be deployed to cloud environments like Kubernetes or Azure Container Apps.

Built-In Service Support

Out of the box, Aspire integrates with common services such as:

• Redis

• PostgreSQL

• Dapr

• YARP

• OpenTelemetry

These integrations come with sensible defaults, saving you from boilerplate configuration and custom orchestration code.

Simplified Configuration and Dependency Management

Aspire uses declarative configuration to define how services relate to each other. This includes service discovery, environment variables, connection strings, and more—all managed through a central app host. This makes it easier to scale from development to production without rewriting how services are wired together.

Observability by Default

Instrumentation and observability are built in. With native OpenTelemetry support, Aspire enables distributed tracing, metrics, and logs across services without needing to manually configure each component. Developers also get access to a dashboard that provides real-time insights into service health and relationships.

Developer Experience

.NET Aspire focuses on making the developer experience seamless:

• Fast local feedback loops

• Integrated dashboards for diagnostics

• Consistent tooling and project structure

• Better onboarding for new team members

When to Use .NET Aspire

.NET Aspire is a strong choice when:

• You are building or modernizing a distributed system

• Your app relies on multiple services that need to be wired and run together

• You need consistent observability and diagnostics from development to production

• You want to reduce infrastructure friction and boilerplate code

Conclusion

.NET Aspire is a welcome addition to the .NET ecosystem, offering practical tools and conventions for building modern cloud-native applications. It aligns well with developers who value clarity, scalability, and maintainability in distributed architectures.

If you're starting a new .NET project that spans multiple services or migrating an existing system to the cloud, Aspire is worth exploring.

Resources:

• Official announcement: https://devblogs.microsoft.com/dotnet/introducing-dotnet-aspire

• GitHub repo: https://github.com/dotnet/aspire

In this post, we’ll walk through how to authenticate .NET applications against an API Gateway endpoint secured by Cognito. This setup works great for web apps, desktop clients, and server-to-server communication.

Why Use Cognito with API Gateway?

Amazon Cognito is a user directory service that provides:

• Secure user sign-up and sign-in

• JWT token-based authentication

• Integration with identity providers like Google, Facebook, and Microsoft

• Federated access to AWS services

API Gateway can directly validate JWT tokens issued by Cognito using a User Pool Authorizer. This allows you to secure your APIs without writing custom authentication logic.

Step 1: Set Up Cognito

1. Create a User Pool

   • Go to the Cognito console.

   • Choose “Create user pool” and configure fields like username, email, and password policies.

2. Create an App Client

   • Disable the client secret (for public clients like desktop or mobile apps).

   • Enable the ALLOW_USER_PASSWORD_AUTH and ALLOW_REFRESH_TOKEN_AUTH flows if you want to authenticate with username/password directly.

3. (Optional) Hosted UI

   • Use Cognito's hosted UI if you want OAuth2-style login redirects.

Step 2: Create and Configure API Gateway

1. Create a REST API or HTTP API

   • In the API Gateway console, choose to create a new HTTP API.

   • Name it something like UserServiceAPI.

2. Define a Secure Endpoint

   • Add a new route: GET /profile

   • This endpoint will return user profile data and should only be accessible to authenticated users.

3. Add a Cognito Authorizer

   • Go to the Authorizers section.

   • Choose "Cognito" and select the user pool you created earlier.

   • Give the authorizer a name like CognitoUserPoolAuthorizer.

4. Secure the /profile Route

   • In the route settings, attach the Cognito authorizer to the /profile endpoint.

   • This ensures that any request to /profile must include a valid JWT token issued by your Cognito User Pool.

Step 3: Get a JWT Token from Cognito in .NET

You can authenticate a user and retrieve tokens via HTTP using Cognito’s /oauth2/token endpoint.

Here’s how to do that using HttpClient in a .NET app:

var httpClient = new HttpClient();

var parameters = new Dictionary<string, string>
{
    { "grant_type", "password" },
    { "client_id", "<your-app-client-id>" },
    { "username", "<user-email>" },
    { "password", "<user-password>" },
};

var content = new FormUrlEncodedContent(parameters);

var response = await httpClient.PostAsync("https://<your-domain>.auth.<region>.amazoncognito.com/oauth2/token", content);
var json = await response.Content.ReadAsStringAsync();

var tokenResponse = JsonSerializer.Deserialize<TokenResponse>(json);

public class TokenResponse
{
    public string Access_token { get; set; }
    public string Id_token { get; set; }
    public string Refresh_token { get; set; }
    public string Token_type { get; set; }
    public int Expires_in { get; set; }
}

Tip: You can also use MSAL.NET if you’re using the OAuth2 code flow with redirect URIs and Cognito’s hosted UI.

Step 4: Send Authenticated Requests to API Gateway

After obtaining the token from Cognito, use it to call the protected /profile endpoint:

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", tokenResponse.Id_token);

var response = await client.GetAsync("https://your-api-id.execute-api.us-east-1.amazonaws.com/prod/profile");

if (response.IsSuccessStatusCode)
{
    var result = await response.Content.ReadAsStringAsync();
    Console.WriteLine(result);
}
else
{
    Console.WriteLine($"Request failed: {response.StatusCode}");
}

Replace your-api-id with your actual API Gateway ID and region. This example assumes the endpoint is deployed under the prod stage.

Step 5: (Optional) Validate Tokens Manually

If you’re processing the token yourself (e.g., in a Lambda function), use System.IdentityModel.Tokens.Jwt to parse and validate the token:

var handler = new JwtSecurityTokenHandler();
var token = handler.ReadJwtToken(tokenResponse.Id_token);

foreach (var claim in token.Claims)
{
    Console.WriteLine($"{claim.Type}: {claim.Value}");
}

Make sure to validate:

• Signature (using the JWKS endpoint)

• Expiration (exp)

• Audience (aud)

• Issuer (iss)

Common Issues

• Missing Token: Ensure the Authorization header is set and the route is protected with the authorizer.

• Invalid Token: Check that you're using the correct Cognito user pool and app client.

• CORS Errors: If calling from a browser, configure CORS settings in API Gateway.

• Token Expired: Use the refresh token to obtain a new access token.

Conclusion

By combining Amazon Cognito and API Gateway, you can add strong authentication to your APIs without maintaining your own user system. .NET apps can easily acquire and use tokens to call these APIs securely. Whether you're building a mobile app, a web frontend, or a backend service, this setup is clean, scalable, and secure.

References

• Amazon Cognito User Pools

• API Gateway Cognito Authorizer

• Cognito OAuth2 Token Endpoint

• System.IdentityModel.Tokens.Jwt

In this post, we’ll walk through how to schedule a .NET Lambda function using CloudWatch and how to structure your code for maintainability.

Prerequisites

Before you begin, make sure you have the following:

• An AWS Account with permission to create Lambda functions and CloudWatch rules

• The .NET SDK is installed (preferably .NET 6 or later)

• The AWS CLI is installed and configured (aws configure)

• Amazon.Lambda.Tools installed via the .NET CLI:

    dotnet tool install -g Amazon.Lambda.Tools
  

• Basic familiarity with AWS Lambda and the .NET CLI

Step 1: Create the .NET Lambda Function

You can use the AWS-provided templates with the Amazon.Lambda.Templates package.

dotnet new lambda.EmptyFunction --name ScheduledTaskLambda
cd ScheduledTaskLambda

Edit the Function.cs file:

public class Function
{
    public async Task FunctionHandler(ILambdaContext context)
    {
        context.Logger.LogLine("Scheduled task triggered at: " + DateTime.UtcNow);

        // Your logic here
        await DoScheduledWork();
    }

    private Task DoScheduledWork()
    {
        // Simulate a task like cleanup, email reminder, or sync
        Console.WriteLine("Running scheduled task...");
        return Task.CompletedTask;
    }
}

Step 2: Deploy the Lambda Function

Deploy the Lambda:

dotnet lambda deploy-function ScheduledTaskLambda

You’ll be prompted for AWS credentials and region during the deployment.

Step 3: Schedule with CloudWatch Event Rule

You can use the AWS Console or the AWS CLI:

aws events put-rule \
  --schedule-expression "rate(5 minutes)" \
  --name MyScheduledLambdaRule

Add the Lambda target:

aws events put-targets \
  --rule MyScheduledLambdaRule \
  --targets "Id"="1","Arn"="arn:aws:lambda:<region>:<account-id>:function:ScheduledTaskLambda"

Grant CloudWatch permission to invoke the Lambda:

aws lambda add-permission \
  --function-name ScheduledTaskLambda \
  --statement-id MyScheduledEventPermission \
  --action 'lambda:InvokeFunction' \
  --principal events.amazonaws.com \
  --source-arn arn:aws:events:<region>:<account-id>:rule/MyScheduledLambdaRule

Using Cron Expressions

Instead of rate()You can use cron expressions:

--schedule-expression "cron(0 12 * * ? *)"

This triggers at 12:00 PM UTC every day. AWS cron format:

cron(Minutes Hours Day-of-month Month Day-of-week Year)

Real-World Example: Sending a Daily Email Report

Let’s say your system collects usage metrics or user activity throughout the day. Every morning at 8 AM UTC, you want to email a summary report to your team. You’ll:

• Query a database or analytics source

• Generate a report, either plain text or HTML

• Send the report using Amazon SES or another email provider

This is a great use case for a scheduled Lambda function.

Example Code

public class Function
{
    public async Task FunctionHandler(ILambdaContext context)
    {
        var report = await GenerateReport();
        await SendEmail(report);

        context.Logger.LogLine("Daily report sent at: " + DateTime.UtcNow);
    }

    private Task<string> GenerateReport()
    {
        // Query a DB or metrics API. Simulated output:
        return Task.FromResult("User signups: 42\nErrors: 3\nSales: $1280");
    }

    private Task SendEmail(string report)
    {
        // Integrate with Amazon SES, SendGrid, or another provider
        Console.WriteLine("Sending email with report:\n" + report);
        return Task.CompletedTask;
    }
}

This Lambda can be scheduled using the following cron expression:

bashCopy code--schedule-expression "cron(0 8 * * ? *)"

This means 8:00 AM UTC every day.

Logging and Monitoring

• View logs in CloudWatch Logs

• Add custom logging using context.Logger.LogLine(...)

• Use structured logging libraries like Serilog for better insights

Summary

With just a few commands and a bit of .NET code, you can schedule tasks using CloudWatch Events and AWS Lambda. This approach is scalable, cost-effective, and fully serverless.

Benefits Recap:

• No server maintenance

• Pay only for executions

• Integrated with the AWS ecosystem

• Ideal for recurring jobs like cleanup, reporting, data sync, and reminders

References

• AWS Lambda Developer Guide (.NET)

• Schedule expressions for rules - EventBridge

• Amazon.Lambda.Tools GitHub

• AWS Schedule Expressions

In this post, you'll learn how to write a .NET Lambda function that processes messages from an SQS queue.

Architecture Overview

1. An application pushes messages to an SQS queue.

2. AWS Lambda automatically polls the queue.

3. When messages arrive, Lambda invokes your function with a batch.

4. Your function processes each message.

Create a .NET Lambda Project

Start by creating a plain .NET project. You don’t need any special templates for this walkthrough.

dotnet new console -n SqsLambdaProcessor
cd SqsLambdaProcessor

Add the necessary AWS Lambda packages:

dotnet add package Amazon.Lambda.Core
dotnet add package Amazon.Lambda.SQSEvents
dotnet add package Amazon.Lambda.Serialization.SystemTextJson

Rename Program.cs to Function.cs, or create a new Function.cs file, and define your handler:

using Amazon.Lambda.SQSEvents;
using Amazon.Lambda.Core;

[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))]

public class Function
{
    public async Task FunctionHandler(SQSEvent evnt, ILambdaContext context)
    {
        foreach (var message in evnt.Records)
        {
            await ProcessMessageAsync(message, context);
        }
    }

    private Task ProcessMessageAsync(SQSEvent.SQSMessage message, ILambdaContext context)
    {
        context.Logger.LogLine($"Processing message {message.MessageId}: {message.Body}");

        // Add your business logic here

        return Task.CompletedTask;
    }
}

Deploy the Lambda

To deploy, you can use the AWS CLI, AWS Console, or the AWS Toolkit for Visual Studio. Here's how to deploy using the AWS CLI with the Lambda .NET tooling:

1. Package the project:

dotnet lambda package --output-package bin/release/sqs-lambda.zip

2. Deploy the function:

aws lambda create-function \
  --function-name SqsLambdaProcessor \
  --runtime dotnet6 \
  --handler SqsLambdaProcessor::SqsLambdaProcessor.Function::FunctionHandler \
  --zip-file fileb://bin/release/sqs-lambda.zip \
  --role arn:aws:iam::YOUR_ACCOUNT_ID:role/YOUR_LAMBDA_EXECUTION_ROLE

Replace the role ARN with your actual IAM role that allows Lambda execution and access to SQS.

Connect the SQS Queue

You can configure the SQS queue as an event source:

aws lambda create-event-source-mapping \
  --function-name SqsLambdaProcessor \
  --event-source-arn arn:aws:sqs:us-east-1:123456789012:your-queue-name \
  --batch-size 5

Test Locally

You can write unit tests using the Amazon.Lambda.TestUtilities package:

dotnet add package Amazon.Lambda.TestUtilities

Example test:

[Fact]
public async Task TestHandlerProcessesMessages()
{
    var function = new Function();
    var context = new TestLambdaContext();
    var sqsEvent = new SQSEvent
    {
        Records = new List<SQSEvent.SQSMessage>
        {
            new SQSEvent.SQSMessage { Body = "Test Message" }
        }
    };

    await function.FunctionHandler(sqsEvent, context);
}

Error Handling and Retries

Lambda automatically retries failed messages. To handle failures:

• Implement try-catch inside ProcessMessageAsync.

• Set up a Dead Letter Queue (DLQ) on your Lambda or SQS.

• Use structured logging to track errors.

Best Practices

• Make your function idempotent to handle retries safely.

• Tune batch size to optimize throughput vs. memory usage.

• Keep Lambda’s timeout below the SQS visibility timeout.

• Log enough information to troubleshoot failures.

Cleanup

To remove the resources:

aws lambda delete-function --function-name SqsLambdaProcessor
aws sqs delete-queue --queue-url https://sqs.us-east-1.amazonaws.com/123456789012/your-queue-name

References

• Amazon SQS

• AWS Lambda with SQS

• Amazon.Lambda.SQSEvents on NuGet

• AWS .NET Lambda Tools GitHub

What Changed?

Before C# 13, lambda expressions required all parameters to be explicitly supplied. If you wanted default values, you'd have to wrap your lambda in a method or use null checks and ternary operators inside the lambda body.

With C# 13, you can now define default values directly in the lambda parameter list, just like you can with regular methods.

Example

Here’s how it looks in practice:

Func<string, string, string> greet = (name = "World", prefix = "Hello") => $"{prefix}, {name}!";

Console.WriteLine(greet()); // Hello, World!
Console.WriteLine(greet("Developer")); // Hello, Developer!
Console.WriteLine(greet("Developer", "Hi")); // Hi, Developer!

This makes lambda expressions significantly more concise and expressive, especially when used in callbacks, event handlers, or functional programming patterns.

Why It Matters

Adding default parameters to lambdas helps in several ways:

• Cleaner Code: Removes the need for wrapper methods or inline null checks.

• More Expressive: The intent is clearer when default behavior is defined right at the parameter level.

• Useful in Functional Scenarios: When passing lambdas into LINQ, configuration setups, or task pipelines, it reduces boilerplate.

Limitations

While this is a powerful feature, there are some caveats to be aware of:

• You must use explicitly-typed lambda expressions. Type inference alone won't work when using default values.

• This feature does not apply to anonymous methods (delegate { }).

• It may not be supported by older tooling or analyzers that haven't yet been updated for C# 13.

Summary

The default parameter values in lambda expressions is a small but impactful improvement in C# 13. It aligns lambdas more closely with traditional methods and opens up new, cleaner ways to write inline logic.

As C# continues to evolve alongside .NET, these kinds of enhancements demonstrate a strong commitment to developer productivity and language consistency.

References

• C# Language Proposal - Default Parameter Values in Lambdas

• .NET 10 Preview Release Notes

Prerequisites

• .NET 6 or later SDK

• AWS CLI (configured with credentials)

• Amazon.Lambda.Tools CLI (dotnet tool install -g Amazon.Lambda.Tools)

• An existing or new S3 bucket

Step 1: Create the Lambda Project

Start with the empty Lambda template:

dotnet new lambda.EmptyFunction --name S3TriggeredLambda
cd S3TriggeredLambda

Step 2: Define the Handler for S3 Events

Update Function.cs to accept an S3Event and log the key of the uploaded file:

using Amazon.Lambda.S3Events;
using Amazon.S3;
using Amazon.S3.Util;
using Amazon.Lambda.Core;

[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))]

public class Function
{
    private readonly IAmazonS3 _s3Client;

    public Function() : this(new AmazonS3Client()) { }

    public Function(IAmazonS3 s3Client)
    {
        _s3Client = s3Client;
    }

    public async Task FunctionHandler(S3Event evnt, ILambdaContext context)
    {
        foreach (var record in evnt.Records)
        {
            var bucket = record.S3.Bucket.Name;
            var key = record.S3.Object.Key;

            context.Logger.LogLine($"File uploaded to S3: {bucket}/{key}");

            // Optional: read content
            var response = await _s3Client.GetObjectAsync(bucket, key);
            using var reader = new StreamReader(response.ResponseStream);
            var content = await reader.ReadToEndAsync();

            context.Logger.LogLine($"First 100 characters: {content[..Math.Min(100, content.Length)]}");
        }
    }
}

Step 3: Configure Lambda Deployment

Create aws-lambda-tools-defaults.json:

{
  "profile": "default",
  "region": "us-east-1",
  "configuration": "Release",
  "framework": "net6.0",
  "function-runtime": "dotnet6",
  "function-handler": "S3TriggeredLambda::S3TriggeredLambda.Function::FunctionHandler",
  "function-memory-size": 256,
  "function-timeout": 30,
  "function-name": "S3TriggeredLambda",
  "function-role": "arn:aws:iam::123456789012:role/your-lambda-role"
}

Step 4: Deploy the Function

dotnet lambda deploy-function

Take note of the function name or ARN printed after deployment.

Step 5: Configure S3 to Trigger the Lambda

Use the AWS CLI or Console to attach the Lambda as a notification target for your S3 bucket.

Option A: Using AWS Console

• Go to your S3 bucket

• Choose Properties > Event notifications

• Create a new event

  • Event type: PUT

  • Destination: Lambda function

  • Select your Lambda

Option B: Using AWS CLI

aws s3api put-bucket-notification-configuration --bucket your-bucket-name --notification-configuration '{
  "LambdaFunctionConfigurations": [
    {
      "LambdaFunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:S3TriggeredLambda",
      "Events": ["s3:ObjectCreated:*"]
    }
  ]
}'

Make sure your Lambda function has permission to be invoked by S3:

aws lambda add-permission \
  --function-name S3TriggeredLambda \
  --principal s3.amazonaws.com \
  --statement-id s3invoke \
  --action "lambda:InvokeFunction" \
  --source-arn arn:aws:s3:::your-bucket-name

Step 6: Test the Integration

Upload a file to your S3 bucket:

aws s3 cp sample.txt s3://your-bucket-name/

Then check the Lambda logs:

aws logs describe-log-groups
aws logs get-log-events --log-group-name /aws/lambda/S3TriggeredLambda --log-stream-name <latest-stream-name>

You should see log lines indicating that your Lambda processed the S3 object.

Cleanup

To avoid charges, delete the Lambda function and remove the S3 notification:

aws lambda delete-function --function-name S3TriggeredLambda

Summary

You’ve now connected S3 with a .NET Lambda to react to file uploads in real time. This pattern is ideal for file processing pipelines, ingestion workflows, or triggering downstream services without managing infrastructure.

References

• AWS Lambda for .NET

• S3 Event Notification Documentation

• Amazon.Lambda.S3Events Package text

• Lambda Permission Policy for S3

• Working with AWS SDK for .NET

Prerequisites

• .NET 6 or later SDK

• AWS CLI (configured with credentials)

• Amazon.Lambda.Tools CLI

Install the AWS Lambda tools globally if you haven’t already:

dotnet tool install -g Amazon.Lambda.Tools

Step 1: Create a Minimal API

We'll start with a simple .NET 6+ Web API using Minimal APIs:

dotnet new webapi -n MyLambdaApi
cd MyLambdaApi

(Optional) Clean up the template a bit and define your own minimal endpoint in Program.cs:

var app = WebApplication.Create(args);
app.MapGet("/hello", () => "Hello from Lambda!");
app.Run();

Step 2: Add Lambda Support

Install the necessary NuGet packages:

dotnet add package Amazon.Lambda.AspNetCoreServer
dotnet add package Amazon.Lambda.RuntimeSupport

Then, add a new class LambdaEntryPoint.cs:

public class LambdaEntryPoint : Amazon.Lambda.AspNetCoreServer.APIGatewayProxyFunction
{
    protected override void Init(IWebHostBuilder builder)
    {
        builder.UseStartup<Startup>();
    }
}

Make sure Startup.cs exists and configures your services like normal.

Step 3: Add Lambda Project Configuration

Create a aws-lambda-tools-defaults.json file in the project root:

{
  "profile": "default",
  "region": "us-east-1",
  "configuration": "Release",
  "framework": "net6.0",
  "function-runtime": "dotnet6",
  "function-handler": "MyLambdaApi::MyLambdaApi.LambdaEntryPoint::FunctionHandlerAsync",
  "function-memory-size": 512,
  "function-timeout": 30,
  "function-name": "MyLambdaApi",
  "function-role": "arn:aws:iam::123456789012:role/your-lambda-role"
}

Step 4: Deploy to AWS Lambda

Build and deploy using the Lambda tools:

dotnet lambda deploy-serverless

This command packages your app, creates a Lambda function, and wires it to an API Gateway endpoint.

After deployment, it will print a URL like:

https://xyz123.execute-api.us-east-1.amazonaws.com/Prod/hello

You can test it using curl or a browser.

Step 5: Test the Endpoint

curl https://xyz123.execute-api.us-east-1.amazonaws.com/Prod/hello
# → Hello from Lambda!

Cleanup

To avoid charges:

aws cloudformation delete-stack --stack-name MyLambdaApi

Summary

You’ve just deployed a real .NET Web API to AWS Lambda using API Gateway with no servers in sight. This pattern is perfect for lightweight APIs, backend services, and microservices.

Stay tuned for the next post in the CloudSharp series, where we'll wire this API to a DynamoDB backend.

References

• AWS Lambda for .NET

• Amazon.Lambda.Tools GitHub Repo

• Deploying .NET Lambda Functions

• ASP.NET Core Minimal APIs

• API Gateway and Lambda Integration

Prerequisites

Before you begin, make sure you have the following:

• .NET SDK (>= 6.0) installed: https://dotnet.microsoft.com/download

• AWS CLI configured with credentials and default region: Installing the AWS CLI

• Amazon.Lambda.Templates installed:

    dotnet new install Amazon.Lambda.Templates
  

• An existing DynamoDB table or permissions to create one

• Basic familiarity with AWS Lambda and DynamoDB

• (Optional) AWS Toolkit for Visual Studio if you prefer a GUI deployment experience

What Are DynamoDB Streams?

DynamoDB Streams capture table activity (inserts, updates, and deletes) and store the change records in a stream. You can attach an AWS Lambda function to the stream so it automatically gets invoked when changes occur.

Use cases include:

• Real-time analytics

• Auditing and logging

• Replicating data to other systems

Enabling Streams on a Table

You can enable streams using the AWS Console, CLI, or CloudFormation. For example, using AWS CLI:

aws dynamodb update-table \
  --table-name MyTable \
  --stream-specification StreamEnabled=true,StreamViewType=NEW_AND_OLD_IMAGES

The StreamViewType determines what data is captured:

• KEYS_ONLY

• NEW_IMAGE

• OLD_IMAGE

• NEW_AND_OLD_IMAGES (recommended for most cases)

Creating a .NET Lambda to Process Stream Records

Let's build a .NET Lambda that listens to a DynamoDB Stream and processes the records.

1. Create a New Lambda Project

Use the AWS Lambda template:

dotnet new lambda.DynamoDBEventFunction -n DynamoDbStreamConsumer
cd DynamoDbStreamConsumer

2. Update the Function Handler

In Function.csYou’ll find a method like this:

public async Task FunctionHandler(DynamoDBEvent dynamoEvent, ILambdaContext context)
{
    foreach (var record in dynamoEvent.Records)
    {
        context.Logger.LogInformation($"Event ID: {record.EventID}");
        context.Logger.LogInformation($"Event Name: {record.EventName}");

        if (record.Dynamodb.NewImage != null)
        {
            var item = Document.FromAttributeMap(record.Dynamodb.NewImage);
            context.Logger.LogInformation($"New item: {item.ToJsonPretty()}");
        }

        if (record.Dynamodb.OldImage != null)
        {
            var oldItem = Document.FromAttributeMap(record.Dynamodb.OldImage);
            context.Logger.LogInformation($"Old item: {oldItem.ToJsonPretty()}");
        }
    }
}

You can deserialize NewImage and OldImage to your model if needed.

3. Deploy the Lambda Function

You can deploy the function using the AWS Toolkit for Visual Studio or with the CLI:

dotnet lambda deploy-function DynamoDbStreamConsumer

4. Attach the Stream to Lambda

After deployment, link the DynamoDB stream to the Lambda:

aws lambda create-event-source-mapping \
  --function-name DynamoDbStreamConsumer \
  --event-source arn:aws:dynamodb:region:account-id:table/MyTable/stream/timestamp \
  --starting-position LATEST \
  --batch-size 10

This sets up the Lambda to process stream records in batches of 10.

Error Handling and Retries

If your Lambda throws an exception, the batch is retried until it succeeds or expires. To avoid poison pills:

• Use a dead-letter queue (DLQ)

• Enable partial batch response to skip bad records

Logging and Monitoring

Use Amazon CloudWatch Logs to debug and monitor stream processing. You can also add structured logging with Serilog or Microsoft.Extensions.Logging.

Conclusion

Using DynamoDB Streams with .NET Lambda functions allows you to build reactive, event-driven applications with minimal overhead. Whether you're tracking changes, replicating data, or triggering downstream processes, this integration is a powerful tool in your AWS toolkit.

References

• DynamoDB Streams Documentation

• AWS Lambda with DynamoDB Streams

• AWS SDK for .NET

• dotnet-lambda CLI Tool

Prerequisites

Before you start, make sure you have:

• .NET SDK 6.0 or later

• AWS CLI (configured with credentials)

• Amazon.Lambda.Tools

• An AWS account

Install the Lambda tooling with:

dotnet tool install -g Amazon.Lambda.Tools

Step 1: Create a Lambda Project

You can create a new Lambda project using one of the AWS templates:

dotnet new lambda.EmptyFunction --name MyLambdaFunction
cd MyLambdaFunction

The main function logic will be in Function.cs, under the method FunctionHandler.

Step 2: Write Your Function Logic

Edit Function.cs to match your logic. For example:

public class Function
{
    public string FunctionHandler(string input, ILambdaContext context)
    {
        return $"Hello, {input}!";
    }
}

Step 3: Test Locally

You can test the function locally with:

dotnet lambda invoke-function MyLambdaFunction --payload "World"

Step 4: Deploy to AWS

Deploy using the Lambda tools:

dotnet lambda deploy-function MyLambdaFunction

You’ll be prompted for details like the IAM role, region, and function name. You can also use --function-role, --region, and other flags to script deployments.

Step 5: Invoke from AWS Console or API

Once deployed, you can:

• Test it from the AWS Lambda Console

• Invoke it using the AWS CLI:

aws lambda invoke \
  --function-name MyLambdaFunction \
  --payload "\"John Doe\"" \
  output.json

Optional: Set Up API Gateway

To expose your Lambda via HTTP, connect it to API Gateway:

• In the AWS Console, go to API Gateway.

• Create a new HTTP API.

• Add an integration with your Lambda.

• Deploy the API and use the URL to invoke your Lambda.

Cleanup

To delete the Lambda and avoid charges:

aws lambda delete-function --function-name MyLambdaFunction

Conclusion

Running .NET on AWS Lambda is a great way to take advantage of serverless architecture while using C#. With a few CLI commands, you can deploy scalable functions to the cloud without managing infrastructure.

Need advanced patterns, like dependency injection, configuration, or async I/O? AWS .NET Lambda projects support all of them. Let me know if you want a follow-up post on those topics.

References

• AWS Lambda for .NET
  https://docs.aws.amazon.com/lambda/latest/dg/dotnet.html

• AWS Toolkit for .NET CLI (Amazon.Lambda.Tools)
  https://github.com/aws/aws-extensions-for-dotnet-cli

• .NET Templates for AWS Lambda
  https://docs.aws.amazon.com/lambda/latest/dg/csharp-package-cli.html

• Deploying .NET Lambda Functions
  https://docs.aws.amazon.com/lambda/latest/dg/csharp-deployment-package.html

• Testing AWS Lambda Functions Locally
  https://docs.aws.amazon.com/lambda/latest/dg/images-test.html

• AWS Lambda + API Gateway Integration
  https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-getting-started-with-rest-apis.html

• .NET on AWS – Official AWS Page
  https://aws.amazon.com/net/

Key Advantages:

• Immediate Execution: Run C# code instantly without project scaffolding.

• Simplified Tooling: No additional tools or dependencies required—just the dotnet CLI and your .cs file.

• Scalable Development: Easily transition from a single script to a full-fledged project as your application grows.

Enhancing Scripts with File-Level Directives

.NET 10 introduces file-level directives that bring additional capabilities to single-file C# applications:

• NuGet Package References: Include external packages directly within your script using the #:package directive.

    #:package Humanizer@2.14.1
    using Humanizer;
  
    var releaseDate = DateTimeOffset.Parse("2024-12-03");
    var duration = DateTimeOffset.Now - releaseDate;
    Console.WriteLine($"Released {duration.Humanize()} ago.");
  

• SDK Specification: Define the SDK context (e.g., for web applications) with the #:sdk

    #:sdk Microsoft.NET.Sdk.Web
  

• MSBuild Properties: Set build properties like language version using the #:property directive.

    #:property LangVersion preview
  

• Shebang Support: Create executable scripts on Unix-like systems with shebang lines.

    #!/usr/bin/dotnet run
    Console.WriteLine("Hello from a C# script!");
  

Make the script executable and run it:

chmod +x app.cs
./app.cs

Seamless Transition to Project-Based Applications

When your script evolves into a more complex application, you can convert it into a standard project effortlessly:

dotnet project convert app.cs

Getting Started

1. Install .NET 10 Preview 4: Download and install from the official .NET website.

2. Set Up Your Editor: For Visual Studio Code, install the C# Dev Kit and switch to the pre-release version of the C# extension to enable file-based app support.

3. Write Your Script: Create a file named hello.cs with the following content:

    Console.WriteLine("Hello, world!");
   

Run Your Script: Execute the script using the command:

dotnet run hello.cs

Embracing a More Accessible C

The introduction of dotnet run app.cs marks a significant step towards making C# more approachable and versatile. By streamlining the execution of C# code, Microsoft empowers developers to experiment, learn, and build applications more easily and efficiently.

Referrences

• https://devblogs.microsoft.com/dotnet/announcing-dotnet-run-app/

In this post, I’ll walk you through the complete setup for returning binary content (like images) from API Gateway using a Lambda function. I’ll also show how to configure it using SAM/CloudFormation and share a few lessons I wish I knew when I started.

Why Is Binary Content So Tricky with API Gateway?

API Gateway was originally built around text-based communication, like JSON or plain text. By default, it doesn’t expect raw binary. So when you return binary data, you must explicitly tell API Gateway how to handle it. If you skip any step, you’ll either get unreadable output or empty files.

Stack Used

• AWS Lambda (Python)

• API Gateway (REST, not HTTP API)

• AWS SAM (Serverless Application Model)

• Google Maps API to fetch image content

Step 1: Configure Binary Support in API Gateway

You need to declare which binary media types your API supports. This is done in the BinaryMediaTypes section of the AWS::ApiGateway::RestApi resource.

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: Example SAM template for returning binary content through API Gateway

Globals:
  Function:
    Timeout: 30
    Runtime: python3.12

Resources:
  BinaryEnabledApi:
    Type: AWS::ApiGateway::RestApi
    Properties:
      Name: binary-enabled-api
      BinaryMediaTypes:
        - "*/*"
      EndpointConfiguration:
        Types:
          - PRIVATE

  ApiRootResource:
    Type: AWS::ApiGateway::Resource
    Properties:
      RestApiId: !Ref BinaryEnabledApi
      ParentId: !GetAtt BinaryEnabledApi.RootResourceId
      PathPart: "api"

  ImageResource:
    Type: AWS::ApiGateway::Resource
    Properties:
      RestApiId: !Ref BinaryEnabledApi
      ParentId: !Ref ApiRootResource
      PathPart: "image"

  GetImageMethod:
    Type: AWS::ApiGateway::Method
    Properties:
      RestApiId: !Ref BinaryEnabledApi
      ResourceId: !Ref ImageResource
      HttpMethod: GET
      AuthorizationType: NONE
      Integration:
        Type: AWS_PROXY
        IntegrationHttpMethod: POST
        Uri: !Sub
          - "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${LambdaArn}/invocations"
          - { LambdaArn: !GetAtt BinaryLambdaFunction.Arn }
        PassthroughBehavior: WHEN_NO_MATCH

  BinaryLambdaFunction:
    Type: AWS::Serverless::Function
    Properties:
      FunctionName: binary-content-handler
      CodeUri: src/
      Handler: app.lambda_handler
      MemorySize: 128
      Tracing: Active
      Policies: AWSLambdaBasicExecutionRole

  LambdaInvokePermission:
    Type: AWS::Lambda::Permission
    Properties:
      Action: lambda:InvokeFunction
      FunctionName: !Ref BinaryLambdaFunction
      Principal: apigateway.amazonaws.com
      SourceArn: !Sub "arn:aws:execute-api:${AWS::Region}:${AWS::AccountId}:${BinaryEnabledApi}/*/GET/api/image"

  ApiDeployment:
    Type: AWS::ApiGateway::Deployment
    DependsOn:
      - GetImageMethod
    Properties:
      RestApiId: !Ref BinaryEnabledApi

  ApiStage:
    Type: AWS::ApiGateway::Stage
    Properties:
      StageName: prod
      RestApiId: !Ref BinaryEnabledApi
      DeploymentId: !Ref ApiDeployment
      MethodSettings:
        - ResourcePath: "/*"
          HttpMethod: "*"
          MetricsEnabled: true
          LoggingLevel: INFO

Outputs:
  ApiInvokeUrl:
    Description: Invoke URL for the binary-enabled API
    Value: !Sub "https://${BinaryEnabledApi}.execute-api.${AWS::Region}.amazonaws.com/prod/api/image"

Important: Any time you update BinaryMediaTypes, make sure to redeploy your API and its stage. Changes won't take effect until that happens.

Step 2: Make Lambda Return the Right Format

Your Lambda function must return a Base64-encoded string with specific fields set in the response.

Example: Returning a Static Map Image

import base64
import requests

def lambda_handler(event, context):
    image_url = "https://maps.googleapis.com/maps/api/staticmap?center=New+York&zoom=13&size=600x300&key=YOUR_API_KEY"
    response = requests.get(image_url)

    return {
        "statusCode": 200,
        "headers": {
            "Content-Type": "image/png"
        },
        "body": base64.b64encode(response.content).decode("utf-8"),
        "isBase64Encoded": True
    }

Step 3: Test with Real Clients

Tools that won't work reliably:

• AWS Console’s “Test” feature

• CloudWatch Logs (shows only the base64 string)

Tools that work correctly:

• Postman

• Curl

• Browsers

Example curl command:

curl -H "Authorization: ..." \
     https://your-api-id.execute-api.us-west-2.amazonaws.com/prod/api/image \
     --output result.png

Common Pitfalls

Here are the mistakes that cost me the most time:

• Forgetting to set "isBase64Encoded": true in the Lambda response

• Not setting the correct Content-Type header

• Expecting binary output to work with the default test tools

• Using HTTP API instead of REST API (binary support is limited in HTTP APIs)

• Forgetting to redeploy after changing BinaryMediaTypes

Final Thoughts

Returning binary content through API Gateway is not intuitive at first, but once you know what to configure, it works reliably. This setup is especially useful for services that return images, PDFs, or any kind of binary payload directly from Lambda.

If this helped you get your API working, feel free to share it or reach out. I’d love to hear how you used it in your project.

References

• API Gateway Binary Support Docs

• AWS SAM Template Reference