No Description

Cesar De la Torre 338d911621 Updated the to use the latest ASPNETCORE BUILD/SDK Image (2.0.2) and just 'dot net publish' against the whole .sln 6 months ago
Components 5f4d42520d Add GeolocatorPlugin-1.0.3 to IOS and Windows project 11 months ago
ServiceFabric 780123813d Added placeholder for eshop image tags in SF config manifests 6 months ago
cli-linux 6c5bdda2f5 Improve (removed dotnet restore (doing with publish now) and set quiet on verbosity in order to reduce issues with System.Console.dll on build container). Remove unnecesary namespace on Identity.Api startup.cs 8 months ago
cli-mac 66de8cd43c Update project list in mac build script 6 months ago
cli-windows bf40b4be83 Increased the port range for firewall rules 6 months ago
deploy 54db2cad98 Update 7 months ago
docs bca490fe14 Added latest Xamarin eBook. 9 months ago
img d7e3dc6fac Updated SF Windows manifests 7 months ago
k8s 7861d5df87 Updated settings for k8s / SF to enable Load testing mode 6 months ago
readme 384895add3 Doc updates 9 months ago
src 8c810ad8a1 Minor changes in SwaggerEndpoints for each microservice. 6 months ago
test 7861d5df87 Updated settings for k8s / SF to enable Load testing mode 6 months ago
vsts-docs 8683efcaf9 Merge branch 'dev' 9 months ago
.env c51c101f90 Updated Load Tests 6 months ago
.gitattributes 6b2a4ed4d4 Treat *.pfx as binary so CRLF will not change it 8 months ago
.gitignore 76dcd66c73 we don't need schema files for k8 in a repo. 8 months ago 59571104de Add 1 year ago
LICENSE 481709e3f7 Update LICENSE 1 year ago
Local.testsettings 6a0001b9c6 Add new LoadTest project, add new Catalog integration test and add new webMVC load test 10 months ago
NuGet.config 4aafa813f5 a couple of quick changes to allow building in the 1 year ago eb80502bcb Update 7 months ago 210c42b7de doc updated to reflect netcore2 moving 8 months ago
docker-compose-external.override.yml e8c8678082 Changed to new GA SQL Server container Image tag and parameters 7 months ago
docker-compose-external.yml cc4325cee5 Updated all docker-compose files version from 2.1 to 3 7 months ago cc4325cee5 Updated all docker-compose files version from 2.1 to 3 7 months ago
docker-compose-windows.yml cc4325cee5 Updated all docker-compose files version from 2.1 to 3 7 months ago 338d911621 Updated the to use the latest ASPNETCORE BUILD/SDK Image (2.0.2) and just 'dot net publish' against the whole .sln 6 months ago
docker-compose.dcproj 2ca72e8f1d Set Linux as by default target OS for Docker's project in VS2017 7 months ago
docker-compose.nobuild.yml cc4325cee5 Updated all docker-compose files version from 2.1 to 3 7 months ago cc4325cee5 Updated all docker-compose files version from 2.1 to 3 7 months ago
docker-compose.override.yml 779c7c2901 Refactoring in docker-compose files 6 months ago dbc80a3596 Updates in 6 months ago
docker-compose.yml 779c7c2901 Refactoring in docker-compose files 6 months ago
eShopOnContainers-Android.sln ecef3bed68 Set same vs version for all the solutions 8 months ago
eShopOnContainers-AzureFunctions.sln ecef3bed68 Set same vs version for all the solutions 8 months ago
eShopOnContainers-MobileApps.sln e3f9817745 Minor solution changes for latest VS2017 release. 8 months ago
eShopOnContainers-ServicesAndWebApps.sln c51c101f90 Updated Load Tests 6 months ago
eShopOnContainers-iOS.sln ecef3bed68 Set same vs version for all the solutions 8 months ago
eShopOnContainers.sln d8b374ac4a Create DesignTimeFactories for context used on startup with dependencies 8 months ago
global.json 6515a3b58f update sdk to 2.0.2 8 months ago
hosts b46665955c Changes to README and other minor changes after testing 1 year ago

eShopOnContainers - Microservices Architecture and Containers based Reference Application (BETA state - Visual Studio 2017 and CLI environments compatible)

Sample .NET Core reference application, powered by Microsoft, based on a simplified microservices architecture and Docker containers.

