With microservice architectures, often times it is benefitial to develop you Angular applications from within Docker. Placing an Nginx proxy in front of your docker container can provide you with clean portless urls and ssl - making integration with services like Auth0 more natural.

In this article, I will show you how to work locally while serving your Angular application from within docker.

Docker

We will leverage both Docker and Docker Compose for this project.

Dockerfile

In order to increase the build times, we will be leveraging a docker cache layer based on the contents of the node package.config. This will prevent the build from having to pull down all of the node_modules files every time. The only time the layer will need to be refreshed is if you add or update an npm package.

Additionally, we will use the environment variable ENABLE_POLLING for Windows development machines that do not support File System Events.

FROM node:10

LABEL Maintainer = Christopher Town 
LABEL Name = Docker Angular App

# #############################################################################
# Cache layer with package.json for node_modules 
#
ADD package.json package-lock.json ./tmp/
RUN cd /tmp && npm i npm@latest -g && npm install && npm i -g nodemon
RUN mkdir -p /home/app/angular-app && cp -a /tmp/node_modules /home/app/angular-app

# #############################################################################
# Application Code
#
COPY . /home/app/angular-app

# #############################################################################
# Expose
#
WORKDIR /home/app/angular-app
EXPOSE 4200

# #############################################################################
# Start dev server with polling for Windows
# 
ENTRYPOINT ["/bin/bash", "-c", "if [ \"$ENABLE_POLLING\" = \"enabled\" ]; \
then npm run start:docker:poll; else npm run start:docker; fi"]

docker-compose

The docker compose configuration maps the application source in the container to the local development folder via a volume. This will allow ng serve to detect changes and dynamically reload your application.

version: '3'
services:

  docker-angular-app:
    image: docker-angular-app
    build:
      context: .
      dockerfile: Dockerfile
    container_name: docker-angular-app
    environment:
      - ENABLE_POLLING=${ENABLE_POLLING}
      - VIRTUAL_HOST=web.mydomain.com
    ports:
      - "4200:4200"
    volumes:
      - ./src:/home/app/angular-app/src
    working_dir: /home/app/angular-app
    networks:
      - dev-network
    tty: true
    stdin_open: true

networks:
  dev-network:
    driver: bridge

The VIRTUAL_HOST variable is used to support loading your container behind an nginx ssl proxy. Check out the post Clean Development URLs and SSL with Docker and Nginx Proxy for more info.

Node Tasks

In order to support containers and polling, the following tasks are used:

{
  "name": "docker-angular-app",
  "version": "0.0.0",
  "scripts": {
    "start": "ng serve --host 0.0.0.0 --port 4200",
    "start:docker": "ng serve --host 0.0.0.0 --port 4200 --configuration=container",
    "start:docker:poll": "npm run start:docker -- --poll 1000"
  }
}

Visual Studio Code Tasks

To streamline launching and debugging your application in a container, we'll add some VS Code tasks and debug launchers.

Tasks.json

The compose task will help build and compose the docker container.

{
    "label": "compose",
    "type": "shell",
    "osx": {
        "command": "bash ./scripts/project-tasks.sh compose"
    },
    "presentation": {
        "echo": true,
        "reveal": "always",
        "focus": true,
        "panel": "dedicated"
    },
    "problemMatcher": [],
    "windows": {
        "command": ".\\scripts\\project-tasks.ps1 -Compose"
    }
}

Launch.json

The docker launch debugger will call the compose task to create your container and then launch Chrome with the debugger attached. This will allow you to set breakpoints in you Angular application - even when running in the container.

{
    "name": "Docker Launch",
    "request": "launch",
    "preLaunchTask": "compose",
    "type": "chrome",
    "url": "http://localhost:4200",
    "webRoot": "${workspaceFolder}"
}

Helper Scripts

Two helper scripts, project-tasks.sh and project-tasks.ps1, have been added to orchestrate the management of your containers. You can read more about them in the web series, Orchestrating Visual Studio Code.

Source Code

https://github.com/christophla/blog-docker-angular

One of the great features of Visual Studio Code is its extensibility. In this series, we will learn how to orchestrate your development environment by leveraging the built in extension points of the IDE.

Prerequisites

• Visual Studio Code: https://code.visualstudio.com
• DotNet Core SDK: https://www.microsoft.com/net/download
• Docker: https://www.docker.com

Sections

The series is broken down into several sections:

Part 2 : Tasks and Launchers

We start by learning how to leverage tasks to build docker containers, push NuGet packages, run unit and integration tests, and more. Configure launchers to debug your code locally and remotely within docker.

Part 3 : Debugging with Docker Containers

Everything needed to remotely debug your microservices from within the docker environment.

Part 4 : AppSettings and the Container

Learn to configure multiple runtime settings to allow combinations of local and container debugging.

Part 5 : Unit Testing

Executing unit tests using VSCode tasks.

Part 6 : Code Coverage

Leverage coverlet and LCOV to generate html test-coverage reports.

Part 7 : NuGet Deployments

Deploy nuget packages with VSCode tasks.

Part 8 : Continuous Integration Builds

Create a CI build using everything we've learned using TravisCI.

Windows Users

All script samples in this series are written in bash for OSX and Linux. PowerShell equivalent scripts are provided in the source repository to allow identical functionality under Windows. In fact, all of the provided VS Code tasks will automatically point to the PowerShell scripts when running on a Windows OS.

Code Samples

