Part 1: The Foundations of Production .NET Services
A practical guide for building, operating, and deploying reliable ASP.NET Core services on AWS.
Audience: .NET developers moving from working APIs to production services.
Reference example: an Orders API using ASP.NET Core, EF Core, PostgreSQL, and Amazon ECS Fargate.
Prepared: 24 October 2026. Commands and configuration are instructional examples; this document does not provision or deploy resources.
1. What you will learn
- Define what makes a service ready for production.
- Organise a .NET application around clear responsibilities.
- Understand request processing, dependency injection, and asynchronous I/O.
- Design secure APIs and dependable database operations.
- Add configuration validation, health checks, logs, metrics, and traces.
- Package a service as a Linux container.
- Deploy it behind HTTPS on AWS with private networking and managed persistence.
- Validate a release, recover from failures, and understand deployment trade-offs.
Reference assumptions
- Use .NET 10 LTS with current security patches; confirm support before starting a new project. [S1]
- Build one independently deployable Orders service first.
- Use PostgreSQL for the worked AWS example. The same principles apply to SQL Server, but providers, SQL syntax, licensing, and operational settings differ.
- Start with synchronous HTTP request handling for short operations; introduce a durable queue for work that must survive an API process restart.
- Choose ECS Fargate here to run containers without managing EC2 hosts. This is a design choice for this example, not a universal requirement.
- Use
eu-west-2for the sample commands. Select the region based on residency, dependency availability, latency, and business requirements.
2. Working software versus production software
A production service needs predictable behaviour when users, dependencies, infrastructure, or deployments fail.
| Concern | Development shortcut | Production foundation |
|---|---|---|
| Configuration | Values copied into code | Environment-specific settings validated at startup |
| Credentials | Password in a settings file | Managed secrets and least-privilege identities |
| Failure handling | Unhandled exception | Consistent error contract and correlated diagnostics |
| Persistence | Happy-path inserts | Constraints, transactions, concurrency control, backups |
| Scaling | One local process | Stateless replicas and explicit capacity limits |
| Deployment | Replace files manually | Versioned image, automated checks, controlled rollout |
| Operations | Read console output | Searchable logs, metrics, traces, alarms, runbooks |
| Recovery | Restart and hope | Rollback procedure and tested restore process |
Define measurable service goals
- Identify the critical user journey: create an order and retrieve its status.
- Define availability and latency targets with the product owner.
- Example targets for discussion: 99.9% monthly availability and p95 read latency below 300 ms at the agreed load.
- Define the measurement point, eligible requests, observation window, and exclusions before treating a target as an SLO.
- Agree recovery time objective (RTO): how long the business can tolerate an outage.
- Agree recovery point objective (RPO): how much data loss the business can tolerate.
- Treat these figures as requirements to validate with testing and recovery exercises.
3. Start with a service boundary
Orders service responsibilities
- Accept order requests.
- Validate products, quantities, and relevant customer ownership.
- Calculate or verify trusted prices on the server.
- Persist orders atomically.
- Return order status to authorised users.
- Emit a durable event when downstream work is introduced.
Keep boundaries explicit
- The Orders service owns its order tables and schema changes.
- Other services use its API or published events rather than updating its tables directly.
- Keep payment processing outside database transactions that hold locks while waiting on a remote API.
- Avoid splitting every entity into a separate microservice.
- A modular monolith is a valid starting point when modules share deployment and ownership needs.
- Split services when independent deployment, security isolation, scaling, or team ownership justifies the operational cost.
flowchart TD
Client["Web or mobile client"] --> Api["Orders API"]
Api --> Application["Order use cases"]
Application --> Domain["Business rules"]
Application --> Data["Persistence adapter"]
Data --> Db[("Orders database")]
Application --> External["External service adapter"]- HTTP and persistence details stay at the edges.
- Business rules should be testable without starting a web server.
- The diagram shows runtime calls; source-code dependencies should point toward application contracts and domain rules.
4. A practical solution structure
Use this structure when the service has enough business behaviour to benefit from separate projects. A small CRUD service can start with feature folders in one project.
Orders/
src/
Orders.Api/
Endpoints/
Middleware/
Configuration/
Program.cs
appsettings.json
Orders.Api.csproj
Orders.Application/
Orders/
Abstractions/
Orders.Application.csproj
Orders.Domain/
Orders/
Orders.Domain.csproj
Orders.Infrastructure/
Persistence/
Integrations/
Orders.Infrastructure.csproj
tests/
Orders.UnitTests/
Orders.IntegrationTests/
deploy/
task-definition.json
infrastructure/
Dockerfile
.dockerignore
README.md
| Project | Responsibility | Typical dependencies |
|---|---|---|
| Domain | Entities, invariants, value objects | Standard library |
| Application | Use cases and interfaces | Domain |
| Infrastructure | EF Core and external adapters | Application and Domain |
| API | HTTP contract and composition root | Application; Infrastructure for registration |
- Keep dependencies deliberate; do not create a generic repository merely to wrap every EF Core operation.
- Use DTOs at HTTP boundaries rather than exposing tracked database entities.
- Keep naming aligned with business operations, such as
CreateOrder, rather than generic helper classes. - Record significant decisions in short architecture decision records.
5. Understand the ASP.NET Core request lifecycle
flowchart TD
Request["Incoming request"] --> Proxy["Trusted proxy headers"]
Proxy --> Errors["Exception handling and tracing"]
Errors --> Routing["Routing and request limits"]
Routing --> Auth["Authentication"]
Auth --> Access{"Authorised?"}
Access -->|No| Reject["401 or 403"]
Access -->|Yes| Validate["Validate input"]
Validate --> Valid{"Valid?"}
Valid -->|No| Bad["400 validation response"]
Valid -->|Yes| Handler["Execute use case"]
Handler --> Response["Serialize response"]Middleware principles
- Order matters: exception handling must surround work whose failures it should handle.
- Process trusted forwarded headers before logic that depends on the original scheme or client IP. [S3]
- Put authentication before authorisation.
- Place endpoint-specific rate limiting after routing; place it after authentication when partitions depend on user identity.
- Configure CORS only for known browser origins that need cross-origin access.
- CORS is a browser policy; it does not authenticate clients.
- Serve public OpenAPI documentation only when that is an intentional access decision.
- Do not return stack traces or database connection details to clients.
HTTPS behind an AWS load balancer
- Terminate public TLS at the Application Load Balancer (ALB) using an ACM certificate.
- Redirect public HTTP to HTTPS at the ALB listener.
- The example uses HTTP from ALB to tasks inside the VPC; choose backend TLS when required by the threat model or compliance requirements.
- If the application consumes forwarded headers, explicitly trust the actual proxy addresses or narrowly scoped networks and set an appropriate forwarding limit.
- Do not clear all trusted proxy restrictions to make HTTPS redirects work.
- An API using ALB-managed HTTPS can avoid application-level redirect loops by keeping redirect ownership at the ALB.
6. Dependency injection and service lifetimes
| Lifetime | Behaviour | Typical use | Common mistake |
|---|---|---|---|
| Transient | New instance each time it is resolved | Lightweight stateless components | Expensive repeated construction |
| Scoped | One instance per scope, usually per HTTP request | EF Core DbContext and request use cases | Capturing it in a singleton |
| Singleton | One instance per application container | Thread-safe shared services | Mutable state without synchronisation |
- Keep
DbContextscoped and avoid using the same instance concurrently. - Use constructor injection to make dependencies visible.
- Do not use the service provider as a general-purpose service locator.
- A singleton background worker must create a scope for scoped dependencies.
- Keep request state out of singleton fields.
- Use
IHttpClientFactoryfor centrally configured outbound HTTP clients. [S2]
// Registration fragment in Program.cs for the example application.
builder.Services.AddScoped<IOrderService, OrderService>();
builder.Services.AddHttpClient("catalogue", client =>
{
client.BaseAddress = new Uri("https://catalogue.example.com/");
client.Timeout = TimeSpan.FromSeconds(3);
});
- The catalogue URI is a placeholder.
- Do not register an external dependency unless the service actually needs it.
7. Async I/O, cancellation, and bounded concurrency
- Use asynchronous database and HTTP APIs end to end.
- Pass the request cancellation token into supported downstream operations.
- Avoid
.Result,.Wait(), and blocking I/O on request paths. [S2] - Do not wrap asynchronous I/O in
Task.Runto make it asynchronous. - An
awaitcan release the request thread while I/O is incomplete; it does not allocate a dedicated waiting thread or guarantee a thread switch. - CPU work still occupies a thread. Large CPU workloads need bounded execution and usually a separate worker.
- Limit concurrent downstream calls; unbounded
Task.WhenAllcan overwhelm a connection pool or dependency. - Keep database transactions short.
// Read-path fragment: requires an EF Core DbContext with an Orders DbSet.
var order = await db.Orders
.AsNoTracking()
.Where(x => x.Id == orderId && x.CustomerId == customerId)
.Select(x => new OrderSummary(x.Id, x.Status, x.Total))
.SingleOrDefaultAsync(cancellationToken);
- The ownership filter is part of the data access, not an assumption based on an order ID.
- Derive
customerIdfrom a validated identity or trusted server-side mapping. AsNoTrackingsuits read-only queries; use tracking deliberately for changes.
sequenceDiagram
autonumber
participant Client
participant API
participant DB as Database
Client->>API: Request order
API->>DB: Start asynchronous query
Note over API: Await incomplete I/O; thread can serve other work
DB-->>API: Query completes
Note over API: Continuation runs on an available thread
API-->>Client: Return order response8. API contracts and predictable errors
Suggested endpoints
| Method and route | Purpose | Typical success |
|---|---|---|
POST /api/orders | Create an order | 201 Created with Location header |
GET /api/orders/{id} | Retrieve an owned order | 200 OK |
GET /api/orders?cursor=...&limit=... | List a bounded page | 200 OK |
POST /api/orders/{id}/cancel | Request a valid state transition | 200 OK or 204 No Content |
GET /health/live | Process liveness | 200 OK |
GET /health/ready | Readiness to receive traffic | 200 OK or 503 |
Input and error rules
- Reject invalid quantities, missing fields, unsupported states, oversized payloads, and invalid identifiers.
- Cap page sizes and use deterministic ordering.
- Use a consistent Problem Details response for errors.
- Return
401when authentication is required or invalid;403when an authenticated identity lacks permission. - Decide consistently whether inaccessible resources return
404to avoid disclosing their existence. - Return
409for a conflict with current state or a conflicting idempotency request. - Return
429for throttling and supply retry guidance where appropriate. - Include a trace identifier that helps operators find the failure.
{
"type": "https://api.example.com/problems/order-state-conflict",
"title": "Order cannot be cancelled",
"status": 409,
"detail": "The order has already been dispatched.",
"traceId": "example-trace-id"
}
Idempotency for create operations
- Accept an idempotency key for client retries where duplicate effects are costly.
- Scope the key to the authenticated caller and operation.
- Persist the key, a request fingerprint, processing state, and reusable result with a uniqueness constraint.
- Make the key reservation and order write atomic where possible.
- Return the prior result for the same completed request; reject a reused key with a different payload.
- Define behaviour for concurrent requests and abandoned in-progress records.
- Document retention and expiry; an expired key cannot prevent all future duplicates.
9. Data integrity and database performance
- Use constraints for invariants that must hold across concurrent requests.
- Use parameterised EF Core queries or parameterised SQL; never concatenate untrusted input into SQL.
- Index actual lookup and filtering patterns, such as customer plus creation time.
- Inspect execution plans and query counts under representative data volumes.
- Project only required columns and avoid N+1 queries.
- Use optimistic concurrency for conflicting updates and translate conflicts into a clear API response.
- Use a transaction for related writes that must succeed together.
- Bound command timeouts and connection pool capacity.
- Calculate connection capacity across all replicas, workers, migration jobs, and deployment surge tasks.
- Use UTC timestamps and an appropriate monetary representation such as decimal plus a currency code.
- Use a restricted application database user; separate schema migration permissions.
- Enable backups and point-in-time recovery where required, then test restoration.
Safe schema changes
flowchart TD
Expand["Add compatible schema"] --> Deploy["Deploy compatible application"]
Deploy --> Backfill["Backfill data in bounded batches"]
Backfill --> Verify{"Data and traffic verified?"}
Verify -->|No| Investigate["Investigate; retain compatibility"]
Investigate --> Verify
Verify -->|Yes| Contract["Remove old schema in a later release"]- Run migrations as an explicit deployment job with one migration executor.
- Do not have every API replica race to apply migrations on startup.
- A rolling release temporarily runs old and new binaries together.
- Application rollback does not undo database changes.
- Keep schema compatible with the previous image until the rollback window closes.
10. Configuration and secrets
- Store safe defaults in
appsettings.json. - Supply environment-specific settings through deployment configuration.
- Use .NET user secrets for local development; they are a development convenience, not an encrypted production vault.
- Store production credentials in Secrets Manager or an appropriate encrypted parameter store. [S7]
- Inject the database connection string using the .NET environment-variable key
ConnectionStrings__Orders. - Validate required values at startup so misconfigured tasks fail before receiving traffic.
- Never log the configuration tree, connection strings, access tokens, or secret values.
- When ECS injects a secret at task startup, rotation does not update running task environments; launch replacement tasks. [S7]
- Use workload IAM roles for AWS access rather than static AWS access keys.
// Options fragment with domain-specific validation added.
builder.Services.AddOptions<OrderOptions>()
.Bind(builder.Configuration.GetSection("Orders"))
.Validate(x => x.MaxItems is > 0 and <= 1000,
"Orders:MaxItems must be between 1 and 1000.")
.ValidateOnStart();
public sealed class OrderOptions
{
public int MaxItems { get; set; }
}
11. Security foundations
Identity and access
- Use a trusted identity provider and validate JWT signature, issuer, audience, and expiry.
- Enforce ownership and tenant isolation for every resource access.
- Apply operation-level permissions, including administrative and bulk endpoints.
- Never trust a caller-supplied tenant or customer ID without authorisation.
- Give the application role access only to the AWS resources it uses.
HTTP and application controls
- Require HTTPS at the public boundary.
- Set request size limits, accepted content types, and bounded execution budgets.
- Use rate limits and abuse controls; in-process counters apply per replica unless backed by a shared design.
- Protect cookie-authenticated state-changing requests against CSRF. SameSite settings support the defence but should be assessed with the complete authentication flow.
- A bearer-token API without automatically attached authentication cookies has a different CSRF exposure; XSS and token theft remain relevant.
- Apply CSP to pages that render HTML and scripts; CSP does not replace API authorisation.
- Prevent SSRF when fetching caller-provided URLs: constrain destinations, redirects, DNS resolution, and internal or metadata address access.
- Redact personal data and set log retention deliberately.
- Keep runtime, NuGet packages, base images, and operating-system layers patched.
- Scan source, dependencies, and images; triage findings rather than treating a green scanner as proof of security.
12. Reliability when dependencies fail
| Control | Purpose | Example rule |
|---|---|---|
| Timeout | Bound waiting | Set an operation budget and shorter dependency budgets |
| Cancellation | Stop unnecessary work | Propagate cancellation where supported |
| Retry with jitter | Recover from transient errors | Limited retries within the total budget |
| Circuit breaker | Avoid repeated calls to a failing dependency | Reject temporarily after a configured failure threshold |
| Concurrency limit | Bound pressure | Cap simultaneous calls to the catalogue |
| Idempotency | Avoid duplicate effects | Persist request keys for order creation |
| Durable queue | Survive process loss | Persist work before acknowledging acceptance |
- Retry only failures likely to be transient.
- Do not retry non-idempotent writes unless their semantics make retries safe.
- Avoid nested retry policies that multiply attempts.
- Treat a database commit timeout as an uncertain outcome; reconcile before blindly repeating writes.
- Use an outbox when a database write and an outgoing event must remain consistent.
- A
BackgroundServicealone does not make an in-memory job durable. - Keep the detailed queue, outbox, and worker implementation for a later part; recognise the boundary now.
13. Observability and health checks
Logs
- Emit structured JSON logs to standard output.
- Include service name, environment, deployment version, trace ID, operation, duration, and outcome.
- Use message templates rather than string interpolation for searchable properties.
- Redact tokens, passwords, payment details, and unnecessary personal information.
logger.LogInformation(
"Order {OrderId} created in {ElapsedMs} ms", order.Id, elapsedMs);
Metrics and traces
- Track request count, error rate, p50/p95/p99 latency, and throughput.
- Monitor CPU, memory, thread-pool pressure, database connection usage, and dependency latency.
- Track business signals such as order creation failures separately from HTTP failures.
- Use OpenTelemetry instrumentation and a configured exporter or collector for end-to-end tracing.
- Do not put order IDs, email addresses, or user IDs into metric labels; high cardinality makes metrics expensive and hard to use.
- Connect actionable alarms to an on-call owner and a runbook.
Liveness and readiness
- Liveness asks whether the process is functioning; do not make it depend on database availability.
- Readiness asks whether the instance can serve its intended traffic.
- Register lightweight dependency checks only where their failure should remove an instance from traffic. [S4]
- Use bounded probe timeouts and avoid costly database queries.
- Do not disclose internal diagnostic detail in public health responses.
- Consider fleet-wide outages: making every replica unready does not repair a failed shared database.
- ALB can fail open when all registered targets are unhealthy; readiness is not an access-control boundary. [S10]
// Health endpoint fragment; register actual ready-tagged checks separately.
builder.Services.AddHealthChecks();
app.MapHealthChecks("/health/live", new HealthCheckOptions
{
Predicate = _ => false
});
app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
Predicate = check => check.Tags.Contains("ready")
});
- Import
Microsoft.AspNetCore.Diagnostics.HealthChecks. - With no registered readiness checks,
/health/readydoes not verify database connectivity. - Define an
IHealthCheckor deliberately selected integration for the actual dependency probe before using this as a production readiness signal. - Allow health endpoints without user authentication, restrict detailed output, and block public listener access to health paths if only internal probing is required.
14. Containerise the service
Example Dockerfile
This assumes the solution structure from section 4, no private package feed, and an API assembly named Orders.Api.dll.
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY . .
RUN dotnet restore src/Orders.Api/Orders.Api.csproj
RUN dotnet publish src/Orders.Api/Orders.Api.csproj \
--configuration Release \
--no-restore \
--output /app/publish \
/p:UseAppHost=false
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS runtime
WORKDIR /app
ENV ASPNETCORE_HTTP_PORTS=8080
EXPOSE 8080
USER app
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "Orders.Api.dll"]
Example .dockerignore
**/bin/
**/obj/
.git/
.env
.env.*
**/appsettings.*.local.json
**/*.pfx
**/*.pem
TestResults/
- Keep secrets out of the build context and image layers.
- Run the container as a non-root user.
- Pin approved image digests in the production build process and rebuild deliberately for security patches.
- Keep the runtime image separate from the SDK build stage.
- Use an explicit image architecture that matches the ECS task runtime platform.
- Write logs to stdout; do not rely on container-local files for durable storage.
- Ensure shutdown drains work within the container stop timeout and ALB deregistration settings.
- The Dockerfile is a template; build and smoke-test it against the actual application.
15. AWS reference architecture
flowchart TD
User["API client"] --> DNS["Route 53 DNS"]
DNS --> ALB["Public ALB with ACM HTTPS"]
WAF["AWS WAF web ACL"] -.-> ALB
subgraph VPC["VPC across two Availability Zones"]
ALB --> A["Private Fargate task in AZ A"]
ALB --> B["Private Fargate task in AZ B"]
A --> DB[("Private RDS PostgreSQL Multi-AZ")]
B --> DB
end
A --> Logs["CloudWatch logs and metrics"]
B --> Logs- Route 53 resolves the domain to the ALB; it does not proxy application traffic.
- Associate the WAF web ACL with the ALB when filtering or abuse controls are needed.
- The ALB spans public subnets in two Availability Zones.
- The ECS service runs at least two tasks spread across the selected private application subnets; verify actual placement.
- RDS uses private database subnets and is not publicly accessible.
- Multi-AZ improves availability; it does not replace backups or guarantee zero interruption during failover.
- ECR stores container images; Secrets Manager stores credentials.
- A separate worker service and SQS can be added when asynchronous workflows are required.
AWS component responsibilities
| Component | Responsibility | Important setting |
|---|---|---|
| ECR | Container image registry | Immutable release references and scanning policy |
| ECS cluster and service | Schedule and maintain tasks | Desired count, deployment policy, autoscaling |
| Fargate | Managed task compute | Correct CPU, memory, architecture |
| ALB and target group | HTTP routing and probes | HTTPS listener, ip targets, port 8080 |
| ACM | Public TLS certificate | Certificate in the ALB region |
| RDS PostgreSQL | Durable relational storage | Encryption, backups, Multi-AZ as required |
| Secrets Manager | Store connection credentials | Narrow access and rotation procedure |
| CloudWatch | Logs, metrics, alarms | Retention, ownership, alert thresholds |
| IAM | Service identities and permissions | Separate execution, application, and deployment roles |
| VPC endpoints or NAT | Outbound connectivity | Explicit routes and security groups |
Network boundaries
| Security group | Inbound rule | Purpose |
|---|---|---|
| ALB | TCP 443 from approved clients, or internet for a public API | Public HTTPS |
| ALB | TCP 80 if HTTP redirect is supported | Redirect to HTTPS |
| API tasks | TCP 8080 from ALB security group only | Application traffic and ALB probes |
| Database | TCP 5432 from API and approved migration-task security groups | PostgreSQL |
| Interface endpoints | TCP 443 from relevant task security groups | Private AWS API access |
- Disable public IP assignment for API tasks.
- Use Fargate
awsvpcnetworking and an ALB target group with target typeip. [S6, S8] - Ensure tasks can pull images, retrieve injected secrets, and send logs before removing NAT connectivity.
- A private endpoint design commonly needs ECR API and Docker interface endpoints, an S3 gateway endpoint for image layers, and interface endpoints for Logs and Secrets Manager.
- Enable private DNS, configure endpoint policies, and permit network paths to the endpoints.
- External services still need a suitable outbound path; ECR endpoints do not provide general internet access.
- Compare NAT and endpoint costs against actual traffic and Availability Zone design.
16. AWS deployment walkthrough
Step 1: Prepare the application
- Build the application with its supported SDK and lock the intended package versions.
- Implement authentication, ownership checks, startup validation, and real health probes.
- Confirm that
ConnectionStrings__Ordersis consumed by the database registration. - Run unit and integration tests against the intended database engine.
- Verify local container startup and the health endpoints.
- Use disposable test data, not production credentials.
Step 2: Provision the infrastructure
- Define the VPC, subnets, routing, security groups, endpoints or NAT, ECR, ECS, ALB, RDS, secrets, and monitoring using reviewed infrastructure as code.
- Prefer separate AWS accounts for production and non-production where feasible.
- Create the ACM certificate and validate the domain.
- Configure the HTTPS listener and
iptarget group on port 8080. - Set the target-group health path to
/health/readyand success code to200. - Configure realistic startup grace, health thresholds, and deregistration timing.
- Enable database encryption, backup retention, and production deletion protection.
- Create CloudWatch log groups with explicit retention before tasks start.
- These resources are prerequisites for the following CLI fragments; the fragments do not create the full infrastructure.
Step 3: Create the IAM roles
- Execution role: used by ECS for image pulls, log delivery, and task-definition secret injection. Scope additional secret and KMS permissions to the selected resources. [S5]
- Task role: used by application code for AWS SDK calls. Grant only resources and actions the application needs.
- Deployment role: used by CI to register task definitions and update the selected ECS service.
- Restrict
iam:PassRoleto the intended task and execution roles and relevant AWS service. - Use CI workload federation, such as an OIDC trust scoped to the approved repository and deployment environment, rather than long-lived access keys.
Step 4: Build and push a release image
Run these Bash commands from the solution root with Docker, AWS CLI, and an authorised AWS session. The ECR repository must already exist. The example targets Linux x86-64 explicitly.
export AWS_REGION=eu-west-2
export AWS_ACCOUNT_ID="<your-account-id>"
export ECR_REPOSITORY=orders-api
export RELEASE_TAG="<immutable-release-id>"
export IMAGE_URI="${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com/${ECR_REPOSITORY}:${RELEASE_TAG}"
aws sts get-caller-identity
aws ecr get-login-password --region "$AWS_REGION" \
| docker login --username AWS --password-stdin \
"${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com"
docker buildx build \
--platform linux/amd64 \
--tag "$IMAGE_URI" \
--load .
docker push "$IMAGE_URI"
- Replace placeholders before running commands.
- Use a release ID or full commit SHA; do not deploy mutable
latestreferences. - Resolve and record the image digest after push and use the digest in the release task definition.
- Scan the image and enforce the agreed vulnerability policy before promotion.
- Build once, then promote the same image digest through environments.
Step 5: Register a task definition
The following JSON is a template. Replace every angle-bracket placeholder; it is not directly deployable as written. The secret value is a complete PostgreSQL connection string for the restricted application user, configured with verified TLS according to the driver and RDS certificate setup.
{
"family": "orders-api",
"networkMode": "awsvpc",
"requiresCompatibilities": ["FARGATE"],
"cpu": "512",
"memory": "1024",
"runtimePlatform": {
"operatingSystemFamily": "LINUX",
"cpuArchitecture": "X86_64"
},
"executionRoleArn": "<execution-role-arn>",
"taskRoleArn": "<application-task-role-arn>",
"containerDefinitions": [
{
"name": "orders-api",
"image": "<ecr-repository-uri>@sha256:<image-digest>",
"essential": true,
"stopTimeout": 60,
"portMappings": [
{ "containerPort": 8080, "protocol": "tcp" }
],
"environment": [
{ "name": "ASPNETCORE_ENVIRONMENT", "value": "Production" },
{ "name": "ASPNETCORE_HTTP_PORTS", "value": "8080" },
{ "name": "Orders__MaxItems", "value": "100" }
],
"secrets": [
{
"name": "ConnectionStrings__Orders",
"valueFrom": "<secrets-manager-connection-string-arn>"
}
],
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-group": "/ecs/orders-api",
"awslogs-region": "eu-west-2",
"awslogs-stream-prefix": "ecs"
}
}
}
]
}
- The example starts at 0.5 vCPU and 1 GiB RAM; validate sizing with representative traffic.
- This definition relies on ALB health checks; it does not include a container health command.
- If adding container liveness, include a suitable probe executable in the image rather than assuming
curlis present. - Configure application graceful shutdown to fit inside
stopTimeout; verify behaviour with in-flight requests.
aws ecs register-task-definition \
--region "$AWS_REGION" \
--cli-input-json file://deploy/task-definition.json
- Record the returned revision ARN; do not guess the revision number.
Step 6: Run migrations and roll out the service
- Run reviewed compatible migrations using a dedicated one-off task with the same network access to RDS.
- Wait for the migration task and check its exit code; stop the release if it fails.
- For the initial service creation, bind the existing target group to container
orders-api, port8080, and select the private subnets and API security group. - Set desired count to two, disable public IP assignment, and configure health-check grace time.
- For later releases, update the existing service using the registered task-definition ARN.
- Enable the ECS rolling deployment circuit breaker with rollback. It requires an earlier completed deployment to roll back to; the first deployment has no previous working release. [S9]
export ECS_CLUSTER=production-services
export ECS_SERVICE=orders-api
export TASK_DEFINITION_ARN="<returned-task-definition-arn>"
aws ecs update-service \
--region "$AWS_REGION" \
--cluster "$ECS_CLUSTER" \
--service "$ECS_SERVICE" \
--task-definition "$TASK_DEFINITION_ARN" \
--deployment-configuration \
'minimumHealthyPercent=100,maximumPercent=200,deploymentCircuitBreaker={enable=true,rollback=true}'
aws ecs wait services-stable \
--region "$AWS_REGION" \
--cluster "$ECS_CLUSTER" \
--services "$ECS_SERVICE"
- The update command assumes the ECS service already exists and uses the rolling deployment controller.
- Keep sufficient subnet IP space, task quota, and database connection headroom for surge capacity.
- A stability waiter alone is insufficient: a successful rollback can leave the service stable on the old revision.
- Inspect service deployments and confirm the primary task definition matches the intended ARN and the rollout completed.
Step 7: Validate the release
- Confirm both intended replicas are healthy and the deployed image digest is correct.
- Verify HTTPS hostname and certificate validation.
- Test an authenticated order creation and retrieval with a controlled test account.
- Verify invalid requests, ownership isolation, and unauthorised access.
- Check logs and traces for the new deployment version.
- Watch latency, errors, resource usage, and database connections during the observation window.
- Test task replacement and assess the behaviour of a dependency timeout.
- Confirm alarms reach the responsible team.
Step 8: Roll back when needed
- If startup or health checks fail, allow the configured deployment circuit breaker to act and inspect the result.
- If business-level smoke tests fail after rollout, update the service to the recorded previous compatible task-definition ARN.
- Wait for stability, verify the active revision, and repeat smoke tests.
- Do not assume image rollback repairs corrupt data or reverses a migration.
- Use the restore or data-repair runbook when the failure affects stored data.
17. Delivery pipeline and release gates
flowchart TD
Change["Pull request"] --> Checks["Build, tests, and security checks"]
Checks --> Pass{"Checks pass?"}
Pass -->|No| Fix["Fix and review"]
Fix --> Change
Pass -->|Yes| Image["Build and scan release image"]
Image --> Stage["Deploy same digest to staging"]
Stage --> Verify{"Smoke and load checks pass?"}
Verify -->|No| Stop["Stop promotion"]
Verify -->|Yes| Release["Run compatible migration and deploy production"]
Release --> Observe{"Revision and user journey healthy?"}
Observe -->|Yes| Complete["Complete release"]
Observe -->|No| Rollback["Restore previous compatible revision"]- Run focused unit tests for pricing rules, state transitions, and validation.
- Use integration tests for constraints, transactions, query behaviour, and concurrent updates.
- Test authorisation with multiple users and tenants.
- Test duplicate and concurrent idempotency requests.
- Build and smoke-test the actual container image.
- Load-test an agreed workload, including error paths and realistic data sizes.
- Exercise deployment and rollback in staging.
- Preserve release provenance: commit, digest, task-definition ARN, migration version, and validation result.
18. Scaling, availability, and cost
Scale deliberately
- Use measured demand to choose task CPU and memory.
- Start with CPU or ALB request-count scaling where it correlates with the workload; add more suitable signals as needed.
- Define minimum and maximum task counts and scale-in cooldowns.
- Keep session and durable state outside the task.
- For cookie authentication across replicas, share and protect ASP.NET Core Data Protection keys as required.
- Check the database and downstream capacity before increasing replica limits.
- Spread tasks across Availability Zones and verify replacement behaviour.
- Multi-AZ in one region does not provide a complete regional disaster recovery strategy.
Understand the bill
- Include Fargate compute, ALB, RDS, NAT gateways or endpoints, CloudWatch, ECR, WAF where used, backups, and data transfer.
- Set budgets and anomaly alerts before production use.
- Tune log retention and trace sampling without losing incident evidence.
- Avoid exact cost commitments without region, traffic, retention, and availability requirements.
- A smaller development environment can use fewer resources; do not assume it demonstrates production availability.
19. Common failure scenarios
| Symptom | Likely investigation | First corrective direction |
|---|---|---|
| Task cannot pull image | ECR URI, execution role, DNS, NAT or endpoints | Restore registry connectivity and permissions |
| Task fails retrieving secret | Secret ARN, execution role, KMS and endpoint access | Correct scoped secret access |
| ALB reports unhealthy target | Port 8080, health path, security groups, startup time | Align task, target group, and probe configuration |
| Repeated HTTPS redirects | Forwarded scheme and redirect ownership | Correct trusted proxy configuration or edge redirects |
| Database timeouts at scale | Slow queries, pool saturation, connection limits | Inspect plans and bound concurrency |
| High latency with low CPU | Blocking calls, dependency waits, pool contention | Inspect traces and thread-pool signals |
| Duplicate orders | Missing or non-atomic idempotency handling | Enforce persisted uniqueness and replay semantics |
| Tasks fail after secret rotation | Credentials differ between running tasks and RDS | Coordinate rotation and task replacement |
| New release breaks old tasks | Incompatible schema change | Restore compatibility; use expand-and-contract |
| Service stable on wrong version | Circuit breaker rolled back | Inspect rollout state and active task-definition ARN |
20. Production readiness checklist
Application
- Service ownership, supported runtime, and upgrade policy are documented.
- Business rules and API contracts have meaningful tests.
- Authentication, ownership, tenant isolation, and validation are enforced.
- Error responses are consistent and do not leak internal information.
- I/O is asynchronous, timeouts are bounded, and cancellation is propagated.
- Duplicate requests and concurrency conflicts have defined outcomes.
Data and security
- Database constraints and indexes match the workload.
- Runtime credentials have restricted privileges.
- Secrets are externalised, redacted, and covered by a rotation procedure.
- Backup retention, restore testing, RTO, and RPO are agreed.
- Schema changes preserve the required rollback window.
- Dependencies and images meet the agreed security policy.
AWS and operations
- ALB HTTPS and certificate validation work.
- API tasks and RDS have the intended private network boundaries.
- Registry, secrets, logs, and external dependency connectivity are verified.
- Intended task count and Availability Zone placement are verified.
- Health checks distinguish process health from dependency readiness.
- Logs, metrics, traces, alarms, and runbooks are usable.
- Task shutdown, replacement, deployment, and rollback have been exercised.
- The active image digest and task-definition ARN are recorded.
- Cost budgets, retention, and capacity limits are configured.
21. Suggested hands-on exercise
- Build the Orders API with create, get, list, and cancel operations.
- Add PostgreSQL persistence, ownership filtering, and optimistic concurrency.
- Add persisted idempotency for order creation.
- Add startup validation and meaningful health checks.
- Containerise the API using a non-root runtime image.
- Deploy a staging environment using infrastructure as code.
- Deploy two Fargate tasks behind an HTTPS ALB.
- Run a controlled load test and record p95 latency, error rate, and database connections.
- Release an intentionally unhealthy image in staging and confirm rollback behaviour.
- Restore a database backup into an isolated environment and measure recovery time.
- Record the design decisions and evidence needed to pass the readiness checklist.
Completion criteria
- An authorised user can create and retrieve an order over HTTPS.
- A different user cannot retrieve that order without the required permission.
- Repeating the same idempotent create request does not create a second order.
- Stopping one task does not lose acknowledged orders.
- A failed release is detected and recovery to a known version is demonstrated.
- An operator can trace a failed request and follow a recovery runbook.
22. Realistic code examples
To complement the architectural guidance, here are two realistic code examples from our .NET 10 Orders API stack showcasing typical usage of EF Core with async operations and a complete minimal API endpoint.
Code Example 1: Creating an Order with Idempotency and Dependency Injection
This example shows a simplified service method to create a new order with idempotency key handling, cancellation support, validation, and atomic database transaction.
public class OrderService : IOrderService
{
private readonly OrdersDbContext _dbContext;
private readonly ILogger<OrderService> _logger;
public OrderService(OrdersDbContext dbContext, ILogger<OrderService> logger)
{
_dbContext = dbContext;
_logger = logger;
}
public async Task<OrderDto> CreateOrderAsync(CreateOrderRequest request, string idempotencyKey, CancellationToken cancellationToken)
{
if (string.IsNullOrWhiteSpace(idempotencyKey))
throw new ArgumentException("Idempotency key must be provided", nameof(idempotencyKey));
// Check if request with the same idempotency key exists and completed
var existingRequest = await _dbContext.IdempotentRequests
.Where(r => r.Key == idempotencyKey && r.UserId == request.UserId)
.SingleOrDefaultAsync(cancellationToken);
if (existingRequest != null)
{
if (existingRequest.Completed)
{
_logger.LogInformation("Idempotency key {Key} found - returning cached result", idempotencyKey);
return existingRequest.Response;
}
throw new InvalidOperationException("Duplicate in-progress request detected");
}
// Begin atomic transaction
await using var tx = await _dbContext.Database.BeginTransactionAsync(cancellationToken);
try
{
var order = new Order
{
UserId = request.UserId,
Items = request.Items.Select(i => new OrderItem(i.ProductId, i.Quantity)).ToList(),
Created = DateTime.UtcNow,
Status = OrderStatus.Pending
};
// Reserve idempotency key record
var idempotencyRecord = new IdempotentRequest
{
Key = idempotencyKey,
UserId = request.UserId,
StartedAt = DateTime.UtcNow,
Completed = false
};
_dbContext.IdempotentRequests.Add(idempotencyRecord);
_dbContext.Orders.Add(order);
await _dbContext.SaveChangesAsync(cancellationToken);
// Simulate event emission omitted here...
idempotencyRecord.Completed = true;
idempotencyRecord.Response = new OrderDto(order.Id, order.Status.ToString(), order.Items.Count);
await _dbContext.SaveChangesAsync(cancellationToken);
await tx.CommitAsync(cancellationToken);
return idempotencyRecord.Response;
}
catch (Exception ex)
{
_logger.LogError(ex, "Failed to create order with idempotency key {Key}", idempotencyKey);
await tx.RollbackAsync(cancellationToken);
throw;
}
}
}
Notice how idempotency records and orders are created inside a transaction to ensure atomicity, and cancellation tokens are propagated for async database calls.
Code Example 2: Minimal API Endpoint for Creating Orders
This code snippet demonstrates how to expose the create order functionality as a secured minimal API endpoint in the ASP.NET Core 10 Program.cs style.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddScoped<IOrderService, OrderService>();
builder.Services.AddDbContext<OrdersDbContext>(options =>
options.UseNpgsql(builder.Configuration.GetConnectionString("Orders")));
builder.Services.AddAuthentication("Bearer").AddJwtBearer("Bearer", options =>
{
options.Authority = "https://auth.example.com";
options.Audience = "orders-api";
});
var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapPost("/api/orders", async (
[FromBody] CreateOrderRequest request,
[FromHeader(Name = "Idempotency-Key")] string idempotencyKey,
IOrderService orderService,
CancellationToken cancellationToken) =>
{
if (string.IsNullOrEmpty(idempotencyKey))
return Results.BadRequest(new { error = "Missing Idempotency-Key header" });
try
{
var order = await orderService.CreateOrderAsync(request, idempotencyKey, cancellationToken);
return Results.Created($"/api/orders/{order.Id}", order);
}
catch (ArgumentException ex)
{
return Results.BadRequest(new { error = ex.Message });
}
catch (InvalidOperationException ex)
{
return Results.Conflict(new { error = ex.Message });
}
});
app.Run();
This minimal API endpoint uses dependency injection to resolve the service, enforces idempotency through a custom header, and returns proper HTTP codes based on business exceptions.
23. Sources and further reading
The architecture, targets, and sizing in this guide are illustrative engineering choices. The references below support platform behaviour; verify service limits, regional availability, and current configuration guidance during implementation.
- [S1] .NET support policy: https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core
- [S2] ASP.NET Core performance best practices: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/best-practices?view=aspnetcore-10.0
- [S3] ASP.NET Core proxy and load balancer configuration: https://learn.microsoft.com/en-us/aspnet/core/host-and-deploy/proxy-load-balancer?view=aspnetcore-10.0
- [S4] ASP.NET Core health checks: https://learn.microsoft.com/en-us/aspnet/core/host-and-deploy/health-checks?view=aspnetcore-10.0
- [S5] IAM roles for Amazon ECS: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-iam-role-overview.html
- [S6] ECS load balancing: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/service-load-balancing.html
- [S7] Passing sensitive data to ECS containers: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specifying-sensitive-data.html
- [S8] Fargate task networking: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/fargate-task-networking.html
- [S9] ECS deployment circuit breaker: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/deployment-circuit-breaker.html
- [S10] ALB target-group health checks and fail-open behaviour: https://docs.aws.amazon.com/elasticloadbalancing/latest/application/target-group-health-checks.html
This article introduces code that shows practical idiomatic usage of async EF Core, dependency injection, idempotency, and minimal APIs, bridging the gap between architectural concepts and runnable implementation.