.NET Architecture

https://learn.microsoft.com/en-us/dotnet/architecture
Admin
Provides documentation and guidance on how to design production-ready .NET applications, including...
Tokens:160,057
Snippets:1,138
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### docker-compose up command for test infrastructure

Source: https://learn.microsoft.com/en-us/dotnet/architecture/microservices/multi-container-microservice-net-applications/test-aspnet-core-services-web-apps

Starts the test infrastructure services by running docker-compose with both the base and override files. Must be executed from the solution test folder before running functional/integration tests.

```console
docker-compose -f docker-compose-test.yml -f docker-compose-test.override.yml up

```

--------------------------------

### Integration test for PrimeWebDefaultRequestShould using TestServer

Source: https://learn.microsoft.com/en-us/dotnet/architecture/microservices/multi-container-microservice-net-applications/test-aspnet-core-services-web-apps

This snippet shows an xUnit integration test that uses TestServer and HttpClient to verify the root endpoint returns 'Hello World!'. It instantiates the test server with WebHostBuilder and Startup, then sends a GET request to '/'.

```csharp
public class PrimeWebDefaultRequestShould
{
    private readonly TestServer _server;
    private readonly HttpClient _client;

    public PrimeWebDefaultRequestShould()
    {
        // Arrange
        _server = new TestServer(new WebHostBuilder()
           .UseStartup<Startup>());
        _client = _server.CreateClient();
    }

    [Fact]
    public async Task ReturnHelloWorld()
    {
        // Act
        var response = await _client.GetAsync("/");
        response.EnsureSuccessStatusCode();
        var responseString = await response.Content.ReadAsStringAsync();
        // Assert
        Assert.Equal("Hello World!", responseString);
    }
}
```

--------------------------------

### Basic functional test class using WebApplicationFactory

Source: https://learn.microsoft.com/en-us/dotnet/architecture/modern-web-apps-azure/test-asp-net-core-mvc-apps

Creates a test class implementing IClassFixture<WebApplicationFactory<Program>> to get an HttpClient client for functional tests. The client is created in the constructor and used in test methods.

```C#
public class BasicWebTests : IClassFixture<WebApplicationFactory<Program>>
{
  protected readonly HttpClient _client;

  public BasicWebTests(WebApplicationFactory<Program> factory)
  {
    _client = factory.CreateClient();
  }

  // write tests that use _client
}

```

--------------------------------

### Request dependencies in Startup class constructor

Source: https://learn.microsoft.com/en-us/dotnet/architecture/modern-web-apps-azure/develop-asp-net-core-mvc-apps

Injects dependencies into the Startup class constructor when the web host initializes. The requested parameters must be registered in the service container.

```csharp
public class Startup
{
    public Startup(IHostingEnvironment env)
    {
        var builder = new ConfigurationBuilder()
            .SetBasePath(env.ContentRootPath)
            .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
            .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true);
    }
}

```

--------------------------------

### Install Ocelot NuGet package

Source: https://learn.microsoft.com/en-us/dotnet/architecture/microservices/multi-container-microservice-net-applications/implement-api-gateways-with-ocelot

Installs Ocelot 18.0 and its dependencies into an ASP.NET Core project from the NuGet package repository via the Visual Studio Package Manager Console. Ocelot targets .NET 6 only and is not suitable for .NET Framework applications.

```powershell

Install-Package Ocelot

```

--------------------------------

### Configure services in Program.cs using WebApplicationBuilder

Source: https://learn.microsoft.com/en-us/dotnet/architecture/modern-web-apps-azure/develop-asp-net-core-mvc-apps

Sets up dependencies directly in Program.cs using WebApplicationBuilder before building the app. This is the default approach for .NET 6 and later.

```csharp
var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();

var app = builder.Build();

```

--------------------------------

### Define catalog-api container in docker-compose.yml

Source: https://learn.microsoft.com/en-us/dotnet/architecture/microservices/multi-container-microservice-net-applications/multi-container-applications-docker-compose

Defines the catalog-api container in a docker-compose.yml file. It uses the eshop/catalog-api image, sets the ConnectionString environment variable for Entity Framework, exposes port 80, maps it to host port 5101, adds an extra host for external SQL Server access, and depends on the sqldata container. The depends_on ensures the container starts only after sqldata starts, but retry logic is recommended because Docker only checks container-level readiness.