A fully-functional project is provided for the series. Each part is contained in its own branch. Be sure to select the appropriate branch for each part of the series.

The full source code can be found at: https://github.com/christophla/blog-orchestrating-vscode

Next Post : Tasks and Launchers

In the next post we will learn how to leverage tasks and launchers to orchestrate building and debugging our application.

When developing microservices with docker containers, I often find myself trying to remember all of the different ports exposed by each service. Fortunately, there is a way to provide memorable, clean urls for each of your service endpoints.

By leveraging an Nginx Proxy in one of your containers, we can easily assign subdomains (e.g. service-a.mydomain.com) to each of your microservice projects.

I'll also show you how to dynamically generate a development certificate and load it into the proxy so that you will be able to connect securely to your services with SSL.

Source Files

All files are available in the repository: https://github.com/christophla/blog-docker-nginx-proxy

Both Bash and PowerShell scripts are provided for Windows, OSX, and Linux.

The Docker Compose File

Jason Wilder has created a great docker image, jwilder/nginx-proxy, that contains an instance of Nginx that automatically wires up a reverse proxy with host-headers for any docker containers that include the environmental variable VIRTUAL_HOST.

In the sample code, I've included a dotnet core webapi project as a service, along with an instance of nginx-proxy. The service nginx-proxy-app sets its virtual host as myapp.nginx-proxy-app.com.

version: '3'

services:

  nginx-proxy-app:
    container_name: nginx-proxy-app
    image: nginx-proxy-app
    build: 
      context: .
      dockerfile: Dockerfile
    environment:
      - ASPNETCORE_ENVIRONMENT=development
      - REMOTE_DEBUGGING=${REMOTE_DEBUGGING}
      - VIRTUAL_HOST=myapp.nginx-proxy-app.com
    ports:
      - "5000:80"
    networks:
      - dev-network
    tty: true
    stdin_open: true

  nginx-proxy-nat:
    image: jwilder/nginx-proxy
    container_name: nginx-proxy-nat
    environment:
      - HSTS=off
      - HTTPS_METHOD=noredirect
    ports:
      - "80:80"
      - "443:443"
    networks:
      - dev-network
    volumes:
      - /var/run/docker.sock:/tmp/docker.sock:ro
      - ./certs:/etc/nginx/certs

networks:
  dev-network:
    driver: bridge

The Setup Script

Our script is going to have to perform several things in order to setup our project to be able to use hostnames and SSL. First, we will remove any existing certificates generated for our custom domain. This will allow us to generate a new certificate when we add or remove services (and hostnames) to our development environment. Next, we will generate a certificate and add it to the docker volume ./certs:/etc/nginx/certs so that Nginx can pick it up for SSL. Last, we will add our hostnames to the local machine etc/hosts file..

setupProxy () {

    # remove existing certificates
    echo -e "${YELLOW} Removing existings certificates... ${RESTORE}"
    sudo security delete-certificate -c $certificatePrefix /Library/Keychains/System.keychain

    # generate key
    openssl \
        genrsa \
        -out certs/$certificatePrefix.key \
        4096

    # generate csr request
    openssl \
        req \
        -new \
        -sha256 \
        -out certs/$certificatePrefix.csr \
        -key certs/$certificatePrefix.key \
        -config openssl-san.conf

    #generate certificate from csr request
    openssl \
        x509 \
        -req \
        -days 3650 \
        -in certs/$certificatePrefix.csr \
        -signkey certs/$certificatePrefix.key \
        -out certs/$certificatePrefix.crt \
        -extensions req_ext \
        -extfile openssl-san.conf

    # generate pem
    cat certs/$certificatePrefix.crt certs/$certificatePrefix.key > certs/$certificatePrefix.pem

    # install certificate
    if [ -f certs/$certificatePrefix.crt ]; then
        echo -e "${YELLOW} Installing certificate... ${RESTORE}"
        sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain certs/$certificatePrefix.crt
    else
        echo -e "${RED} An error occurred while generating the certificate: certs/$certificatePrefix.crt ${RESTORE}"
    fi
    
    # Write Hosts
    addHost "myapp.nginx-proxy-app.com"

}

Since Chrome 58, self signed wildcard certificates are not supported without Subject Alternative Names (SANs). As a result, we will will use the config file openssl-san.conf to include each of our service hostnames.

[req]
default_bits = 2048
prompt = no
default_md = sha256
req_extensions = req_ext
distinguished_name = dn

[ dn ]
C=US
ST=Texas
L=Austin
O=Development
OU=Development Domain
emailAddress=admin@nginx-proxy-app.com
CN = nginx-proxy-app.com

[ req_ext ]
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment
subjectAltName = @alt_names

[alt_names]
DNS.1 = myapp.nginx-proxy-app.com

The Setup Task

We are going to create a VS Code Task to make running our script easier from within the IDE.

{
    "version": "2.0.0",
    "tasks": [{
        "label": "setup",
        "type": "shell",
        "osx": {
            "command": "bash ./scripts/project-tasks.sh setup"
        },
        "presentation": {
            "echo": true,
            "reveal": "always",
            "focus": true,
            "panel": "dedicated"
        },
        "problemMatcher": [],
        "windows": {
            "command": ".\\scripts\\project-tasks.ps1 -Setup"
        }
    }]
}

Conclusion

At this point, you should able to launch your docker-compose project and the Nginx service will automatically wire up your other services as hostnames with SSL.

