arcus-azure / arcus.templates Goto Github PK

406 is returned when the client send the Accept: text/plain

How to fix this?

• remove the text plain as supported media type for JsonOutputFormatter?

            var jsonOutputFormatter = options.OutputFormatters.OfType<JsonOutputFormatter>().FirstOrDefault();
            if (jsonOutputFormatter != null)
            {
                if (!jsonOutputFormatter.SupportedMediaTypes.Contains(Text.Plain))
                {
                    jsonOutputFormatter.SupportedMediaTypes.Add(Text.Plain);
                }
            }

• remove the text plain as supported media type for JsonInputFormatter?

            var jsonInputFormatter = options.InputFormatters.OfType<JsonInputFormatter>().FirstOrDefault();
            if (jsonInputFormatter != null)
            {
                if (jsonInputFormatter.SupportedMediaTypes.Contains(Text.Plain))
                {
                    jsonInputFormatter.SupportedMediaTypes.Remove(Text.Plain);
                }
            }

• understand why the StringOutputFormatter doesn't kick in.
  StringOutputFormatter is added by default and according to the docs it should take care of text/plain
  If not used / if doesn't kick in, better to remove

            var stringFormatter = options.OutputFormatters.OfType<StringOutputFormatter>().FirstOrDefault();
            if (stringFormatter != null) options.OutputFormatters.RemoveType<StringOutputFormatter>();

To use the correlation functionality, we needed the MyGet package because no next release was made for the Arcus.WebApi library.

When that happens, we should remove the MyGet package source and use the offical NuGet release.

Marvin.StreamExtensions includes basic functionality to interact with streams which I've found myself implementing myself as well.

Might be interesting to include it rather than building our own.

using (var response = await httpClient.SendAsync(request))
{
    using (var stream = await response.Content.ReadAsStreamAsync())
    {
        var person = stream.ReadAndDeserializeFromJson<Person>();
    }
}

Write introduction blog post for templates which discusses the focus of the project and what it brings to the table

Update issue template to list version of installed packages so that we have an idea what the user is using.

Example: https://github.com/tomkerkhove/promitor/blob/master/.github/ISSUE_TEMPLATE/Bug_report.md#specifications

Initially required in #143

Use enrichers from Arcus Observability

Is your feature request related to a problem? Please describe.
Document what version introduces a specific feature so that people know what to expect.

Describe the solution you'd like

• Only publish documentation for new features when a new version is released
• Provide indication in documentation what version introduces the feature

Describe alternatives you've considered
None

Provide a custom dotnet new template which configures a Web API with minimal requirements.

The template should be calles arcus-webapi.

Features in the template

