EDITION v2.0.5

DOWNLOAD available at: https://aka.ms/microservicesebook

PUBLISHED BY

Microsoft Developer Division, .NET and Visual Studio product teams

A division of Microsoft Corporation

One Microsoft Way

Redmond, Washington 98052-6399

Copyright © 2018 by Microsoft Corporation

All rights reserved. No part of the contents of this book may be reproduced or transmitted in any form or by any means without the written permission of the publisher.

This book is provided “as-is” and expresses the author’s views and opinions. The views, opinions and information expressed in this book, including URL and other Internet website references, may change without notice.

Some examples depicted herein are provided for illustration only and are fictitious. No real association or connection is intended or should be inferred.

Microsoft and the trademarks listed at http://www.microsoft.com on the “Trademarks” webpage are trademarks of the Microsoft group of companies.

Mac and macOS are trademarks of Apple Inc.

The Docker whale logo is a registered trademark of Docker, Inc. Used by permission.

All other marks and logos are property of their respective owners.

Participants and reviewers:

Contents

Introduction

About this guide

Version

What this guide does not cover

Who should use this guide

How to use this guide

Related microservice and container-based reference application: eShopOnContainers

Send us your feedback!

Introduction to Containers and Docker

What is Docker?

Comparing Docker containers with virtual machines

Docker terminology

Docker containers, images, and registries

Choosing Between .NET Core and .NET Framework for Docker Containers

General guidance

When to choose .NET Core for Docker containers

Developing and deploying cross platform

Using containers for new (“green-field”) projects

Creating and deploying microservices on containers

Deploying high density in scalable systems

When to choose .NET Framework for Docker containers

Migrating existing applications directly to a Windows Server container

Using third-party .NET libraries or NuGet packages not available for .NET Core

Using.NET technologies not available for .NET Core

Using a platform or API that does not support .NET Core

Decision table: .NET frameworks to use for Docker

What OS to target with .NET containers

Official .NET Docker images

.NET Core and Docker image optimizations for development versus production

Architecting Container- and Microservice-Based Applications

Vision

Container design principles

Containerizing monolithic applications

Deploying a monolithic application as a container

Publishing a single-container-based application to Azure App Service

State and data in Docker applications

Service-oriented architecture

Microservices architecture

Data sovereignty per microservice

The relationship between microservices and the Bounded Context pattern

Logical architecture versus physical architecture

Challenges and solutions for distributed data management

Identify domain-model boundaries for each microservice

Direct client-to-microservice communication versus the API Gateway pattern

Communication in a microservice architecture

Creating, evolving, and versioning microservice APIs and contracts

Microservices addressability and the service registry

Creating composite UI based on microservices, including visual UI shape and layout generated by multiple microservices

Resiliency and high availability in microservices

Health management and diagnostics in microservices

Orchestrating microservices and multi-container applications for high scalability and availability

Using container-based orchestrators in Microsoft Azure

Using Azure Container Service

Using Azure Service Fabric

Stateless versus stateful microservices

Development Process for Docker-Based Applications

Vision

Development environment for Docker apps

Development tool choices: IDE or editor

.NET languages and frameworks for Docker containers

Development workflow for Docker apps

Workflow for developing Docker container-based applications

Simplified workflow when developing containers with Visual Studio

Using PowerShell commands in a Dockerfile to set up Windows Containers

Designing and Developing Multi-Container and Microservice-Based .NET Applications

Vision

Designing a microservice-oriented application

Application specifications

Development team context

Choosing an architecture

Benefits of a microservice-based solution

Downsides of a microservice-based solution

External versus internal architecture and design patterns

The new world: multiple architectural patterns and polyglot microservices

Creating a simple data-driven CRUD microservice

Designing a simple CRUD microservice

Implementing a simple CRUD microservice with ASP.NET Core

Generating Swagger description metadata from your ASP.NET Core Web API

Defining your multi-container application with docker-compose.yml