Source Code

A fully-functional project is available at:

https://github.com/christophla/blog-docker-nginx-proxy

In this section, we will be adding a Continuous Integration (CI) build that leverages our project-tasks.sh scripts and tasks.

Travis CI

Travis CI is a free CI server for open-source projects.

The Configuration File

Create the file .travis.yaml in the the root of your project:

language: csharp
solution: WebApp.sln
mono: none
dotnet: 2.1.101
script:
  - chmod +x ./scripts/project-tasks.sh
  - ./scripts/project-tasks.sh compose
  - ./scripts/project-tasks.sh unitTests
  - ./scripts/project-tasks.sh nugetPublish
sudo: required
services:
  - docker

Be sure to include the leading . in the filename.

Travis Setup

Head over to https://travis-ci.org/christophla/blog-orchestrating-vscode to see the build in-action.

Conclusion

This wraps up the end of the web series Orchestrating Visual Studio Code.

The Source Code

You can find the source code for this article in the following repository under the part-7-nuget-deployment branch:

https://github.com/christophla/blog-orchestrating-vscode/tree/part-8-ci-builds

Previous Post : NuGet Deployment

https://christophertown.com/orchestrating-vscode-nuget-deployment

Content Delivery Networks (CDNs) are the backbone of the internet. Instead of sending content from your datacenter to a client half-way around the world, the content is pre-distributed and fetched from a server far closer (sometimes just down the street).

Typically with an Angular application, we put the index.html loading page on a Virtual Machine (VM) or Docker instance and then ship the rest of our application off to a CDN to make delivery more efficient and responsive. But what if you don't want to front the cost of hosting an index.html with a single VM or docker image?

Just imagine if your index page is hosted in a datacenter in Texas (South Central US) and a customer in London (UK South) brings up your site, they need to make a connection all the way across the Atlantic, just to be told that they can grab all of the additional required resources from a CDN a couple of miles away.

Why not cut out the middleman and bring everything close to home - all while cutting costs? We can achieve this by leveraging Azure's Premium CDN and its rules engine.

Enter Azure Premium CDN

What differentiates Azure CDN and Azure Premium CDN is that premium (Verizon) gives you an interface to control far more aspects of its behavior. You can set tokens, geo-filtering, caching, and - most importantly - add rules.

Managing Rules

For the sake of hosting a single page application on the CDN, lets focus on the rules engine that Azure Premium CDN offers. Rules will allow us to set a default document (index.html) for our site so that we have clean URLs.

Once you've created a Premium Azure CDN endpoint, go ahead an open it up in Azure Portal and select manage.

Go ahead an open the rules section under the CDN management site.

Adding a Rule

Click Add New:

Name / Description : Default Document

Choose IF and Always and add the following features. The source and destination pull-down should be your blob storage location for your app.

• URL Rewrite
  • Source: ((?:[^\?]*/)?)($|\?.*)
  • Destination : $1index.html$2
• URL Rewrite
  • Source: ((?:[^\?]*/)?[^\?/.]+)($|\?.*)
  • Destination : $1.html$2

This will point all URIs to your index.html page, e.g.:

• http://mysite.com
• http://mysite.com/#/home?myvar=one
• http://mysite.com/index.html

Setting Up DNS

At this point, you can create a C-Name Record pointing www.yourdomain.com to the Azure CDN entpoint at https://yourapp.azureedge.net. If your DNS provider supports it, you can create a page-rule that redirects all requests to yourdomain.com/* to www.yourdomain.com/*. Personally, I use CloudFlare account to manage my DNS, which supports redirecting to the C-Name.

Caveats

Since your index.html page is hosted on the CDN, when you push a new version of your application, it can take a long time for the changes to be reflected. You will need to select purge to see changes immediately.

Conclusion

I will be publishing a post in the future that describes how to host the index.html in an proxied Azure Function. This can help alleviate the need to reset the CDN cache after each deployment.

As developers, we are always leveraging various tools to help automate our day-to-day tasks. VS Code provides a built-in way of organizing all of these various workflows with Tasks. You can easily fire of a task without trying to remember what command to type, all while staying within the IDE. Combined with debug launchers, tasks can supercharge your environment and help you automate any process.

We are going to create a simple solution with a web-api project and then create some basic tasks to help us build and debug the application.

Setting Up the Environment

To get started, let’s create a basic web-api solution from the command line:

dotnet new sln --name WebApp

Next, let's create a webapi application in the /src folder.

mkdir src
cd src
dotnet new webapi

Go ahead and open your project in VSCode. The IDE should ask you if you'd like to add default folders. Say Yes and you should see a folder structure similar to the following:

│   WebApp.sln
│
├───.vscode
│       launch.json
│       tasks.json
│
└───src
    │   appsettings.json
    │   appsettings.development.json
    │   Program.cs
    │   Startup.cs
    │   WebApp.csproj
    │
    └───Controllers
            ValuesController.cs

Tasks and Launchers

As stated earlier, Tasks allow you to easily call commands and scripts from within the IDE. They can be used to automate any process that you may need; builds with gulp, building docker containers, pushing code to NuGet, etc. Launchers are used to launch your application with a debugger attached.

Both are defined in the .vscode folder in the root of your project:

├── .vscode
    ├── launch.json
    ├── tasks.json

If VSCode doesn't prompt you to automatically create the .vscode folder, you can always add it yourself.