```yaml
  catalog-api:
    image: eshop/catalog-api
    environment:
      - ConnectionString=Server=sqldata;Initial Catalog=CatalogData;User Id=sa;Password=[PLACEHOLDER]
    expose:
      - "80"
    ports:
      - "5101:80"
    #extra hosts can be used for standalone SQL Server or services at the dev PC
    extra_hosts:
      - "CESARDLSURFBOOK:10.0.75.1"
    depends_on:
      - sqldata

```

--------------------------------

### Request dependencies in the Configure method of Startup

Source: https://learn.microsoft.com/en-us/dotnet/architecture/modern-web-apps-azure/develop-asp-net-core-mvc-apps

Specifies dependencies directly as parameters in the Configure method of the Startup class. The runtime resolves and populates these dependencies during startup.

```csharp
public void Configure(IApplicationBuilder app,
    IHostingEnvironment env,
    ILoggerFactory loggerFactory)
{

}

```

--------------------------------

### Persist an Order aggregate with Azure Cosmos DB API

Source: https://learn.microsoft.com/en-us/dotnet/architecture/microservices/microservice-ddd-cqrs-patterns/nosql-database-persistence-infrastructure

Shows a C# example of an Order aggregate being persisted with the Azure Cosmos DB API. It includes domain model code that creates an Order aggregate, updates its address, and adds an order item, followed by infrastructure code that uses the Cosmos DB client to create documents. The example highlights that the domain model usage is similar to EF Core, but the persistence API differs.

```csharp
// C# EXAMPLE OF AN ORDER AGGREGATE BEING PERSISTED WITH AZURE COSMOS DB API
// *** Domain Model Code ***
// Aggregate: Create an Order object with its child entities and/or value objects.
// Then, use AggregateRoot's methods to add the nested objects so invariants and
// logic is consistent across the nested properties (value objects and entities).

Order orderAggregate = new Order
{
    Id = "2024001",
    OrderDate = new DateTime(2005, 7, 1),
    BuyerId = "1234567",
    PurchaseOrderNumber = "PO18009186470"
}

Address address = new Address
{
    Street = "100 One Microsoft Way",
    City = "Redmond",
    State = "WA",
    Zip = "98052",
    Country = "U.S."
}

orderAggregate.UpdateAddress(address);

OrderItem orderItem1 = new OrderItem
{
    Id = 20240011,
    ProductId = "123456",
    ProductName = ".NET T-Shirt",
    UnitPrice = 25,
    Units = 2,
    Discount = 0;
};

//Using methods with domain logic within the entity. No anemic-domain model
orderAggregate.AddOrderItem(orderItem1);
// *** End of Domain Model Code ***

// *** Infrastructure Code using Cosmos DB Client API ***
Uri collectionUri = UriFactory.CreateDocumentCollectionUri(databaseName,
    collectionName);

await client.CreateDocumentAsync(collectionUri, orderAggregate);

// As your app evolves, let's say your object has a new schema. You can insert
// OrderV2 objects without any changes to the database tier.
Order2 newOrder = GetOrderV2Sample("IdForSalesOrder2");
await client.CreateDocumentAsync(collectionUri, newOrder);

```

--------------------------------

### Inject IMediator into a Web API controller constructor

Source: https://learn.microsoft.com/en-us/dotnet/architecture/microservices/microservice-ddd-cqrs-patterns/microservice-application-layer-implementation-web-api

Inject IMediator into a controller constructor to minimize dependencies for cross-cutting concerns and maintain a lean controller setup.

```csharp
public class MyMicroserviceController : Controller
{
    public MyMicroserviceController(IMediator mediator,
                                    IMyMicroserviceQueries microserviceQueries)
    {
        // ...
    }
}

```

--------------------------------

### Get data from API using GetFromJsonAsync

Source: https://learn.microsoft.com/en-us/dotnet/architecture/modern-web-apps-azure/work-with-data-in-asp-net-core-apps

Fetches a CatalogItem from an API endpoint using the configured HttpClient and the GetFromJsonAsync helper method. The URL is constructed with an id parameter.