Note Visual Studio 2017 version required: This is important as of Oct. 11th 2017. For working with Docker and docker-compose files (needed with eShopOnContainers), do not migrate to VS 2017 15.4 as it has a bug when using TAGs in the docker-compose files. Please, either use VS 2017 15.35 or VS 2017 15.5 Preview 1 (bug is fixed here) or later. VS Preview installs next to your stable Visual Studio IDE, allowing you to use either independently. Download of Preview here:

Note for Pull Requests: We accept pull request from the community. When doing it, please do it onto the DEV branch which is the consolidated work-in-progress branch. Do not request it onto Master, if possible.

Moving to .NET Core 2.0 "wave"

NOTE: During August/September 2017 we'll be moving the solution to .NET Core "wave". Not just compilation but also new recommended code in EF Core 2.0, ASP.NET Core 2.0, and other new related versions.

PLEASE Read our branch guide to know about our branching policy


IMPORTANT: The current state of this sample application is BETA, consider it version 0.1, a foundational version. Therefore, many areas could be improved and change significantly while refactoring current code and implementing new features. Feedback with improvements and pull requests from the community will be highly appreciated and accepted.

This reference application proposes a simplified microservice oriented architecture implementation to introduce technologies like .NET Core with Docker containers through a comprehensive application. The chosen domain is an eShop/eCommerce but simply because it is a well-know domain by most people/developers. However, this sample application should not be considered as an "eCommerce reference model", at all. The implemented business domain might not be ideal from an eCommerce business point of view. It is neither trying to solve all the problems in a large, scalable and mission-critical distributed system. It is just a bootstrap for developers to easily get started in the world of Docker containers and microservices with .NET Core.

For example, the next step (still not covered in eShopOnContainers) after understanding Docker containers and microservices development with .NET Core, is to select a microservice cluster/orchestrator like Docker Swarm, Kubernetes or DC/OS (in Azure Container Service) or Azure Service Fabric which in most of the cases will require additional partial changes to your application's configuration (although the present architecture should work on most orchestrators with small changes). Additional steps would be to move your databases to HA cloud services, or to implement your EventBus with Azure Service Bus or any other production ready Service Bus in the market.

In the future we might fork this project and make multiple versions targeting specific microservice cluster/orchestrators plus using additional cloud infrastructure.

Read the planned Roadmap and Milestones for future releases of eShopOnContainers within the Wiki for further info about possible new implementations and provide feedback at the ISSUES section if you'd like to see any specific scenario implemented or improved. Also, feel free to discuss on any current issue.

Architecture overview: This reference application is cross-platform at the server and client side, thanks to .NET Core services capable of running on Linux or Windows containers depending on your Docker host, and to Xamarin for mobile apps running on Android, iOS or Windows/UWP plus any browser for the client web apps. The architecture proposes a simplified microservice oriented architecture implementation with multiple autonomous microservices (each one owning its own data/db) and implementing different approaches within each microservice (simple CRUD vs. DDD/CQRS patterns) using Http as the communication protocol between the client apps and the microservices and supports asynchronous communication for data updates propagation across multiple services based on Integration Events and an Event Bus (a light message broker, to choose between RabbitMQ or Azure Service Bus, underneath) plus other features defined at the roadmap.

Important Note on API Gateways and published APIs

Note that the previous architecture diagram shows how you deploy eShopOnContainers in a local Docker development machine. For a production-ready architecture we recommend to keep evolving your architecture with additional features like API Gateways based on AzureAPI Management or any other approach for API Gateways explained in the related documentation/eBook, so you can filter APIs and apply security in a single tier while hiding/securing the internal microservices to the client apps or outside consumers.

The sample code in this repo is NOT making use of Azure API Management in order to be able to provide an "F5 experience" in Visual Studio (or CLI) of the sample with no up-front dependencies in Azure. But you should evaluate API Gateways alternatives when building for production.

The microservices are different in type, meaning different internal architecture pattern approaches depending on its purpose, as shown in the image below.

Important Note on Database Servers/Containers

In this solution's current configuration for a development environment, the SQL databases are automatically deployed with sample data into a single SQL Server for Linux container (a single shared Docker container for SQL databases) so the whole solution can be up and running without any dependency to any cloud or specific server. Each database could also be deployed as a single Docker container, but then you'd need more than 8GB of RAM assigned to Docker in your development machine in order to be able to run 3 SQL Server Docker containers in your Docker Linux host in "Docker for Windows" or "Docker for Mac" development environments.

A similar case is defined in regard to Redis cache running as a container for the development environment. Or a No-SQL database (MongoDB) running as a container.