Creating a Task

We'll start by creating a task to build our project.

{
    "version": "2.0.0",
    "tasks": [{
        "label": "build",
        "command": "dotnet",
        "type": "process",
        "args": [
            "build",
            "${workspaceFolder}/src/WebApp.csproj"
        ],
        "problemMatcher": "$msCompile"
    }]
}

To run your task, press F1 and then select Tasks:Run Task. Your task should be in the list the the label build. You'll see the solution being built in the VSCode output panel.

Creating a Debug Launcher

Debug Launchers are just that - a way to execute a process with the VSCode debugger attached. The preLaunchTask property tells the launcher to call our build task before launching the application.

{
    "version": "0.2.0",
    "configurations": [{
        "name": "Local Launch",
        "args": [],
        "cwd": "${workspaceFolder}/src",
        "env": {
            "ASPNETCORE_ENVIRONMENT": "development",
            "ASPNETCORE_URLS": "http://+:5000"
        },
        "internalConsoleOptions": "openOnSessionStart",
        "launchBrowser": {
            "args": "http://localhost:5000",
            "enabled": true,
            "linux": {
                "command": "xdg-open"
            },
            "osx": {
                "command": "open"
            },
            "windows": {
                "args": "/C start http://localhost:5000/api/values",
                "command": "cmd.exe"
            }
        },
        "preLaunchTask": "build",
        "program": "${workspaceFolder}/src/bin/Debug/netcoreapp2.0/WebApp.dll",
        "request": "launch",
        "sourceFileMap": {
            "/src": "${workspaceFolder}/src"
        },
        "stopAtEntry": false,
        "type": "coreclr"
    }]
}

Launching Your Project

The launchBrowser section tells VSCode to open the page http://localhost:5000/api/values once the application is running. Go ahead and press F5 or the debug icon to launch your application.

You should see a webpage with the following response (default for webapi scaffold):

["value1","value2"]

Project Settings

Visual Studio Code support project-level settings via the file settings.json in the .vscode folder.

{
    "files.eol": "\n"
}

Project Extensions

Visual Studio Code supports project-level extensions via the file extensions.json in the .vscode folder. When your project is first opened by a new developer, the IDE will prompt to install the extensions.

{
    "recommendations": [
        "editorconfig.editorconfig",
        "ms-vscode.csharp",
        "robertohuertasm.vscode-icons"
    ]
}

EditorConfig (editorconfig.editorconfig)

EditorConfig is used to maintain consistent formatting across developers in a project. http://editorconfig.org

OmniSharp C# (ms-vscode.csharp)

OniSharp is required to provide support for C#. It performs code anylsis with the Roslyn compiler and loads assemblies and projects. http://www.omnisharp.net

VSCode Icons (robertohuertasm.vscode-icons)

VSCode icons extend the built-in icons and provide an enhanced user experience.

Conclusion

At this point, we have learned how to configure the built-in project extension points in Visual Studio Code. By leveraging tasks, launchers, settings, and extensions, we are able to customize our project across development teams and provide functionality without leaving the IDE.

Source Code

https://github.com/christophla/blog-orchestrating-vscode/tree/part-2-tasks-and-launchers

Next Post : Debugging Docker Containers

In the next post we will learn how to leverage tasks and launchers to orchestrate building and debugging our application.

Previous Post : Overview

https://christophertown.com/orchestrating-visual-studio-code-overview

In this part, we will learn how to integrate NuGet package packing and deployment into our project.

The NuGet Script

We will add the method nugetPublish() to .vscode/tasks.json. This will search all projects in the solution that contain a .nuspec file, run dotnet pack, and curl upstream to NuGet.

nugetPublish () {

    echo -en "${YELLOW} Using Key: $nugetKey ${RESTORE}\n"

    buildEnvironment=@1

    if [[ -z buildEnvironment ]]; then
        buildEnvironment="debug"
    fi

    shopt -s nullglob # hide hidden

    cd src

    for dir in */ ; do # iterate projects
        [ -e "$dir" ] || continue

        cd $dir

        for nuspec in *.nuspec; do

            projectName=${dir::-1}
            echo -e "${YELLOW}Found nuspec for ${projectName} ${RESTORE}"

            dotnet pack \
            -c $buildEnvironment \
            --include-source \
            --include-symbols

            echo -e "${YELLOW}Publishing: ${projectName}.$nugetVersion ${RESTORE}"

            curl \
            -H 'Content-Type: application/octet-stream' \
            -H "X-NuGet-ApiKey: $nugetKey" \
            $nugetFeedUri \
            --upload-file bin/$buildEnvironment/${projectName}.$nugetVersion.nupkg

        done

        cd $ROOT_DIR

    done
}

You can also use a MyGet feed with the variable $nugetFeedUri in this script.

The NuGet Task

We will add the task nuget-publish to the .vscode\tasks.json file:

{
    "label": "nuget-publish",
    "type": "shell",
    "osx": {
        "command": "bash ./scripts/project-tasks.sh nugetPublish"
    },
    "presentation": {
        "echo": true,
        "reveal": "always",
        "focus": true,
        "panel": "dedicated"
    },
    "problemMatcher": [],
    "windows": {
        "command": ".\\scripts\\project-tasks.ps1 -NugetPublish"
    }
}

Deploying

After adding a project with a .nuspec to your solution, press F1 and select the task nuget-publish. You will see the project get built, packed, and uploaded to NuGet or MyGet.

