Tutorial with samples about how to setup .Net Core with Docker
MIT License
This example shows how to:
Feel free to create an issue if you have any questions or request for more explanation or samples. I also take Pull Requests!
If this repository helped you - I'd be more than happy if you join the group of my official supporters at:
We will use default Visual Studio template for the WebApi project:
File => New => Project
Templates => Visual C# => .Net Core
an ASP.NET Core Web Application
Web Api
template. Unselect "Enable Docker Support" and leave Authentication settings as they are (so no authentication).dotnet restore
command. It will get all needed NuGet packages for your application.F5
to run it.http://localhost:{port}/api/values
and ["value1","value2"]
.You can check the detailed changes in pull request
Most of our applications needs to have the database. We'll use Entity Framework and MSSQL server in this example.
Package Manger Console
run Install-Package Microsoft.EntityFrameworkCore.SqlServer
and Install-Package Microsoft.EntityFrameworkCore.Tools
. This will add Nuget Packages nessesary for the MSSQL server databasse usage.ValuesController
and add new TasksController.async
usage - it' much better for the performance perspective to use async/await
in the api. What's crucial is that you cannot leave the async statement using database not awaited, because it may end up with your db connection not disposed properly,
returning proper Http Status Codes for the Api endpoints:
OK
- will return 200
,NotFound
- will return 404
result,Forbid
- will return 403
status,Good explanation of http status codes can be found here
few examples of the new usefull C# 6 syntax
You should also update your launchSettings.json
to redirect you by default to the /tasks/
instead of the /values/
route.
If you run now you're application then you'll get following exception:
System.Data.SqlClient.SqlException: 'Cannot open database "NetCoreWithDocker" requested by the login. The login failed.
It basically means that it cannot login, because in fact there is no database that Entity Framework can login to. How to setup it? By using build in Migrations mechanism.
It's needed to setup the migrations (event the initial one), that will create database with object<=>relation mapping defined in the TasksDbContext. To do that open Package Manager Console
and run: `Add-Migration InitialCreate](). This will automatically freeze the current model definiton in Current Model Snapshot and the define Initial Migration.
Now to create/update our database it's needed to run Update-Database
from Package Manager Console
.
You should now be able to run the application. If you did all of the steps properly then you should see browser page with http://localhost:{port}/api/values
and []
. That means that our TasksController returned empty list of tasks - because our database is currently empty.
Entity Framework also provides mechanism to add initial data (it's usefull for the eg. dictionaries or test data setup). Unfortunatelly it's needed to provide some boilerplate code for that. We need to do following steps:
12.1. Run Add-Migration InitialSeed
in the Package Manager Console
- this will generate empty migration.
12.2. Then we need to prepare our TasksDbContext to be also created not only from the depenedency injection. To do that we should create TasksDbContextFactory. This class will be used for the database configuration (eg. connection string) injection. It needs to implement IDbContextFactory<TasksDbContext>
and unfortunatelly mimic some of the Startup Configuration reading functionality. Full implementation can be seen here.
12.3. Now we can use our factory class in our Initial Seed migration. In Up
method we're defining our insertion, in Down
method we're cleaning data (it' being run if something went wrong).
12.4. You need also to mark appsettings.Development.json
as being coppied to ouput directory. To do that we need to add new settings in the NetCoreWithDocker.csproj.
Now you should be able to run Update-Database
from Package Manager Console
to apply seeding, start application by clicking F5
and see the results in the browser (eg. [{"id":1,"description":"Do what you have to do"},{"id":2,"description":"Really urgent task"},{"id":3,"description":"This one has really low priority"}]
)
You can check the detailed changes in pull request
docker
in the root of our project. We will place there all of the docker configuration. Create also subfolder called mssql
.docker
folder let's create docker-compose.yml - this will be our main configuration file. Docker configs are written in yaml syntax.version: "3"
services:
mssql:
image: "microsoft/mssql-server-linux"
env_file:
- mssql/variables.env
ports:
- "1433:1433"
It contains following sections:
services
- list of services (docker containers) that will be run,mssql
- name of a service. It is provided by us, it could be named even xyz
,env_file
- reference to the files with environment needed for our service setup,ports
- mapping of our port. This configuration mean that 1433
port from docker container will be mapped to our localhost 1433
port. Without that configuration port will be by default not accessible. It's also usefull if our local port is in use and we'd like to have different port assigned.mssql
folder and place there:
ACCEPT_EULA=Y
SA_PASSWORD=!QAZxsw2#EDC
ACCEPT_EULA
- is needed for accepting MSSQL Server licence terms,SA_PASSWORD
- sa
database user passwordCMD
from docker
directory and run docker-compose up
. This will download MSSQL server image from Docker Hub. It will also automatically start the server.SQL Server is now ready for client connections.
in the CMD
window.Update-Database
from Package Manager Console
and we can run our application by clicking F5
!docker-compose up
- as described above, gets images and starts containers,docker-compose kill
- kills running dockers,docker-compose pull
- pulls latest docker images,docker system prune
- clean up all containers that were get through pull
and up
commands. Useful for cleaning the disk space and making sure that you have the assumed version of docker (docker system prune
+ docker-compose up
), or just resetting state of the docker container,docker ps
- lists all running docker containers.You can check the detailed changes in pull request
I gathered and generalized all of practices used in this tutorial/samples in Nuget Packages of maintained by me GoldenEye Framework. it provides set of base and bootstrap classes that helps you to reduce boilerplate code and help you focus on writing business code. See more in:
dotnet add package GoldenEye.Backend.Core
dotnet add package GoldenEye.Backend.Core.EntityFramework
dotnet add package GoldenEye.Backend.Core.WebApi
The simplest way to start is installing the project template by running
dotnet -i GoldenEye.WebApi.Template.SimpleDDD
and then creating new project based on it:
dotnet new SimpleDDD -n NameOfYourProject
Feel free to create an issue on GitHub. Contributions, pull requests are more than welcome!
NetCoreWithDocker is Copyright © 2017-2020 Oskar Dudycz and other contributors under the MIT license.