web-app

Web application wrapper and search endpoint for CKS

.NET Core 3 web application for NICE Clinical Knowledge Summaries (CKS) to host the static site generated via Gatsby and to serve a search API endpoint

Table of contents

• Web application wrapper and search endpoint for CKS
  • Stack
    • Software
  • Deploying to IIS
  • HTTP compression
  • Tests
    • Running the tests
      • From VSCode
      • From command line

Stack

Software

• Visual Studio 2019
• .NET Core 3
• xUnit for tests
  • With Moq for mocking
  • And Shouldly for assertions
• IIS Compression module for Brotli and gzip HTTP compression

Deploying to IIS

Running the web app locally for development will use either Kestrel or IIS Express by default.

Follow these steps to be able to run the app in IIS:

• Enable dynamic compression for IIS
• Download and install Microsoft IIS Compression (x64)
• Install URL Rewrite
• Enable overriding of HTTP_ACCEPT_ENCODING within allowedServerVariables in urlrewrite:
  • Open IIS
  • Open Configuration Editor within Management
  • Expand the section drop down to find system.webServer/rewrite/allowedServerVariables
  • Click Unlock section in the Actions pane on the right

HTTP compression

If you're new to HTTP compression (especially with IIS) then read 'IIS Compression Overview' on the Microsoft Docs.

We use dynamic compression to improve performance. It's dynamic compression rather than static because the gatsby static files aren't served straight from the file system via IIS. They're routed via the .NET Core runtime and served via the UseStaticFiles middleware.

There are 2 compression algorithms: Brotli and gzip, and we favour Brotli. Brotli is a newer algorithm by Google and is, in theory, 15-20% more efficient than gzipping. Brotli is also supposed to be particularly effective for text documents, and in our case we're mostly serving text (HTML, JS and JSON) so we should see good results. Global browser support for Brotli is up around 94% as of May 2020.

The compression comes from the IIS Dynamic Compression module via hosting the web app in IIS, rather than using the compression middleware built in to .NET Core. This is because of performance and is recommended in the docs. This is why there are extra steps to configure IIS for hosting, see the Deploying to IIS section above. This also means you won't get HTTP compression when running the app locally in Kestrel or IIS Express.

There's a bug in IIS < 1803 that means gzip is always preferred even if a requests's Accept-Encoding header contaings br e.g. Accept-Encoding: gzip, deflate, br. This is why there's a URL Rewrite rule called Prioritize Brotli that rewrites the Accept-Encoding header. See the web.config for the implementation details.

Note: brotli only works over HTTPS so if you're only seeing GZIP encoded responses, make sure you're serving over HTTPS.

Tests

We use xUnit as a test runner with Moq for mocking and Shouldly for assertions.

We have two of levels of tests within the web-app project:

• low-level unit tests
• integration tests.

The integration tests use a test web host and an in-memory test server to ensure the app works as a whole, including file system and network access.

Note: there are also Jest tests for the Gatsby static site and high-level functional, browser-based tests.

Try to follow Microsoft's conventions for naming tests and the surrounding code style wherever possible.

Running the tests

Run the test from either:

• VSCode
• Test Explorer window in Visual Studio
• Resharper in Visual Studio
• command line.

From VSCode

VSCode has built in support for running and debugging individual .NET tests.

Open a test file e.g. SearchTest.cs and click Run Test or Debug Test above the method signature.

From command line

Open a terminal at the web-app folder (right click on the web-app folder in the VSCode explorer and choose 'Open in Terminal') and run the following command to run all the tests:

# From the web-app folder
dotnet test

Or run a single test file by matching its name with the --filter argument. For example to run test files containing search e.g. SearchTests, use --filter search:

# From the web-app folder
dotnet test --filter search

See the dotnet test command docs for all the CLI options.