++++++++++++++++++++++++++++++++++++++++++++++++
+ Deploying nuget packages to nuget feed
+ https://www.myget.org/F/envoice/api/v2
++++++++++++++++++++++++++++++++++++++++++++++++

 Using Key: 00000000-0000-0000-0000-000000000000

Found nuspec for MyApp.NuGetProject
Microsoft (R) Build Engine version 15.6.82.30579 for .NET Core
Copyright (C) Microsoft Corporation. All rights reserved.

  Restoring packages for ...
   Publishing: MyApp.NuGetProject.1.0.0
    The package has been created.

++++++++++++++++++++++++++++++++++++++++++++++++
Uploaded nuspec for MyApp.NuGetProject
++++++++++++++++++++++++++++++++++++++++++++++++

Instead of storing your api-key in source code, the script looks for an environment variable NUGET_KEY. You also need to set the NuGet|MyGet feed uri to the one provided from your account.

The Source Code

You can find the source code for this article in the following repository under the part-7-nuget-deployment branch:

https://github.com/christophla/VSCode-Orchestration/tree/part-7-nuget-deployment

Next Post : Part 8 : CI Integration

In the next post we will learn how integrate our tasks and scripts in our Continuous Build Server.

Previous Post : Unit Test Code Coverage

https://christophertown.com/orchestrating-vscode-test-code-coverage

We will learn how to add test code coverage reports using xUnit, Gulp and Coverlet, and LCOV.

The Files

The following files will be created in this section:

.
├── gulpfile.js
├── package.json
├── .coverage

NodeJS

In order to use Gulp, you will need to have NodeJS installed.

brew install node

Windows users can either load the installer from https://nodejs.org or use chocolatey to install node.

Gulp

Gulp is a toolkit for automating repetitive tasks in your development environment.

Installation

To use gulp, we will need to initialize npm (Node Package Manager). Run the following in the root of your project:

npm init

Then add gulp to your project:

npm install gulp --save-dev

And the LCOV html report generator:

npm install gulp-lcov-to-html --save-dev

While we have tried to focus on VS Code's built-in task runner and local scripts throughout this series, sometimes you need to step out of the box and leverage node and gulp for heavier workloads.

The Gulp Task

Create a file gulpfile.js in the root of your solution and add the following code:

const gulp = require('gulp')
const lcov = require('gulp-lcov-to-html')

gulp.task('generate-coverage-report', function () {

    return gulp
        .src("test/**/coverage.info") // grab the lcov files
        .pipe(lcov({
            name : "My WebApp"
        })) 
        .pipe(gulp.dest(".coverage")) // output to .coverage folder

});

This task generate-coverage-report will look through the test folder for coverage.info files and generate an html report with them in the .coverage directory.

Coverlet

Coverlet is a code coverage library for .NET Core, with support for line, branch, and method coverage. We will be using it in our test project to output coverage data in lcov format.

Installation

In the root of test/UnitTests, run the following to install coverlet in your project:

dotnet add package coverlet.msbuild --version 1.2.0

The Scripts

We will add the following to our unitTests() method in project-tasks.sh to generate a coverage report when our tests run.

unitTests () {

    for dir in test/*.UnitTests*/ ; do
        ...
        dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=lcov
        ...
    done
    
    ...
    
    gulp generate-coverage-report
}

The switches we added to dotnet test tell the test runner that we want to enable code coverage and output the results as lcov. We also call the gulp task that we created earlier to create the report.

Running the Tests

Press F1 and run the unit-tests task. You will see output from our gulp task. Opening the report in a web browser will give you detailed results per project, namespace, and class.

Calculating coverage result...
  Generating report 'C:\Users\CTown\AppDev\VSCode-Orchestration\test\UnitTests\coverage.info'

| Module   | Coverage |
|----------|----------|
   WebApp       0%
 
++++++++++++++++++++++++++++++++++++++++++++++++
+ Generating code-coverage html report
++++++++++++++++++++++++++++++++++++++++++++++++
[11:10:19] Using gulpfile ~\AppDev\VSCode-Orchestration\gulpfile.js
[11:10:19] Starting 'generate-coverage-report'...
[11:10:19] Finished 'generate-coverage-report' after 118 ms
++++++++++++++++++++++++++++++++++++++++++++++++
+ Report generated at:
+
+ /.coverage/index.html
++++++++++++++++++++++++++++++++++++++++++++++++

Since we only have a simple smoke test that doesn't actually cover any of our application code - the module and coverage results will be empty. Go ahead and start writing some real unit tests and you will begin to see percentages.

The Source Code

You can find the source code for this article in the following repository under the part-6-xunit-code-coverage branch:

https://github.com/christophla/VSCode-Orchestration/tree/part-6-xunit-code-coverage

Next Post : Deploying NuGet Packages

In the next post we will learn how to create a task to scan our solution for NuGet projects and deploy them to nuget.org and myget.org.

Previous Post : Unit Testing

https://christophertown.com/orchestrating-vscode-unit-testing

In this section, we will be automating unit tests with Visual Studio Code tasks.

XUnit

xUnit is a lightweight test framework that is very popular in the .NET community. It supports extensions for BDD with the xBehave library that can be very helpful in descibing tests with your Product Team as well as increased readability via syntax similar to Gherkin notation.

GitLens

GitLense is a Visual Studio Code plugin that gives insights into your underlying git repository (similar to CodeLens) as well as providing test run/debug links throughtout your code.