However, in a real production environment it is recommended to have your databases (SQL Server, Redis, and the NO-SQL database, in this case) in HA (High Available) services like Azure SQL Database, Redis as a service and Azure CosmosDB instead the MongoDB container (as both systems share the same access protocol). If you want to change to a production configuration, you'll just need to change the connection strings once you have set up the servers in a HA cloud or on-premises.

Related documentation and guidance

While developing this reference application, we've been creating a reference Guide/eBook focusing on architecting and developing containerized and microservice based .NET Applications (download link available below) which explains in detail how to develop this kind of architectural style (microservices, Docker containers, Domain-Driven Design for certain microservices) plus other simpler architectural styles, like monolithic apps that can also live as Docker containers.

There are also additional eBooks focusing on Containers/Docker lifecycle (DevOps, CI/CD, etc.) with Microsoft Tools, already published plus an additional eBook focusing on Enterprise Apps Patterns with Xamarin.Forms. You can download them and start reviewing these Guides/eBooks here:

Architecting & Developing Containers Lifecycle & CI/CD App patterns with Xamarin.Forms
Download (First Edition) Download (First Edition) Download (First Edition)

Send feedback to

However, we encourage to download and review the "Architecting & Developing eBook" because the architectural styles and architectural patterns and technologies explained in the guidance are using this reference application when explaining many pattern implementations, so you'll understand much better the context, design and decisions taken in the current architecture and internal designs.

Overview of the application code

In this repo you can find a sample reference application that will help you to understand how to implement a microservice architecture based application using .NET Core and Docker.

The example business domain or scenario is based on an eShop or eCommerce which is implemented as a multi-container application. Each container is a microservice deployment (like the basket-microservice, catalog-microservice, ordering-microservice and the identity-microservice) which are developed using ASP.NET Core running on .NET Core so they can run either on Linux Containers and Windows Containers. The screenshot below shows the VS Solution structure for those microservices/containers and client apps.

  • (Recommended when getting started) Open eShopOnContainers-ServicesAndWebApps.sln for a solution containing just the server-side projects related to the microservices and web applications.
  • Open eShopOnContainers-MobileApps.sln for a solution containing just the client mobile app projects (Xamarin mobile apps only). It works independently based on mocks, too.
  • Open eShopOnContainers.sln for a solution containing all the projects (All client apps and services).

Finally, those microservices are consumed by multiple client web and mobile apps, as described below.
MVC Application (ASP.NET Core): It's an MVC application where you can find interesting scenarios on how to consume HTTP-based microservices from C# running in the server side, as it is a typical ASP.NET Core MVC application. Since it is a server-side application, access to other containers/microservices is done within the internal Docker Host network with its internal name resolution.
SPA (Single Page Application): Providing similar "eShop business functionality" but developed with Angular 2, Typescript and slightly using ASP.NET Core MVC. This is another approach for client web applications to be used when you want to have a more modern client behavior which is not behaving with the typical browser round-trip on every action but behaving like a Single-Page-Application which is more similar to a desktop app usage experience. The consumption of the HTTP-based microservices is done from TypeScript/JavaScript in the client browser, so the client calls to the microservices come from out of the Docker Host internal network (Like from your network or even from the Internet).
Xamarin Mobile App (For iOS, Android and Windows/UWP): It is a client mobile app supporting the most common mobile OS platforms (iOS, Android and Windows/UWP). In this case, the consumption of the microservices is done from C# but running on the client devices, so out of the Docker Host internal network (Like from your network or even the Internet).

Setting up your development environment for eShopOnContainers

Visual Studio 2017 and Windows based

This is the more straightforward way to get started:

CLI and Windows based

For those who prefer the CLI on Windows, using dotnet CLI, docker CLI and VS Code for Windows:,-Docker-CLI-and-VS-Code)

CLI and Mac based

For those who prefer the CLI on a Mac, using dotnet CLI, docker CLI and VS Code for Mac (Instructions still TBD, but similar to Windows CLI):,-VS-Code-and-CLI-environment--(dotnet-CLI,-Docker-CLI-and-VS-Code)

Orchestrators: Kubernetes and Service Fabric

See at the Wiki the posts on setup/instructions about how to deploy to Kubernetes or Service Fabric in Azure (although you could also deploy to any other cloud or on-premises).

Sending feedback and pull requests

As mentioned, we'd appreciate your feedback, improvements and ideas. You can create new issues at the issues section, do pull requests and/or send emails to


[QUESTION] Answer +1 if the solution is working for you (Through VS2017 or CLI environment):