Using a database server running as a container

Implementing event-based communication between microservices (integration events)

Using message brokers and services buses for production systems

Integration events

The event bus

Testing ASP.NET Core services and web apps

Implement background tasks in microservices with IHostedService and the BackgroundService class

Registering hosted services in your WebHost or Host

The IHostedService interface

Implementing IHostedService with a custom hosted service class deriving from the BackgroundService base class

Tackling Business Complexity in a Microservice with DDD and CQRS Patterns

Vision

Applying simplified CQRS and DDD patterns in a microservice

Applying CQRS and CQS approaches in a DDD microservice in eShopOnContainers

CQRS and DDD patterns are not top-level architectures

Implementing reads/queries in a CQRS microservice

Using ViewModels specifically made for client apps, independent from domain model constraints

Using Dapper as a micro ORM to perform queries

Dynamic versus static ViewModels

Designing a DDD-oriented microservice

Keep the microservice context boundaries relatively small

Layers in DDD microservices

Designing a microservice domain model

The Domain Entity pattern

Implementing a microservice domain model with .NET Core

Domain model structure in a custom .NET Standard Library

Structuring aggregates in a custom .NET Standard Library

Implementing domain entities as POCO classes

Encapsulating data in the Domain Entities

Seedwork (reusable base classes and interfaces for your domain model)

Repository contracts (interfaces) in the domain model layer

Implementing value objects

Using Enumeration classes instead of C# language enum types

Designing validations in the domain model layer

Implementing validations in the domain model layer

Client-side validation (validation in the presentation layers)

Domain events: design and implementation

What is a domain event?

Domain events versus integration events

Implementing domain events

Raising domain events

Single transaction across aggregates versus eventual consistency across aggregates

The domain event dispatcher: mapping from events to event handlers

How to subscribe to domain events

How to handle domain events

Conclusions on domain events

Designing the infrastructure persistence layer

The Repository pattern

The Specification pattern

Implementing the infrastructure persistence layer with Entity Framework Core

Introduction to Entity Framework Core

Infrastructure in Entity Framework Core from a DDD perspective

Implementing custom repositories with Entity Framework Core

EF DbContext and IUnitOfWork instance lifetime in your IoC container

The repository instance lifetime in your IoC container

Table mapping

Implementing the Specification pattern

Using NoSQL databases as a persistence infrastructure

Introduction to Azure Cosmos DB and the native Cosmos DB API

Implementing .NET code targeting MongoDB and Azure Cosmos DB

Designing the microservice application layer and Web API

Using SOLID principles and Dependency Injection

Implementing the microservice application layer using the Web API

Using Dependency Injection to inject infrastructure objects into your application layer

Implementing the Command and Command Handler patterns

The Command process pipeline: how to trigger a command handler

Implementing the command process pipeline with a mediator pattern (MediatR)

Applying cross-cutting concerns when processing commands with the Behaviors in MediatR

Implementing Resilient Applications

Vision

Handling partial failure

Strategies for handling partial failure

Implementing retries with exponential backoff

Implementing the Circuit Breaker pattern

Using the ResilientHttpClient utility class from eShopOnContainers

Testing retries in eShopOnContainers

Testing the circuit breaker in eShopOnContainers

Adding a jitter strategy to the retry policy

Health monitoring

Implementing health checks in ASP.NET Core services

Using watchdogs

Health checks when using orchestrators

Advanced monitoring: visualization, analysis, and alerts

Securing .NET Microservices and Web Applications

Implementing authentication in .NET microservices and web applications

Authenticating using ASP.NET Core Identity

Authenticating using external providers

Authenticating with bearer tokens

About authorization in .NET microservices and web applications

Implementing role-based authorization

Implementing policy-based authorization

Storing application secrets safely during development

Storing secrets in environment variables

Storing secrets using the ASP.NET Core Secret Manager

Using Azure Key Vault to protect secrets at production time

Key Takeaways