Your First Test

We will be creating a test project, adding the xUnit and xBehave NuGet packages, and wiring it up to a VSCode task so that we can run it from the IDE.

The Test Project

We are going to add a new top-level folder /test/UnitTests to hold your solution's tests. Navigate your shell to that folder and create a project.

mkdir -p test/UnitTests
cd test/UnitTests
dotnet new classlib

We need to switch the project from netstandard2.0 to netcoreapp2.0 to support the xunit dotnet cli integration. Change the following in UnitTests.csproj:

<PropertyGroup>
    <TargetFramework>netcoreapp2.0</TargetFramework>
</PropertyGroup>

Make sure to add the new test project to our solution. Run the following from the root of the project:

dotnet sln add test/UnitTests/UnitTests.csproj

Adding Test Packages

Within the ./test/UnitTests directoy, we will add xUnit...

dotnet add package xunit --version 2.3.1
dotnet add package xunit.runner.visualstudio --version 2.3.1

... and then add the xunit cli tool to the UnitTests.csproj:

<ItemGroup>
    <DotNetCliToolReference Include="dotnet-xunit" Version="2.3.1" />
</ItemGroup>

The OmniSharp extension we loaded earlier will prompt to Restore Packages. This will pull the binaries down from NuGet into your local test project.

Creating a Smoke Test

We are going to create a simple smoke test for this example:

└── test
    └── UnitTests
        ├── SmokeTest.cs
        ├── UnitTests.csproj

using Xunit;

namespace UnitTests
{
    public class SmokeTest
    {
        [Fact]
        public void CanAssertTrue()
        {
            Assert.True(true, "Our first test!");
        }
    }
}

From time to time, OmniSharp will hang when loading new packages. If you aren't seeing intellisense, press F1 and select Reload Window. This will reset the analysis engine.

The Unit Test Task

We are now going to add a new tasks to our .vcode/tasks.json file:

{
    "label": "unit-tests",
    "type": "shell",
    "group": {
        "kind": "test",
        "isDefault": true
    },
    "osx": {
        "command": "bash ./scripts/project-tasks.sh unitTests"
    },
    "presentation": {
        "echo": true,
        "reveal": "always",
        "focus": true,
        "panel": "dedicated"
    },
    "problemMatcher": [],
    "windows": {
        "command": ".\\scripts\\project-tasks.ps1 -UnitTests"
    }
}

The Unit Test Script

The task will call the unitTests() method in the scripts/project-tasks.sh file which iterates over the projects under the /test directory and executes dotnet test for folders with UnitTests in their name.

# #############################################################################
# Runs the unit tests.
#
unitTests () {

    echo -e "${GREEN}"
    echo -e "++++++++++++++++++++++++++++++++++++++++++++++++"
    echo -e "+ Running unit tests                            "
    echo -e "++++++++++++++++++++++++++++++++++++++++++++++++"
    echo -e "${RESTORE}"

    for dir in test/*UnitTests*/ ; do
        [ -e "$dir" ] || continue
        dir=${dir%*/}
        echo -e "Found tests in: test/${dir##*/}"
        cd $dir
        dotnet test 
        rtn=$?
        if [ "$rtn" != "0" ]; then            
            echo -e "${RED}An error occurred${RESTORE}"
            exit $rtn
        fi
    done

}

Running Your Tests

At this point, press F1 and run the task unit-tests. You should see the following output:

++++++++++++++++++++++++++++++++++++++++++++++++
+ Running unit tests
++++++++++++++++++++++++++++++++++++++++++++++++

Found: test/UnitTests
Build started, please wait...
Build completed.

Test run for /VSCode-Orchestration/test/UnitTests/bin/Debug/netcoreapp2.0/UnitTests.dll(.NETCoreApp,Version=v2.0)
Microsoft (R) Test Execution Command Line Tool Version 15.6.0-preview-20180109-01
Copyright (c) Microsoft Corporation.  All rights reserved.

Starting test execution, please wait...
[xUnit.net 00:00:00.6418600]   Discovering: UnitTests
[xUnit.net 00:00:00.7619690]   Discovered:  UnitTests
[xUnit.net 00:00:00.7693280]   Starting:    UnitTests
[xUnit.net 00:00:00.9738810]   Finished:    UnitTests

Total tests: 1. Passed: 1. Failed: 0. Skipped: 0.
Test Run Successful.
Test execution time: 2.0896 Seconds

Debugging Your Test

Installing GitLense

We will now load the GitLense extension to allow running and debugging individual tests. Open the extensions menu on the left panel and search for GitLense to install it.

Running and Debugging a single test

Once GitLense is loaded, you will see gray annotations above your classes and methods. If the method is a [Test], [Fact], [Scenario], or any other attribute designating a testable mehtod, you will see two options, run test and debug test.

GitLense also provides insights into your git repository blame logs. You can see what time and which team member last updated each line of code. This is very simlar to Visual Studio's CodeLense feature (but free!).

Conclusion

We learned how to wire-up multiple unit test projects to run within VS Code.

The Source Code

You can find the source code for this article in the following repository under the part-5-unit-testing branch:

https://github.com/christophla/VSCode-Orchestration/tree/part-5-unit-testing

Next Post : Code Coverage

In the next post we will learn how to add code coverage reports to our test runs with gulp and lcov.

Previous Post : Running Docker Containers

