Skip to content

Commit cc2cfd1

Browse files
authoredJun 13, 2024
docs: publish v2.0 feature docs (arcus-azure#888)
1 parent 97bff27 commit cc2cfd1

14 files changed

+373
-0
lines changed
 
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: "Azure EventHubs trigger template (Azure Functions)"
3+
layout: default
4+
---
5+
6+
# Azure EventHubs trigger template (Azure Functions)
7+
8+
## Create your first Arcus Azure Functions with Azure EventHubs trigger project
9+
10+
First, install the template from NuGet:
11+
12+
```shell
13+
> dotnet new install Arcus.Templates.AzureFunctions.EventHubs
14+
```
15+
16+
When installed, the template can be created with shortname: `arcus-az-func-eventhubs`:
17+
18+
```shell
19+
> dotnet new arcus-az-func-eventhubs --name Arcus.Demo.AzureFunctions.EventHubs
20+
```
21+
22+
## Features
23+
24+
Creates a starter worker project with by default configured:
25+
26+
* Arcus secret store setup with Azure Key Vault secret provider (see more info [here](https://security.arcus-azure.net/features/secret-store/) on what this includes)
27+
* [Serilog](https://serilog.net/) as logging mechanism with default enrichers ([version](https://observability.arcus-azure.net/features/telemetry-enrichment#version-enricher), [application](https://observability.arcus-azure.net/features/telemetry-enrichment#application-enricher), sinking to Application Insights.
28+
* Dockerfile
29+
30+
### Configuration
31+
32+
And additional features available with options:
33+
* `-es|--exclude-serilog`: Exclude the [Serilog](https://serilog.net/) logging infrastructure in the worker project which includes default enrichers ([version](https://observability.arcus-azure.net/features/telemetry-enrichment#version-enricher) and [application](https://observability.arcus-azure.net/features/telemetry-enrichment#application-enricher)), and sinking to Application Insights.
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
title: "HTTP Trigger template (Azure Functions)"
3+
layout: default
4+
---
5+
6+
# HTTP Trigger template (Azure Functions)
7+
8+
## Create your first Arcus Azure Functions with HTTP Trigger project
9+
10+
First, install the template from NuGet:
11+
12+
```shell
13+
> dotnet new install Arcus.Templates.AzureFunctions.Http
14+
```
15+
16+
When installed, the template can be created with shortname: `arcus-az-func-http`:
17+
18+
```shell
19+
> dotnet new arcus-az-func-http --name Arcus.Demo.AzureFunctions.Http
20+
```
21+
22+
## Features
23+
24+
Creates a starter worker project with by default configured:
25+
26+
* Arcus secret store setup with Azure Key Vault secret provider (see more info [here](https://security.arcus-azure.net/features/secret-store/) on what this includes)
27+
* [Serilog](https://serilog.net/) as logging mechanism with default enrichers ([version](https://observability.arcus-azure.net/features/telemetry-enrichment#version-enricher), [application](https://observability.arcus-azure.net/features/telemetry-enrichment#application-enricher), and [correlation](https://webapi.arcus-azure.net/features/telemetry) when appropriate), sinking to Application Insights.
28+
29+
* Example Azure Function HTTP 'order' trigger with:
30+
* HTTP correlation (see more info [here](https://webapi.arcus-azure.net/features/correlation) on what this includes)
31+
* Request content and header to restrict to JSON content and JSON parsing with data model annotations validation
32+
* General exception handling that results in 500 Internal Server Error
33+
* OpenAPI docs generation and UI (see more info [here](https://github.com/Azure/azure-functions-openapi-extension))
34+
* Dockerfile
35+
36+
### Configuration
37+
38+
And additional features available with options:
39+
40+
* `--include-healthchecks` (default `false`): include a default Health Azure Function and health check services from the project
41+
* `--exclude-openapi` (default `false`): exclude the [Azure Functions OpenAPI docs generation and UI](https://github.com/Azure/azure-functions-openapi-extension) from the project.
42+
* `--exclude-serilog` (default `false`): exclude the [Serilog](https://serilog.net/) logging infrastructure in the Azure Functions project which includes default enrichers ([version](https://observability.arcus-azure.net/features/telemetry-enrichment#version-enricher) and [application](https://observability.arcus-azure.net/features/telemetry-enrichment#application-enricher)), and sinking to Application Insights.
43+
44+
### Security
45+
46+
As part of this template the following HTTP header value(s) are removed for security sake:
47+
* `Server` header * Provides information concerning the web runtime
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: "Azure Service Bus Queue Trigger template (Azure Functions)"
3+
layout: default
4+
---
5+
6+
# Azure Service Bus Queue Trigger template (Azure Functions)
7+
8+
## Create your first Arcus Azure Functions with Azure Service Bus Queue Trigger project
9+
10+
First, install the template from NuGet:
11+
12+
```shell
13+
> dotnet new install Arcus.Templates.AzureFunctions.ServiceBus.Queue
14+
```
15+
16+
When installed, the template can be created with shortname: `arcus-az-func-servicebus-queue`:
17+
18+
```shell
19+
> dotnet new arcus-az-func-servicebus-queue --name Arcus.Demo.AzureFunctions.ServiceBus.Queue
20+
```
21+
22+
## Features
23+
24+
Creates a starter worker project with by default configured:
25+
26+
* Arcus secret store setup with Azure Key Vault secret provider (see more info [here](https://security.arcus-azure.net/features/secret-store/) on what this includes)
27+
* [Serilog](https://serilog.net/) as logging mechanism with default enrichers ([version](https://observability.arcus-azure.net/features/telemetry-enrichment#version-enricher), [application](https://observability.arcus-azure.net/features/telemetry-enrichment#application-enricher), sinking to Application Insights.
28+
* Dockerfile
29+
30+
### Configuration
31+
32+
And additional features available with options:
33+
* `--exclude-serilog`: Exclude the [Serilog](https://serilog.net/) logging infrastructure in the Azure Functions project which includes default enrichers ([version](https://observability.arcus-azure.net/features/telemetry-enrichment#version-enricher) and [application](https://observability.arcus-azure.net/features/telemetry-enrichment#application-enricher)), and sinking to Application Insights.
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: "Azure Service Bus Topic Trigger template (Azure Functions)"
3+
layout: default
4+
---
5+
6+
# Azure Service Bus Topic Trigger template (Azure Functions)
7+
8+
## Create your first Arcus Azure Functions with Azure Service Bus Topic Trigger project
9+
10+
First, install the template from NuGet:
11+
12+
```shell
13+
> dotnet new install Arcus.Templates.AzureFunctions.ServiceBus.Topic
14+
```
15+
16+
When installed, the template can be created with shortname: `arcus-az-func-servicebus-topic`:
17+
18+
```shell
19+
> dotnet new arcus-az-func-servicebus-topic --name Arcus.Demo.AzureFunctions.ServiceBus.Topic
20+
```
21+
22+
## Features
23+
24+
Creates a starter worker project with by default configured:
25+
26+
* Arcus secret store setup with Azure Key Vault secret provider (see more info [here](https://security.arcus-azure.net/features/secret-store/) on what this includes)
27+
* [Serilog](https://serilog.net/) as logging mechanism with default enrichers ([version](https://observability.arcus-azure.net/features/telemetry-enrichment#version-enricher), [application](https://observability.arcus-azure.net/features/telemetry-enrichment#application-enricher), sinking to Application Insights.
28+
* Dockerfile
29+
30+
### Configuration
31+
32+
And additional features available with options:
33+
* `--exclude-serilog`: Exclude the [Serilog](https://serilog.net/) logging infrastructure in the Azure Functions project which includes default enrichers ([version](https://observability.arcus-azure.net/features/telemetry-enrichment#version-enricher) and [application](https://observability.arcus-azure.net/features/telemetry-enrichment#application-enricher)), and sinking to Application Insights.
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: "Azure EventHubs worker template"
3+
layout: default
4+
---
5+
6+
# Azure EventHubs Worker Project Template
7+
8+
## Create Your First Arcus Azure EventHubs Worker Project
9+
10+
First, install the template from NuGet:
11+
12+
```shell
13+
> dotnet new install Arcus.Templates.EventHubs
14+
```
15+
16+
When installed, the template can be created with shortname: `arcus-eventhubs`:
17+
18+
```shell
19+
> dotnet new arcus-eventhubs --name Arcus.Demo.EventHubs
20+
```
21+
22+
## Features
23+
24+
Creates a starter worker project with by default configured:
25+
26+
* TCP health check probe ([official docs](https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/health-checks?view=aspnetcore-2.2) & [Arcus docs](https://messaging.arcus-azure.net/features/tcp-health-probe)).
27+
* Example message pump on Azure EventHubs ([Arcus EventHubs messaging docs](https://messaging.arcus-azure.net/Features/message-handling/event-hubs), [Microsoft EventHubs official docs](https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-dotnet-get-started-with-queues))
28+
* Dockerfile.
29+
30+
### Configuration
31+
32+
And additional features available with options:
33+
* `-es|--exclude-serilog`: Exclude the [Serilog](https://serilog.net/) logging infrastructure in the worker project which includes default enrichers ([version](https://observability.arcus-azure.net/features/telemetry-enrichment#version-enricher) and [application](https://observability.arcus-azure.net/features/telemetry-enrichment#application-enricher)), and sinking to Application Insights.
Loading
Loading
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
title: "Azure Service Bus Queue worker template"
3+
layout: default
4+
---
5+
6+
# Azure Service Bus Queue Worker Project Template
7+
8+
## Create Your First Arcus Azure Service Bus Queue Worker Project
9+
10+
First, install the template from NuGet:
11+
12+
```shell
13+
> dotnet new install Arcus.Templates.ServiceBus.Queue
14+
```
15+
16+
When installed, the template can be created with shortname: `arcus-servicebus-queue`:
17+
18+
```shell
19+
> dotnet new arcus-servicebus-queue --name Arcus.Demo.ServiceBus.Queue
20+
```
21+
22+
23+
## Features
24+
25+
Creates a starter worker project with by default configured:
26+
27+
* TCP health check probe ([official docs](https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/health-checks?view=aspnetcore-2.2) & [Arcus docs](https://messaging.arcus-azure.net/features/tcp-health-probe)).
28+
* Empty message pump on Azure Service Bus Queue ([official docs](https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-dotnet-get-started-with-queues))
29+
* Dockerfile.
30+
31+
### Configuration
32+
33+
And additional features available with options:
34+
* `-es|--exclude-serilog`: Exclude the [Serilog](https://serilog.net/) logging infrastructure in the worker project which includes default enrichers ([version](https://observability.arcus-azure.net/features/telemetry-enrichment#version-enricher) and [application](https://observability.arcus-azure.net/features/telemetry-enrichment#application-enricher)), and sinking to Application Insights.
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
title: "Azure Service Bus Topic worker template"
3+
layout: default
4+
---
5+
6+
# Azure Service Bus Topic Worker Project Template
7+
8+
## Create Your First Arcus Azure Service Bus Topic Worker Project
9+
10+
First, install the template from NuGet:
11+
12+
```shell
13+
> dotnet new install Arcus.Templates.ServiceBus.Topic
14+
```
15+
16+
When installed, the template can be created with shortname: `arcus-servicebus-topic`:
17+
18+
```shell
19+
> dotnet new arcus-servicebus-topic --name Arcus.Demo.ServiceBus.Topic
20+
```
21+
22+
23+
## Features
24+
25+
Creates a starter worker project with by default configured:
26+
27+
* TCP health check probe ([official docs](https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/health-checks?view=aspnetcore-2.2) & [Arcus docs](https://messaging.arcus-azure.net/features/tcp-health-probe)).
28+
* Empty message pump on Azure Service Bus Topic ([official docs](https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-dotnet-how-to-use-topics-subscriptions))
29+
* Dockerfile.
30+
31+
### Configuration
32+
33+
And additional features available with options:
34+
* `-es|--exclude-serilog`: Exclude the [Serilog](https://serilog.net/) logging infrastructure in the worker project which includes default enrichers ([version](https://observability.arcus-azure.net/features/telemetry-enrichment#version-enricher) and [application](https://observability.arcus-azure.net/features/telemetry-enrichment#application-enricher)), and sinking to Application Insights.
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
title: "Using Arcus templates in Visual Studio"
3+
layout: default
4+
---
5+
6+
# Using Arcus templates in Visual Studio
7+
8+
The available .NET project templates in this repository are all available via the command line.
9+
For example:
10+
11+
```shell
12+
PM > dotnet new install Arcus.Templates.WebApi
13+
```
14+
15+
Which will install the template on your machine so it can be used for creating new projects:
16+
17+
```shell
18+
> dotnet new arcus-webapi --name Arcus.Demo.WebAPI
19+
```
20+
21+
However, you can also use our .NET templates in Visual Studio by following these steps:
22+
23+
1. Go to **Tools > Options** in Visual Studio
24+
2. Navigate to **Preview Features**
25+
3. Check the box **Show all .NET Core templates in the New project dialog**
26+
27+
![Show all .NET Core templates in the New project dialog via Tools > Options > Preview Features](img/show-dotnet-templates-in-vs.png)
28+
29+
Once you've enabled it, you can create a new project by using one of our templates:
30+
31+
![Demo of our templates in Visual Studio](img/templates-in-vs.gif)
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
---
2+
title: "Web API template"
3+
layout: default
4+
---
5+
6+
# Web API Project Template
7+
8+
## Create Your First Arcus Web API Project
9+
10+
First, install the template from NuGet:
11+
12+
```shell
13+
> dotnet new install Arcus.Templates.WebApi
14+
```
15+
16+
When installed, the template can be created with shortname: `arcus-webapi`:
17+
18+
```shell
19+
> dotnet new arcus-webapi --name Arcus.Demo.WebAPI
20+
```
21+
22+
## Features
23+
24+
Creates a starter web API project with by default configured:
25+
26+
* Arcus secret store setup with Azure Key Vault secret source ([docs](https://security.arcus-azure.net/features/secret-store))
27+
* Application configuration with environment variables
28+
* Basic health endpoint with [ASP.NET Core health checks](https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/health-checks?view=aspnetcore-2.2) with [OpenAPI support](https://www.codit.eu/blog/documenting-asp-net-core-health-checks-with-openapi/).
29+
* HTTP request tracking with default route `/` omitted ([docs](https://webapi.arcus-azure.net/features/logging))
30+
* HTTP correlation ([docs](https://webapi.arcus-azure.net/features/correlation))
31+
* Global exception handling ([docs](https://webapi.arcus-azure.net/features/logging))
32+
* Docker building file
33+
* Swagger OpenAPI setup
34+
* Serilog setup with Application Insights logging sink ([docs](https://observability.arcus-azure.net/Features/sinks/azure-application-insights))
35+
* Default JSON serialization
36+
37+
### Configuration
38+
39+
And additional features available with options:
40+
41+
* `-au|--authentication` (default `None`)
42+
* `SharedAccessKey`: adds [shared access key authentication](https://webapi.arcus-azure.net/features/security/auth/shared-access-key) mechanism to the API project
43+
* `Certificate`: adds [client certificate authentication](https://webapi.arcus-azure.net/features/security/auth/certificate) mechanism to the API project
44+
* `JWT`: adds JWT (JSON Web Token) authentication mechanism to the API project
45+
* `None`: no authentication configured on the API project.
46+
* `-ia|--include-appsettings` (default `false`): includes a `appsettings.json` file to the web API project.
47+
* `-ec|--exclude-correlation` (default `false`): excludes the [capability to correlate](https://webapi.arcus-azure.net/features/correlation) between HTTP requests/responses from the API project.
48+
* `-eo|--exclude-openApi` (default `false`): exclude the [ASP.NET OpenAPI docs generation and UI](https://docs.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-3.1&tabs=visual-studio) from API project.
49+
* `-lo|--logging` (default `Serilog`)
50+
* `Console`: no extra logging mechanism except for the default console logging will be added to the web API project.
51+
* `Serilog`: adds [Serilog](https://serilog.net/) as logging mechanism with request logging, default enrichers ([version](https://observability.arcus-azure.net/features/telemetry-enrichment#version-enricher), [application](https://observability.arcus-azure.net/features/telemetry-enrichment#application-enricher), and [correlation](https://webapi.arcus-azure.net/features/telemetry) when appropriate), sinking to Application Insights to the web API project.
52+
53+
### Security
54+
55+
As part of this template the following HTTP header(s) are removed for security sake:
56+
* `Server` header * Provides information concerning the Web API runtime
57+
58+
The OpenAPI documentation is available by-default. Be careful of exposing sensitive information with the OpenAPI documentation, only expose what's necessary and hide everything else.
59+
60+
### Health
61+
62+
A default health controller is available that exposes the configured health checks as an aggregated health report.
63+
For more information on application health, see [Microsoft's documentation](https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/health-checks).
64+
65+
The controller doesn't directly exposes Microsoft's `HealthReport` model but uses a custom `ApiHealthReport` model which eliminates the exception details from the original report.
66+
This way the application's health can be exposed in a safe manner without also exposing exception and assembly information to the user.
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
title: "Arcus Templates"
3+
layout: default
4+
permalink: /
5+
redirect_from:
6+
- /index.html
7+
slug: /
8+
sidebar_label: Welcome
9+
sidebar_position: 1
10+
---
11+
12+
# Introduction
13+
Arcus provides a ton of features across multiple libraries. These libraries are build to work together. Background jobs build on top of messaging which uses security features that includes telemetry tracking, and so on. Arcus templates provides several .NET project templates which already includes all the best practices and boilerplate code to kickstart your project. We provide several types of templates to accommodate the most popular types of projects. Look around to find the template of your need, and if missing, [send us your ideas](https://github.com/arcus-azure/arcus.templates/issues/new/choose) for an additional project template.
14+
15+
Want to use our Arcus project templates in Visual Studio? [Learn more in our documentation](./features/using-arcus-templates-in-visualstudio.md)!
16+
17+
# License
18+
This is licensed under The MIT License (MIT). Which means that you can use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the web application. But you always need to state that Codit is the original author of this web application.
19+
20+
*[Full license here](https://github.com/arcus-azure/arcus.templates/blob/master/LICENSE)*
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"tutorialSidebar": [
3+
{
4+
"type": "autogenerated",
5+
"dirName": "."
6+
}
7+
]
8+
}

‎docs/versions.json

+1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
[
2+
"v2.0.0",
23
"v1.1.0",
34
"v1.0.0",
45
"v0.8.0",

0 commit comments

Comments
 (0)
Please sign in to comment.