The microservices architecture is emerging as an important approach for distributed mission-critical applications. In a microservice-based architecture, the application is built on a collection of services that can be developed, tested, deployed, and versioned independently. In addition, enterprises are increasingly realizing cost savings, solving deployment problems, and improving DevOps and production operations by using containers. Microsoft has been releasing container innovations for Windows and Linux by creating products like Azure Container Service and Azure Service Fabric, and by partnering with industry leaders like Docker, Mesosphere, and Kubernetes. These products deliver container solutions that help companies build and deploy applications at cloud speed and scale, whatever their choice of platform or tools. Docker Containers are becoming the de facto standard in the container industry, supported by the most significant vendors in the Windows and Linux ecosystems. (Microsoft is one of the main cloud vendors supporting Docker.) In the future, Docker Containers will probably be ubiquitous in any datacenter in the cloud or on-premises.

Introducing the ‘.NET Microservices – Architecture for Containerized .NET Applications’ Guide/eBook

Today, coinciding with /BUILD 2017, we’re excited to introduce you a first edition of an eBook that offers guidance on those mentioned subjects and from our perspective from the .NET team: .NET Microservices: Architecture for Containerized .NET Applications.

Available as free .PDF download: http://aka.ms/MicroservicesEbook

***[NEW UPDATE – June 2017] ***

Also available as online content at docs.microsoft.com: https://aka.ms/microservices-guide-online-msft-docs

In addition to the .PDF eBook, it is also available as online version (online web pages) at docs.microsoft.com, so you can directly go to specific pages of the content, as a reference. The best thing about this approach is that you can comment on every page and since it is based on GitHub, you can even submit Pull Requests with content updates that we can approve and merge.

******************************

This guide is an introduction to developing microservices-based applications and managing them using containers. It discusses architectural design and implementation approaches using .NET Core and Docker containers. To make it easier to get started with containers and microservices, the guide focuses on a reference containerized and microservice-based application that you can explore. The sample application is available at the eShopOnContainers GitHub repo. This guide provides foundational development and architectural guidance primarily at a development environment level with a focus on two main technologies: Docker and .NET Core. Our intention is that you read this guide when thinking about your application design without focusing on the infrastructure (cloud or on-premises) of your production environment. You will make decisions about your infrastructure later, when you create your production-ready applications. Therefore, this guide is intended to be infrastructure agnostic and more development-environment-centric.

Main topics covered by this guide

–    Introduction to Containers and Docker

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

–    Architecting Container- and Microservice-Based Applications

–    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

–    Identifying domain-model boundaries for each microservice

–    Communication between microservices

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

–    Development Process for Docker-Based Applications

–    Deploying Single-Container-Based .NET Core Web Applications on Linux or Windows Nano Server Hosts

–    Migrating Legacy Monolithic .NET Framework Applications to Windows Containers

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

–    Benefits of a microservice-based solution

–    Downsides of a microservice-based solution

–    The new world: multiple architectural patterns and polyglot microservices

–    Implementing a simple CRUD microservice with ASP.NET Core

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

–    Implementing event-based communication between microservices (integration events): The event bus

–    Tackling Business Complexity in a Microservice with DDD and CQRS Patterns

–    Designing a microservice domain model based on Aggregates

–    Domain events: design and implementation

–    Implementing the infrastructure persistence layer with Entity Framework Core

–    Designing the microservice application layer and Web API

–    Using SOLID principles and Dependency Injection

–    Implementing the Command and Command Handler patterns

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

–    Implementing Resilient Applications

–    Implementing retries with exponential backoff

–    Implementing the Circuit Breaker pattern

–    Implementing health checks in ASP.NET Core services

–    Securing .NET Microservices and Web Applications

Who should use this guide

We wrote this guide for developers and solution architects who are new to Docker-based application development and to microservices-based architecture. This guide is for you if you want to learn how to architect, design, and implement proof-of-concept applications with Microsoft development technologies (with special focus on .NET Core) and with Docker containers. You will also find this guide useful if you are a technical decision maker, such as an enterprise architect, who wants an architecture and technology overview before you decide on what approach to select for new and modern distributed applications.

How to use this guide

The first part of this guide introduces Docker containers, discusses how to choose between .NET Core and the .NET Framework as a development framework, and provides an overview of microservices. This content is for architects and technical decision makers who want an overview but who do not need to focus on code implementation details. The second part of the guide starts with the “Development process for Docker based applications” section. It focuses on development and microservice patterns for implementing applications using .NET Core and Docker. This section will be of most interest to developers and architects who want to focus on code and on patterns and implementation details.

Related microservice and container-based reference application: eShopOnContainers

The eShopOnContainers application (still in BETA state) is a sample reference app for .NET Core and microservices that is designed to be deployed using Docker containers. The application consists of multiple subsystems, including several e-store UI front ends (a Web app and a native mobile app). It also includes the back-end microservices and containers for all required server-side operations. This microservice and container-based application source code is open source and available at the  eShopOnContainers GitHub repo. The following diagram shows a high-level overview of the architecture of the sample application:

 

The sample application includes the following backend services:

•    An identity microservice, which uses ASP.NET Core Identity and IdentityServer.

•    A catalog microservice, which is a data-driven, create, read, update, delete (CRUD) service that consumes an SQL Server database using EntityFramework Core.