https://christophertown.com/orchestrating-vscode-running-docker-containers

Previously, in part 3, we learned how to debug a container running in docker. In this section, we will learn how to run our containerized application without the debugger.

Unfortunately at this time, the vsdbg debugger for Visual Studio Code does not support attaching to a running process remotely. Instead, it listens for commands to start the application and, as a result, your docker application will not run without it.

Container AppSettings

Make a copy of your appsettings.json file and call it appsettings.container.json. This file will be used exclusively when the application runs inside of docker.

└───src
    │   appsettings.container.json
    │   appsettings.development.json
    │   appsettings.json
    │   Program.cs
    │   Startup.cs
    │   WebApp.csproj

For now we will leave it alone, but in a future post I will show you how to leverage this file to perform cross-container communications between multiple microservices.

Compose Method

We will be leveraging the compose method we created earlier to add a new switch that does not set the REMOTE_DEBUGGING environment variable. This will cause the Dockerfile entrypoint to fire up the application instead of waiting for debug commands.

ENTRYPOINT ["/bin/bash", "-c", "if [ \"$REMOTE_DEBUGGING\" = \"enabled\" ]; then sleep infinity; else dotnet WebApp.dll; fi"]

case "$1" in
    "clean")
        clean
        ;;
    "compose")
        compose
        ;;
    "composeForDebug")
        export REMOTE_DEBUGGING="enabled"
        compose
        ;;
    *)
        showUsage
        ;;
esac

Compose Task

We will add a new task to .vscode/tasks.json that will call our compose() method in the project-tasks.sh script.

{
    "label": "compose",
    "type": "shell",
    "group": {
        "kind": "build",
        "isDefault": true
    },
    "osx": {
        "command": "bash ./scripts/project-tasks.sh compose"
    },
    "presentation": {
        "echo": true,
        "reveal": "always",
        "focus": true,
        "panel": "dedicated"
    },
    "problemMatcher": [],
    "windows": {
        "command": ".\\scripts\\project-tasks.ps1 -Compose"
    }
}

Running our Task

At this point, press F1, select Tasks: Run Task, and select compose. Your docker container will build and run without a debugger attached. You will need to manually open your web browser to view the application at: http://localhost:5000/api/values

Conclusion

We have learned how to compose and run our docker container without attaching a debugger.

Source Code

https://github.com/christophla/blog-orchestrating-vscode/tree/part-4-running-containers

Next Post : Unit Tests

In the next post we will learn how to create a unit test project and a VS Code task to run them. We will also explore the GitLense extension to support running and debugging individual tests from within the IDE.

Previous Post : Debugging Docker Containers

https://christophertown.com/orchestrating-vscode-debugging-docker

When working with multiple microservices, it is important to be able to run a debugger inside the docker container. In this article, we will learn how to load vsdbg - the Visual Studio Debugger - inside of a docker image and attach to it using VS Code's launchers.

The Files

The following files will be created in this section:

.
├── Dockerfile
├── docker-compose.yml
├── scripts
    ├── project-tasks.ps1
    └── project-tasks.sh

The Dockerfile

We are using a multi-stage dockerfile to load a base image containing the Visual Studio Code debugger with the following steps:

• Create a base image layer from aspnetcore2.0.
• Download the VSCode debugger vsdbg.
• Create a build image layer from aspnetcore-build.
• Copy the contents of the web project WebProject.
• Publish the web project into /publish folder.
• Create a production layer from the base layer.
• Copy the /publish folder contents into the production layer.

The ENTRYPOINT for the dockerfile serves dual purposes:

• Run the application normally.
• If the ENABLE_DEBUGGING environmental variable is set, sleep the application and listen for debug commands

# #############################################################################
# Development docker image with support for Visual Studio debugging integration
#

# #############################################################################
# BASE IMAGE
FROM microsoft/aspnetcore:2.0 AS base
WORKDIR /app
EXPOSE 80