```C#
var item = await _httpClient.GetFromJsonAsync<CatalogItem>($"catalog-items/{id}");
```

--------------------------------

### Custom WebApplicationFactory for in-memory database and seeding

Source: https://learn.microsoft.com/en-us/dotnet/architecture/modern-web-apps-azure/test-asp-net-core-mvc-apps

Override ConfigureWebHost to set the environment to 'Testing', configure in-memory databases for CatalogContext and AppIdentityDbContext, and seed test data. Use this fixture in tests to provide a pre-configured client.

```C#
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Identity;
using Microsoft.AspNetCore.Mvc.Testing;
using Microsoft.EntityFrameworkCore;
using Microsoft.eShopWeb.Infrastructure.Data;
using Microsoft.eShopWeb.Infrastructure.Identity;
using Microsoft.eShopWeb.Web;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using System;

namespace Microsoft.eShopWeb.FunctionalTests.Web;
public class WebTestFixture : WebApplicationFactory<Startup>
{
  protected override void ConfigureWebHost(IWebHostBuilder builder)
  {
    builder.UseEnvironment("Testing");

    builder.ConfigureServices(services =>
    {
      services.AddEntityFrameworkInMemoryDatabase();

      // Create a new service provider.
      var provider = services
            .AddEntityFrameworkInMemoryDatabase()
            .BuildServiceProvider();

      // Add a database context (ApplicationDbContext) using an in-memory
      // database for testing.
      services.AddDbContext<CatalogContext>(options =>
      {
        options.UseInMemoryDatabase("InMemoryDbForTesting");
        options.UseInternalServiceProvider(provider);
      });

      services.AddDbContext<AppIdentityDbContext>(options =>
      {
        options.UseInMemoryDatabase("Identity");
        options.UseInternalServiceProvider(provider);
      });

      // Build the service provider.
      var sp = services.BuildServiceProvider();

      // Create a scope to obtain a reference to the database
      // context (ApplicationDbContext).
      using (var scope = sp.CreateScope())
      {
        var scopedServices = scope.ServiceProvider;
        var db = scopedServices.GetRequiredService<CatalogContext>();
        var loggerFactory = scopedServices.GetRequiredService<ILoggerFactory>();

        var logger = scopedServices
            .GetRequiredService<ILogger<WebTestFixture>>();

        // Ensure the database is created.
        db.Database.EnsureCreated();

        try
        {
          // Seed the database with test data.
          CatalogContextSeed.SeedAsync(db, loggerFactory).Wait();

          // seed sample user data
          var userManager = scopedServices.GetRequiredService<UserManager<ApplicationUser>>();
          var roleManager = scopedServices.GetRequiredService<RoleManager<IdentityRole>>();
          AppIdentityDbContextSeed.SeedAsync(userManager, roleManager).Wait();
        }
        catch (Exception ex)
        {
          logger.LogError(ex, $"An error occurred seeding the " +
                    "database with test messages. Error: {ex.Message}");
        }
      }
    });
  }
}

```

--------------------------------

### Run catalog microservice with docker-compose run --service-ports

Source: https://learn.microsoft.com/en-us/dotnet/architecture/microservices/multi-container-microservice-net-applications/implement-api-gateways-with-ocelot

Runs the catalog-api service container and its dependencies (SQL Server and RabbitMQ) from the docker-compose files. The --service-ports flag maps the external ports for direct access.

```console
docker-compose run --service-ports catalog-api

```

--------------------------------

### Simple ASP.NET Core Dockerfile

Source: https://learn.microsoft.com/en-us/dotnet/architecture/microservices/multi-container-microservice-net-applications/multi-container-applications-docker-compose

A simple Dockerfile that copies source into a container and runs the app with dotnet run. It works but is not optimized for production because it restores and compiles at runtime, slowing container startup.

```dockerfile
FROM mcr.microsoft.com/dotnet/sdk:8.0
WORKDIR /app
ENV ASPNETCORE_URLS http://+:80
EXPOSE 80
COPY . .
RUN dotnet restore
ENTRYPOINT ["dotnet", "run"]

```

--------------------------------

### CardType : Enumeration example