•    An ordering microservice, which is a domain-driven service that implements domain driven design patterns.

•    A basket microservice, which is a data-driven CRUD service that uses Redis Cache.

•    An MVC watchdogs web app to query and show info from the Health Checks (not shown in the above architecture diagram).

These backend services are implemented as microservices using ASP.NET Web API, and are deployed as unique containers within a single Docker host. Client apps then communicate with the backend services through a Representational State Transfer (REST) web interface. The microservices are also communicated between them with asynchronous messages based on an Event Bus currently implemented on top of RabbitMQ, but the event bus could also be based on any other broker or service bus like Azure Service Bus, NServiceBus, MassTransit, etc. In addition, the sample application ships with three client apps:

•    An MVC application developed with ASP.NET Core.

•    A Single Page Application (SPA) developed with Angular 2 and Typescript.

•    A cross-platform mobile app developed with Xamarin.Forms.

Key takeaways

As a summary and key takeaways, the following are the most important conclusions from this guide.

Benefits of using containers. Container-based solutions provide the important benefit of cost savings because containers are a solution to deployment problems caused by the lack of dependencies in production environments. Containers significantly improve DevOps and production operations.

Containers will be ubiquitous. Docker-based containers are becoming the de facto standard in the container industry, supported by the most significant vendors in the Windows and Linux ecosystems. This includes Microsoft, Amazon AWS, Google, and IBM. In the near future, Docker will probably be ubiquitous in both cloud and on-premises datacenters.

Containers as unit of deployment. A Docker container is becoming the standard unit of deployment for any server-based application or service.

Microservices. The microservices architecture is becoming the preferred approach for distributed and large or complex mission-critical applications based on multiple independent subsystems in the form of autonomous services. In a microservice-based architecture, the application is built as a collection of services that can be developed, tested, versioned, deployed, and scaled independently; this can include any related autonomous database.

Domain-driven design and SOA. The microservices architecture patterns derive from service-oriented architecture (SOA) and domain-driven design (DDD). When you design and develop microservices for environments with evolving business rules shaping a particular domain, it is important to take into account DDD approaches and patterns.

Microservices challenges. Microservices offer many powerful capabilities, like independent deployment, strong subsystem boundaries, and technology diversity. However, they also raise many new challenges related to distributed application development, such as fragmented and independent data models, resilient communication between microservices, eventual consistency, and operational complexity that results from aggregating logging and monitoring information from multiple microservices. These aspects introduce a higher level of complexity than a traditional monolithic application. As a result, only specific scenarios are suitable for microservice-based applications. These include large and complex applications with multiple evolving subsystems; in these cases, it is worth investing in a more complex software architecture, because it will provide better long-term agility and application maintenance.

Containers for any application. Containers are convenient for microservices, but are not exclusive for them. Containers can also be used with monolithic applications, including legacy applications based on the traditional .NET Framework and modernized through Windows Containers. The benefits of using Docker, such as solving many deployment-to-production issues and providing state of the art Dev and Test environments, apply to many different types of applications.

CLI versus IDE. With Microsoft tools, you can develop containerized .NET applications using your preferred approach. You can develop with a CLI and an editor-based environment by using the Docker CLI and Visual Studio Code. Or you can use an IDE-focused approach with Visual Studio and its unique features for Docker, such as like being able to debug multi-container applications.

Resilient cloud applications. In cloud-based systems and distributed systems in general, there is always the risk of partial failure. Since clients and services are separate processes (containers), a service might not be able to respond in a timely way to a client’s request. For example, a service might be down because of a partial failure or for maintenance; the service might be overloaded and responding extremely slowly to requests; or it might simply not be accessible for a short time because of network issues. Therefore, a cloud-based application must embrace those failures and have a strategy in place to respond to those failures. These strategies can include retry policies (resending messages or retrying requests) and implementing circuit-breaker patterns to avoid exponential load of repeated requests. Basically, cloud-based applications must have resilient mechanisms—either custom ones, or ones based on cloud infrastructure, such as high-level frameworks from orchestrators or service buses.

Orchestrators. Container-based orchestrators like the ones provided in Azure Container Service (Kubernetes, Mesos DC/OS, and Docker Swarm) and Azure Service Fabric are indispensable for any production-ready microservice-based and for any multi-container application with significant complexity, scalability needs, and constant evolution. This guide has introduced orchestrators and their role in microservice-based and container-based solutions. If your application needs are moving you toward complex containerized apps, you will find it useful to seek out additional resources for learning more about orchestrators.

Other Guides

Other related guides worth reading include:

– Containerized Docker Application Lifecycle with Microsoft Platform and Tools

– Architecting and Developing Modern Web Applications with ASP.NET Core and Azure

– Enterprise Application Patterns using Xamarin.Forms

– Microsoft Platform and Tools for Mobile App Development.

Send us your feedback!

We wrote this guide to help you understand the architecture of containerized applications and microservices in .NET. This guide and its related application will be evolving, so we welcome your feedback in order to improve it! If you have comments about how this guide can be improved, please send them to: mailto:cesardl@microsoft.com Also, feel free to post your comments within this blog post, of course. We’ll appreciate your feedback and ideas on how to improve this content.