# vscode debugging support
WORKDIR /vsdbg
RUN apt-get update \
    && apt-get install -y --no-install-recommends \
        unzip \
    && rm -rf /var/lib/apt/lists/* \
    && curl -sSL https://aka.ms/getvsdbgsh | bash /dev/stdin -v latest -l /vsdbg


# #############################################################################
# BUILDER IMAGE
FROM microsoft/aspnetcore-build:2.0 AS builder
ENV NUGET_XMLDOC_MODE skip

# publish
COPY . /app
WORKDIR /app/src
RUN dotnet publish -f netcoreapp2.0 -r debian.8-x64 -c Debug -o /publish -v quiet


# #############################################################################
# PRODUCTION IMAGE
FROM base AS production
WORKDIR /app
COPY --from=builder /publish .

# Kick off a container just to wait debugger to attach and run the app
ENTRYPOINT ["/bin/bash", "-c", "if [ \"$REMOTE_DEBUGGING\" = \"enabled\" ]; then sleep infinity; else dotnet WebProject.dll; fi"]

# #############################################################################

The docker-compose file

The docker-compose file contains a single service for creating the docker container.
The REMOTE_DEBUGGING variable is set via a VSCode pre-launch task.

version: '3'

services:

  docker-debug-webapp:
    container_name: docker-debug-webapp
    image: docker-debug-webapp
    build: 
      context: .
      dockerfile: Dockerfile
    environment:
      - ASPNETCORE_ENVIRONMENT=development
      - REMOTE_DEBUGGING=${REMOTE_DEBUGGING}
    ports:
      - "5000:80"
    networks:
      - dev-network
    tty: true
    stdin_open: true

networks:
  dev-network:
    driver: bridge

The setup scripts

The setup scripts project-tasks.sh and project-tasks.ps1 are used to build and compose the container before launching the debugger.

.
├── scripts
│   ├── project-tasks.ps1
│   └── project-tasks.sh

We will be using the bash project-tasks.sh script for this exercise. If you are on windows, a PowerShell project-tasks.ps script is provided in the GitHub source.

The compose() helper method

The compose() method is called by the task to stage your container. It supports multiple docker.{environment}.yml files. The default is docker-compose.yml.

compose () {

    echo -e "${GREEN}"
    echo -e "++++++++++++++++++++++++++++++++++++++++++++++++"
    echo -e "+ Composing docker images                       "
    echo -e "++++++++++++++++++++++++++++++++++++++++++++++++"
    echo -e "${RESTORE}"

    if [[ -z $ENVIRONMENT ]]; then
        ENVIRONMENT="debug"
    fi

    composeFileName="docker-compose.yml"
    if [[ $ENVIRONMENT != "debug" ]]; then
        composeFileName="docker-compose.$ENVIRONMENT.yml"
    fi

    if [[ ! -f $composeFileName ]]; then
        echo -e "${RED} $ENVIRONMENT is not a valid parameter. File '$composeFileName' does not exist. ${RESTORE}\n"
    else

        echo -e "${YELLOW} Building the image $imageName ($ENVIRONMENT). ${RESTORE}\n"
        docker-compose -f "$composeFileName" build

        echo -e "${YELLOW} Creating the container $imageName ${RESTORE}\n"
        docker-compose -f $composeFileName kill
        docker-compose -f $composeFileName up -d
    fi
}

...

case "$1" in
    "composeForDebug")
        export REMOTE_DEBUGGING="enabled"
        compose
        ;;
    *)
        showUsage
        ;;
esac

Note the export REMOTE_DEBUGGING environmental variable. It is being set so that docker-compose can pass it to the Dockerfile's ENTRYPOINT. This will pause the container so that it can listen for vsdbg debugging commands from the IDE. It also allows us to use the compose() method to run our containers without debugging enabled.

The VSCode Task

The Visual Studio Code tasks.json is used to link the setup scripts.
Links to the Windows PowerShell and OSX/Linux Bash scripts. It is used to create our docker image and container:

• Creates the image.
• Kills any running instances.
• Starts the container.

Add the following to your .vscode/tasks.json:

{
    "label": "compose-for-debug",
    "type": "shell",
    "osx": {
        "command": "bash ./scripts/project-tasks.sh composeForDebug"
    },
    "presentation": {
        "echo": true,
        "reveal": "always",
        "focus": true,
        "panel": "dedicated"
    },
    "problemMatcher": [],
    "windows": {
        "command": ".\\scripts\\project-tasks.ps1 -ComposeForDebug"
    }
}

The VSCode Launcher

The Visual Studio Code launch.json orchestrates the application with the following settings:

• Configures apreLaunchTask called compose-for-debug to build and compose the docker container.
• Sets the REMOTE_DEBUGGING env variable to allow the container debugger vsdbg to listen for commands.
• Configures the pipeTransport with the path /vsdgb/vsdbgto the debugger within the container and the command docker and args exec -i that should be executed to begin debugging.
• Sets the sourceFileMap to allow breakpoints on the local filesystem to line-up with the compiled source in the container.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Docker Launch",
            "type": "coreclr",
            "request": "launch",
            "preLaunchTask": "compose-for-debug",
            "cwd": "/app",
            "program": "/app/WebApp.dll",
            "env": {
                "ASPNETCORE_ENVIRONMENT": "development",
                "REMOTE_DEBUGGING": "true"
            },
            "sourceFileMap": {
                "/app": "${workspaceRoot}"
            },
            "launchBrowser": {
                "enabled": true,
                "args": "http://localhost:5000/api/values",
                "windows": {
                    "command": "cmd.exe",
                    "args": "/C start http://localhost:5000/api/values"
                },
                "osx": {
                    "command": "open"
                }
            },
            "pipeTransport": {
                "debuggerPath": "/vsdbg/vsdbg",
                "pipeProgram": "docker",
                "pipeCwd": "${workspaceRoot}",
                "pipeArgs": [
                    "exec -i docker-debug-webapp"
                ],
                "quoteArgs": false
            }
        }
    ]
}

Debugging Your App

At this point, you should be able to run the debug task from within VSCode. Press F1, select Run Tasks, and select compose-for-debug. You application will start with a debugger attached.

Composing Without Debug

I've included an additional task compose that allows you to run your docker container without the debugger attached. This is useful in microservice environments where you want to run several services to work against.

In a later post, I'll be showing how you can orchestrate a large number of microservices using VSCode workspaces and the compose task.

The Source Code

You can find the source code for this article in the following repository under the part-2-tasks-and-launchers branch:

https://github.com/christophla/blog-orchestrating-vscode/tree/part-3-debugging-docker

Next Post : Running Docker Containers

In the next post we will learn how to run stand-along docker container without the debugger attached. This is useful when orchestrating several dependent microservices in a large application.

Previous Post : Tasks and Launchers

https://christophertown.com/orchestrating-vscode-tasks-and-launchers