Source: https://learn.microsoft.com/en-us/dotnet/architecture/microservices/microservice-ddd-cqrs-patterns/enumeration-classes-over-enum-types

Concrete enumeration class that inherits from Enumeration. Defines static instances for Amex, Visa, and MasterCard with unique IDs. Can be used as a type in any entity or value object.

```C#
public class CardType
    : Enumeration
{
    public static CardType Amex = new(1, nameof(Amex));
    public static CardType Visa = new(2, nameof(Visa));
    public static CardType MasterCard = new(3, nameof(MasterCard));

    public CardType(int id, string name)
        : base(id, name)
    {
    }
}
```

--------------------------------

### docker-compose-test.yml - Infrastructure services for testing

Source: https://learn.microsoft.com/en-us/dotnet/architecture/microservices/multi-container-microservice-net-applications/test-aspnet-core-services-web-apps

Defines the infrastructure services (Redis, RabbitMQ, SQL Server, MongoDB) required for running functional/integration tests. This file is used together with the override file to start the services.

```yaml
version: '3.4'

services:
  redis.data:
    image: redis:alpine
  rabbitmq:
    image: rabbitmq:3-management-alpine
  sqldata:
    image: mcr.microsoft.com/mssql/server:2017-latest
  nosqldata:
    image: mongo

```

--------------------------------

### Add EF Core InMemory package

Source: https://learn.microsoft.com/en-us/dotnet/architecture/modern-web-apps-azure/work-with-data-in-asp-net-core-apps

Run this .NET CLI command to add the Microsoft.EntityFrameworkCore.InMemory package for testing with an in-memory data source.

```dotnet-cli
dotnet add package Microsoft.EntityFrameworkCore.InMemory

```

--------------------------------

### Seed database in Main method of Program class

Source: https://learn.microsoft.com/en-us/dotnet/architecture/microservices/multi-container-microservice-net-applications/database-server-container

Add this code to the Main method of the Web API project's Program class to seed the database on startup. It configures logging, applies migrations for CatalogContext and IntegrationEventLogContext, and runs the host. The MigrateDbContext extension method is used to apply migrations and seed data.

```C#
public static int Main(string[] args)
{
    var configuration = GetConfiguration();

    Log.Logger = CreateSerilogLogger(configuration);

    try
    {
        Log.Information("Configuring web host ({ApplicationContext})...", AppName);
        var host = CreateHostBuilder(configuration, args);

        Log.Information("Applying migrations ({ApplicationContext})...", AppName);
        host.MigrateDbContext<CatalogContext>((context, services) =>
        {
            var env = services.GetService<IWebHostEnvironment>();
            var settings = services.GetService<IOptions<CatalogSettings>>();
            var logger = services.GetService<ILogger<CatalogContextSeed>>();

            new CatalogContextSeed()
                .SeedAsync(context, env, settings, logger)
                .Wait();
        })
        .MigrateDbContext<IntegrationEventLogContext>((_, __) => { });

        Log.Information("Starting web host ({ApplicationContext})...", AppName);
        host.Run();

        return 0;
    }
    catch (Exception ex)
    {
        Log.Fatal(ex, "Program terminated unexpectedly ({ApplicationContext})!", AppName);
        return 1;
    }
    finally
    {
        Log.CloseAndFlush();
    }
}
```

--------------------------------

### C# Integration Event Class Example

Source: https://learn.microsoft.com/en-us/dotnet/architecture/microservices/multi-container-microservice-net-applications/integration-event-based-microservice-communications

Defines a ProductPriceChangedIntegrationEvent class that inherits from IntegrationEvent. It holds product ID and old/new price properties, with a constructor to initialize them. This is a typical pattern for integration events in microservices.

```csharp
public class ProductPriceChangedIntegrationEvent : IntegrationEvent
{
    public int ProductId { get; private set; }
    public decimal NewPrice { get; private set; }
    public decimal OldPrice { get; private set; }

    public ProductPriceChangedIntegrationEvent(int productId, decimal newPrice,
        decimal oldPrice)
    {
        ProductId = productId;
        NewPrice = newPrice;
        OldPrice = oldPrice;
    }
}
```
Tokens:
Raw