Skip to content

Latest commit

 

History

History
executable file
·
186 lines (124 loc) · 9.64 KB

README.md

File metadata and controls

executable file
·
186 lines (124 loc) · 9.64 KB
Raw

.NET - Demo Web Application

This is a simple .NET web app using the new minimal hosting model, and Razor pages. It was created from the dotnet new webapp template and modified adding custom APIs, Bootstrap v5, Microsoft Identity and other packages/features.

The app has been designed with cloud native demos & containers in mind, in order to provide a real working application for deployment, something more than "hello-world" but with the minimum of pre-reqs. It is not intended as a complete example of a fully functioning architecture or complex software design.

Typical uses would be deployment to Kubernetes, demos of Docker, CI/CD (build pipelines are provided), deployment to cloud (Azure) monitoring, auto-scaling

The app has several basic pages accessed from the top navigation menu, some of which are only lit up when certain configuration variables are set (see 'Optional Features' below):

  • Info - Will show system & runtime information, and will also display if the app is running from within a Docker container and Kubernetes.
  • Tools - Some tools useful in demos, such a forcing CPU load (for autoscale demos), and error/exception pages for use with App Insights or other monitoring tool.
  • Monitoring - Displays realtime CPU load and memory working set charts, fetched from an REST API and displayed using chart.js
  • Weather - (Optional) Gets the location of the client page (with HTML5 Geolocation). The resulting location is used to fetch a weather forecast from the OpenWeather API
  • User Account - (Optional) When configured with Azure AD (application client id and secret) user login button will be enabled, and an user-account details page enabled, which calls the Microsoft Graph API

screen screen screen

Status

Live instances:

Running and Testing Locally

Pre-reqs

  • Be using Linux, WSL or MacOS, with bash, make etc
  • .NET 6 - for running locally, linting, running tests etc
  • Docker - for running as a container, or image build and push
  • Azure CLI - for deployment to Azure

Clone the project to any directory where you do development work

git clone https://github.com/benc-uk/dotnet-demoapp.git

Makefile

A standard GNU Make file is provided to help with running and building locally.

$ make

help                 💬 This help message
lint                 🔎 Lint & format, will not fix but sets exit code on error
image                🔨 Build container image from Dockerfile
push                 📤 Push container image to registry
run                  🏃‍ Run locally using Dotnet CLI
deploy               🚀 Deploy to Azure Container App
undeploy             💀 Remove from Azure
test                 🎯 Unit tests with xUnit
test-report          🤡 Unit tests with xUnit & output report
clean                🧹 Clean up project

Make file variables and default values, pass these in when calling make, e.g. make image IMAGE_REPO=blah/foo

Makefile Variable Default
IMAGE_REG ghcr.io
IMAGE_REPO benc-uk/dotnet-demoapp
IMAGE_TAG latest
AZURE_RES_GROUP demoapps
AZURE_REGION northeurope
AZURE_APP_NAME dotnet-demoapp

Web app will listen on the usual Kestrel port of 5000, but this can be changed by setting the ASPNETCORE_URLS environmental variable or with the --urls parameter (see docs).

Containers

Public container image is available on GitHub Container Registry.

Run in a container with:

docker run --rm -it -p 5000:5000 ghcr.io/benc-uk/dotnet-demoapp:latest

Should you want to build your own container, use make image and the above variables to customise the name & tag.

Kubernetes

The app can easily be deployed to Kubernetes using Helm, see deploy/kubernetes/readme.md for details

GitHub Actions CI/CD

A set of GitHub Actions workflows are included for CI / CD. Automated builds for PRs are run in GitHub hosted runners validating the code (linting and tests) and building dev images. When code is merged into master, then automated deployment to AKS is done using Helm.

Optional Features

The app will start up and run with zero configuration, however the only features that will be available will be the Info, Tools & Monitoring views. The following optional features can be enabled:

Application Insights

Enable this by setting ApplicationInsights__InstrumentationKey

The app has been instrumented with the Application Insights SDK, it will however need to be configured to point to your App Insights instance/workspace. All requests will be tracked, as well as dependant calls to other APIs, exceptions & errors will also be logged

This article has more information on monitoring .NET with App Insights

If running locally, and using appsettings.Development.json, this can be configured as follows

"ApplicationInsights": {
  "InstrumentationKey": "<key value here>"
}

Weather Details

Enable this by setting Weather__ApiKey

This will require a API key from OpenWeather, you can sign up for free and get one here. The page uses a browser API for geolocation to fetch the user's location. However, the geolocation.getCurrentPosition() browser API will only work when the site is served via HTTPS or from localhost. As a fallback, weather for London, UK will be show if the current position can not be obtained

If running locally, and using appsettings.Development.json, this can be configured as follows

"Weather": {
  "ApiKey": "<key value here>"
}

User Authentication with Azure AD and Microsoft Graph

Enable this feature by setting several 'AzureAd' environmental variables, once enabled, a 'Login' button will be displayed on the main top nav bar.

This uses Microsoft.Identity.Web which is a library allowing .NET web apps to use the Microsoft Identity Platform (i.e. Azure AD v2.0 endpoint)

In addition the user account page shows details & photo retrieved from the Microsoft Graph API

You will need to register an app in your Azure AD tenant. See this guide. Make sure you enable the options

  • Enable the app for "Accounts in any organizational directory and personal Microsoft accounts"
  • Add 'Web platform' for authentication
  • Ensure your Redirect URI ends with /signin-oidc
  • Enable "Access Tokens" and "ID Tokens" in the authentication settings.
  • Add a new client secret, and make a note of it's value

Environmental Variables:

  • AzureAd__ClientId: You app's client id
  • AzureAd__ClientSecret: You app's client secret
  • AzureAd__Instance: Set to https://login.microsoftonline.com/
  • AzureAd__TenantId: Set to common

If running locally, and using appsettings.Development.json, this can be configured as follows

"AzureAd": {
  "Instance": "https://login.microsoftonline.com/",
  "ClientId": "<change me>",
  "ClientSecret": "<change me>",
  "TenantId": "common",
}

Running in Azure - Container App

If you want to deploy to an Azure Container App, a Bicep template is provided in the deploy directory

For a quick deployment, use make deploy which will create a resource group, the Azure Container App instance (with supporting resources) and deploy the latest image to it

make deploy

Note. Azure Container App doesn't currently support HTTP header forwarding, so Azure AD sign-in will not work as it mis-redirects to the wrong URL

Updates

  • Nov 2021 - Large scale rewrite to .NET 6
  • Mar 2021 - Update to deployment, added dummy unit tests and makefile
  • Nov 2020 - Updated to .NET 5
  • Nov 2020 - New GitHub pipelines & container registry
  • Jun 2020 - Moved to NuGet for the Microsoft.Identity.Web
  • Jan 2020 - Rewritten from scratch