Free eBook/Guide on ‘.NET Microservices – Architecture for Containerized .NET Applications’

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:

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

Also available as online content at

In addition to the .PDF eBook, it is also available as online version (online web pages) at, 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: 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.

Comments (43)

  1. Kathleen Dollard says:

    link above book pic is broken

    1. Which one? I tested this, and it is working for me:

  2. blisslight says:

    Is this book available in .mobi or .epub format? Pdf isn’t eBook reader friendly.
    Many thanks. Great content!

  3. Rahul Garg says:

    Really awesome content. Anyone can have a wholesome idea about Microservices, containers and domain driven design. Tons of thanks for all hard works.

  4. Prakash says:

    Very good book. Thanks for sharing this.

    1. Thanks for the feedback! 🙂

  5. Chandrakant Patil says:

    Very well outlined. This will help to decide direction to move. Thanks for sharing with us.

    1. Thank you! I’m glad it can help you guys! 🙂

  6. Vikas says:

    Awesome.. Here is the future.
    Thanks for sharing with us..

  7. Really good book and an excellent introduction to both Microsoft Services design / architecture, docker and .net core.

    The architecture piece on its own is worth a read and allows a lot of questions to be asked during the design phase before development starts.

    1. Thanks for the feedback! 🙂

  8. Yitro Kurniawan says:

    Two thumbs up. Thanks for sharing.

  9. Mike Parker says:

    I just wanted to say this is a fantastic (and free!) book. Thank you so much for putting all this together.

    I would be interested to hear your take on where serverless computing / function hosting fits in with the container model, and whether we’ll all be moving off microservices onto function hosting in the future? 🙂

    1. Thanks for the feedback! 🙂
      In the long term, everything will be moving to serverless approaches that could be containerized underneath, as well.
      As of today, I’d use Azure Functions (serverless) for punctual microservices where you might require very high unexpected usage peaks, even triggered by events coming from Azure’s infrastructure.
      However, when creating a complex microservice-oriented application with tens of types of services, grouping cohesive services within logical BOUNDED CONTEXTS (business microservice), etc. that is doable with an orchestrator-based approach. I see it very challenging if you’d want to use just serverless/Functions for a very complex and large microservice-based application. That’s my personal opinion.

      So, as of today, I see serverless/Azure Functions complementary to more structured approaches like the orchestrator clusters (Service Fabric, Kubernetes, Swarm, DC/OS, CloudFoundry, etc.) so you can extend your large microservice application running on an orchestrator/cluster with Azure Functions, for certain scenarios like explained here:

  10. Alex says:

    Awesome work! Thanks to share it with us.

    1. Thanks for the feedback! 🙂

  11. Great job, thank you for giving us an amazing conference in Madrid.

    Has been inspirational to rebuild the NLayer Architecture with dot net core preview 2, I’ve just uploaded the code in my repository:

    What do you think about this retro project?


  12. Thanks for the good article!

    1. Thanks for the feedback! 🙂

  13. Bassam says:

    Thanks for sharing
    But the Link is not working

    1. @Bassam I just tested the link, from my cellphone, and it is working for me. This is the link for the eBook, in any case:

      1. Bassam says:

        Many Thanks 🙂

  14. durlav karki says:

    how can i got it??

    1. The link is in the blog.
      Here’s the link, in any case:

  15. Herber says:

    Any chance to have it in .mobi / .awz format? I’d like to load it in my kindle

    1. We don’t have it in that format. It’ll require copy/edit work as it is not as simple as convert to a different format.
      We might make it, but it’ll get some time until then.

    2. Brian Russell says:

      +1 request for mobi/awz/epub format. PDFs are terrible on eReaders.

      1. Sorry, for now it’ll be just a .PDF for printing or PC.

    3. Alex O. says:

      You can email PDF file as attachment to your Kindle’s free email address with the subject line “convert” and Amazon’s whispersync service will automatically convert this PDF to Kindle’s native .azw format. You will just need to download that book from Amazon’s cloud to your Kindle device. I do this all the time with my PDF files and it works flawlessly about 95% of the time (sometimes the really big or complex PDF documents may not convert properly).
      See this link for explanation:

  16. Leszek says:

    Looks very good. Thank you very much,
    Szczesc Boze!

  17. Klas says:

    Looks really nice. The second GitHub link points to the PDF though.

    1. Thanks for the feedback!
      Link updated, btw.

  18. Jeff says:

    Nice. Is this available for purchase as a physical book? If not, does Microsoft permit us to print it out for individual use (or pay to have a print shop to do so on our behalf)?

    1. @Jeff Hey! Thanks for the positive feedback! – So, it is still not available as a physical book. We’re in conversations with MS PRESS and other publishers and it might be a physical book in the future.
      About printing it, sure, you can print it out for your personal/work use or usage at your company.
      What’s not allowed is to print it massively (tens, hundreds) without our permission, like for an event or course (might be granted, if asked to us, though, as long as no one is charging for the book itself in a course/event, for instance).
      Finally, it is not allowed to print it as a physical book for selling it, logically.

  19. michael says:

    any chance for an epub? pdf files are terrible for reading on smaller screens, where i do most of mine.

    1. Looking into that! Cannot promise about it, but I’ll try! 🙂

  20. Alek says:


  21. Alek says:

    Where can I get this guide?


    1. Download link is within the provided GitHub link. Also updated direct link above the cover. This is the link for download, in any case:

      1. Jatin says:

        The link above the cover is not hyperlinked, so it is not clickable. Clicking on the cover navigates to a bigger png image of the cover.

        1. Thanks for the heads-up. Links fixed! 🙂

Skip to main content