• Plug in exception middleware
• Configure content negotiation to only support application/json
• Setup Swagger generation
• Setup Swagger UI (but disable for PROD env)
• Configure health checks (middleware only)
• Provide health endpoint (based on info gained via health checks
  • Fully documented according to our guidelines
• Provide a working Dockerfile
• Build a default logger

The template should not provide any authentication by default but should provide a comment that warns about this and point to Arcus WebAPI and Shared Access Key.

Requirements

We should provide a CI that performs following steps:

1. Create project based on template via dotnet new arcus-webapi
2. Build a Docker container based on Dockerfile
3. Run Docker container
4. Get the health of the container

Good reads

• https://rehansaeed.com/custom-project-templates-using-dotnet-new/

When executing the command

dotnet new arcus-webapi --name api.test

the new project is created directly in the current folder. I think it would be better to create the new project in a (new) subfolder of the current folder. So when executing the above command, a subfolder api.test should be created and the project should be created in that folder.

I think this makes it a bit more user-friendly and it is also in line with the webapi template that is provided by MS.

Investigate if we can use stage/job templates for defining our test stages in our builds given they are duplicated in our CI & release build.

• Stage template: https://docs.microsoft.com/en-us/azure/devops/pipelines/yaml-schema?view=azure-devops&tabs=schema#stage-templates
• Job template: https://docs.microsoft.com/en-us/azure/devops/pipelines/yaml-schema?view=azure-devops&tabs=schema#job-templates

Provide a release pipeline for NuGet.org.

Checklist

• Build the codebase
• Run test suite
• Tag the codebase on success
• Create a GitHub pre-release for a preview releases
• Create a GitHub release for full releases
• Push all NuGet packages to NuGet.org

Configure code owners that need to approve changes before merging them in. (docs)

Provide a custom dotnet new template which configures a Worker with minimal requirements.

The template should be calles arcus-servicebus-queue and arcus-servicebus-topic.

Features in the template

• TCP Health Probes
• Register ICachedSecretProvider as dependency
• Registration of message pump which is using empty message handler
  • By default, use ISecretProvider for getting connection string
• Empty message handler

Good reads

• https://rehansaeed.com/custom-project-templates-using-dotnet-new/

Provide integration tests for Swagger (UI):

• Spin up in debug, is able to navigate to Swagger UI
• Spin up in debug, is able to navigate to Swagger docs
• Spin up in release, is not able to navigate to Swagger UI
• Spin up in release, is not able to navigate to Swagger docs

Problem

Example: when we create a TemplateProject, the temp project directory gets deleted but this could contain valuable information on why a test may fail.

Proposal

The disposal of this project could be made configurable.

Swagger UI is not working for generated Web API.

Repro

1. dotnet new arcus-webapi -n Arcus.Demo.WebAPI
2. dotnet run .\Arcus.Demo.WebAPI.csproj

Error

Could not find file 'C:\Temp\bin\Debug\netcoreapp2.2\Arcus.Template.WebApi.Open-Api.xml'.

Analysis

The reason for this is that the file in <DocumentationFile> in Arcus.Demo.WebAPI.csproj is replaced successfully but not when calling AddSwaggerGen (title+path) in Startup.cs.

Is your feature request related to a problem? Please describe.
Document correlation headers in OpenAPI specs, when applicable

Describe the solution you'd like
Use Swashbuckle.AspNetCore.Filters.

We need to:

• Configure it in AddSwaggerGen via AddHeaderOperationFilter & AddResponseHeadersFilter (see docs)
• Annotate our health endpoint with SwaggerResponseHeader (see docs)

Describe alternatives you've considered
None

Additional context
This should only happen when exclude-correlation & exclude-openApi are false

What feature would you like to have?
In any app, there may come a time where you want to limit access for diff authenticated users.. Right now, we allow all features of any API by a single shared access key or configured certificate.
I think it would be useful to add also a JWT authentication system with roles for authorization for a more fine-grained control?

Alternatives you may have considered?
We could also add the possibility to use different kinds of shared access keys/certificates for different levels of access in the API. Maybe also with roles.

Switch Worker template to .NET Core 3.1

Is your feature request related to a problem? Please describe.
Determine if we can warn users about new template versions being available which they should upgrade to.

Describe the solution you'd like
Warning in output

Describe alternatives you've considered
None

Problem

The Startup class still has a middleware method to load the client certificate from the X-ARR-ClientCert header. This will become unnecessary since the CertificateAuthenticationFilter will automatically load this in the future.

Solution

This filter is part of the arcus.webapi repo and will become available for all versions above v.0.2.0.

Configure a CI build that will build & test the changes made in every PR

Is your feature request related to a problem? Please describe.
We should provide information about the installed version.

Describe the solution you'd like
Show template version when using the --help argument.

Describe alternatives you've considered
None.

Enhance our integration tests in builds so that we have one stage which has 2 jobs:

1. To run the test category for all tests that require the generated image to run as a Docker container
2. To run the test category for integration tests that requires no infrastructure

Provide capability to opt-out for Serilog during generation for workers during generation so that it is already configured.

When I create a new Arcus webapi project using the dotnet new arcus-webapi command, a new api project is created as expected.

However, since the Api project supports Docker (a dockerfile is created), I would also expect that there's a profile available which allows me to run/test my API from Visual Studio using Docker.

When I create a new Arcus WebApi project, following profiles are available:

When I create a new Web Api project via Visual Studio and I enable Docker support these profiles are available:

It would be nice if the Docker profile is also available when creating a new project using the arcus-webapi template and that this Docker profile is the default profile.

Provide capability to opt-in for Serilog during generation so that it is already configured.

.NET Boxed is a good example where they allow you to configure what to include or not.

What feature do you like?
Currently, we set up the logging in the startup (Program.cs) of the template. We should make this startup-logger minimal and add another logging configuration later in the Startup/ConfigureServices so we can make use of the !ServiceProvider and IConfiguration for more a advanced logging configuration.

Now, in the integration tests we test the simple possible way of creating a project from the template (without any options).

It would be reasonable if the integration tests consists of several test cases that each creates a new project with one or more options specified and then takes some actions on that new created project to see if the selected options reflect in a changed behavior.

Ex.: when choosing for a authentication mechanism, testing if we indeed have to configure the correct authentication.

We should change our enumeration serialization to use string instead of integers to make it more user friendly.

Expected Outcome

{"entries":{},"status":"Healthy","totalDuration":"00:00:00.0000023"}

Current Outcome

{"entries":{},"status":2,"totalDuration":"00:00:00.0000023"}

Provide capability to opt-in for client cert auth during generation so that it is already configured.

.NET Boxed is a good example where they allow you to configure what to include or not.

Use Application Insights sink from Arcus Observability

Problem

No need to leak information about the web API in the Server: HTTP header, so we need to hide this header from every response.

Proposal

The kestrel options as a boolean called AddServerHeader to configure this.

Resources

https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.server.kestrel.core.kestrelserveroptions.addserverheader?view=aspnetcore-3.0

As of today we log warnings when we generate a project with Shared Access Key auth here:

• https://github.com/arcus-azure/arcus.templates/blob/master/src/Arcus.Templates.WebApi/Startup.cs#L28
• https://github.com/arcus-azure/arcus.templates/blob/master/src/Arcus.Templates.WebApi/Startup.cs#L41

Given the current state of the API is not valid and should not be released, we should switch this so that it gives build errors rather than warnings so that it's clear to users that they have to change something before they can ship their new API.

What do you think @stijnmoreels ?

Provide CI badge in the README

Is your feature request related to a problem? Please describe.
Document generated security mechanism in OpenAPI when applicable.

Describe the solution you'd like
AddSecurityDefinition should be used when configuring OpenAPI docs for API key authentication.

https://github.com/domaindrivendev/Swashbuckle.AspNetCore#add-security-definitions-and-requirements

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Provide a README that clearly states what the project does.

Checklist

• What the focus of the project is

• What features it has

• How to install it

Provide a release pipeline for MyGet.org.

Checklist

• Configure to run for every PR

• Use 'Determine NuGet Package Version' task group to determin package version

• Build the codebase

• Run test suite

• Push all NuGet packages to MyGet.org

Allow users to include appsettings.json via --include-appsettings option.

This is already done when using the CertificateAuth option (#63) but should be usable without it as well.

Define branch policies on the master branch.

It should:

• Build every PR with our CI

• Be approved by 1 person

Change optional features to use camelCasing similar to .NET Core.

See #53 (comment)

What feature would you like?
Currently, we only write log messages to Application Insights but it could be useful if we write to the console as well during Debug.

Especially during development is this a big plus.

Provide correlation by default in our Web API template by plugging in our correlation middleware.

Relates to #10

Switch Web API template to .NET Core 3.1

Provide capability to opt-out for OpenAPI docs, UI & XML docs.

This is because not everybody wants to use that.

Maybe we should have the same naming across the GitHub repo and the source code.
Doesn't matter to me what; but maybe fix this before releasing.

Configure Netlify for creating previews of documentation changes.

This allows us to more easily review documentation changes as a reviewer and also lowers the barrier to make documentation changes.

Checklist

• Create new Netlify site

• Add Netlify configuration

• Enforce checks on branches

Provide capability to opt-in for shared access key during generation so that it is already configured.

.NET Boxed is a good example where they allow you to configure what to include or not.

Hello all,

I have run this on mac, though doubt that this would be relevant information.
Execution steps to create a new WebApi project:

dotnet new arcus-webapi --name ReproApi - au SharedAccessKey -ia true -lo Serilog

But executing this fails with the following exception, so I think there's a mismatch between the actual code / logic and the docs.

Invalid input switch:
  -au
  SharedAccessKey
  -ia
  true
  -lo
  Serilog
Arcus WebAPI (C#)
Author: Arcus
Options:                                                                                                                
  -A|--Authentication  Choose whether to use an authentication mechanism and which authentication to use                
                           SharedAccessKey    - Adds a shared access key authentication mechanism to the web API project
                           None               - No authentication mechanism is added to the web API project             
                       Default: None   

This is the documentation page:

-au|--authentication (default None)
SharedAccessKey: adds shared access key authentication mechanism to the API project
Certificate: adds client certificate authentication mechanism to the API project
JWT: adds JWT (JSON Web Token) authentication mechanism to the API project
None: no authentication configured on the API project.
-ia|--include-appsettings (default false): includes a appsettings.json file to the web API project.
-ec|--exclude-correlation (default false): excludes the capability to correlate between HTTP requests/responses from the API project.
-eo|--exclude-openApi (default false): exclude the ASP.NET OpenAPI docs generation and UI from API project.
-lo|--logging (default Console)
Console: no extra logging mechanism except for the default console logging will be added to the web API project.
Serilog: adds Serilog as logging mechanism with request logging to the web API project.

Provide NuGet badge in the README