diff --git a/README.md b/README.md index f06365c8..88ac4c2c 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ Visual Studio Code users may find the [Docs Authoring Pack](https://marketplace. As you get familiar with DocFX, you'll notice the addition of a YAML header in the markdown files. Values in this header let you control page design, as well as set the page's `UID`. With this, you can create `xref` as well as use DocFX's `@` shorthand. Learn more about [linking in DocFX](https://dotnet.github.io/docfx/tutorial/links_and_cross_references.html). > [!NOTE] -> It should be very rare that you hardcode a link to an 'HTML' page with your markdown. Instead, use its `UID` and let the path get calculated, as well as get links validated when building the project. +> It should be very rare that you hardcode a link to an HTML page with your markdown. Instead, use its `UID` and let the path get calculated, as well as get links validated when building the project. ### Page display options @@ -98,7 +98,7 @@ Corresponding entry in `api/v2/toc.yml`: ## Installing DocFX -> [!NOTE] +> [!IMPORTANT] > This project currently expects DocFX version 2.59.4 to be available. ### Install with Chocolatey diff --git a/api/v4/bootstrap/index.md b/api/v4/bootstrap/index.md index f911a19e..c21ef3a9 100644 --- a/api/v4/bootstrap/index.md +++ b/api/v4/bootstrap/index.md @@ -8,7 +8,7 @@ Get started by adding a reference to the AutoConfiguration package (you may want dotnet add package Steeltoe.Bootstrap.AutoConfiguration ``` -After adding the NuGet reference(s), simply include `.AddSteeltoe()` like you see in the code below and you're all set with the basic implementation. +After adding the NuGet reference(s), include `.AddSteeltoe()` like you see in the code below and you're all set with the basic implementation. ```csharp using Steeltoe.Bootstrap.AutoConfiguration; @@ -19,9 +19,9 @@ builder.AddSteeltoe(); ## Supported Steeltoe Packages -`Steeltoe.Bootstrap.AutoConfiguration` is not a meta-package. In order for a Steeltoe feature to be automatically bootstrapped in the application, the appropriate NuGet package must also be referenced. The following table describes the Steeltoe package that is required to light up a feature and any additional packages that may also be installed: +`Steeltoe.Bootstrap.AutoConfiguration` is not a meta-package. For a Steeltoe feature to be automatically bootstrapped in the application, the appropriate NuGet package must also be referenced. The following table describes the Steeltoe package that is required to light up a feature, and any additional packages that may also be installed: -| Feature Description | Steeltoe Package | Additional Packages | +| Feature Description | Steeltoe Package | Additional Packages | | --- | --- | --- | | [Config Server Configuration Provider](../configuration/config-server-provider.md) | `Steeltoe.Configuration.ConfigServer` | Optional: `Steeltoe.Discovery.Eureka` to use discovery-first | | [Cloud Foundry Configuration Provider](../configuration/cloud-foundry-provider.md) |`Steeltoe.Configuration.CloudFoundry` | N/A | @@ -29,7 +29,7 @@ builder.AddSteeltoe(); | [Placeholder Configuration Provider](../configuration/placeholder-provider.md) |`Steeltoe.Configuration.Placeholder` | N/A | | [Encrypted Configuration Provider](../configuration/decryption-provider.md) | `Steeltoe.Configuration.Encryption` | N/A | | [Spring Boot Configuration Provider](../configuration/spring-boot-provider.md) | `Steeltoe.Configuration.SpringBoot` | N/A | -| [Connectors](../connectors/index.md) |`Steeltoe.Connectors` | Required: Supported driver [^1] (MySQL, PostgreSQL, SQL Server, MongoDB, CosmosDB, Redis, RabbitMQ) | +| [Connectors](../connectors/index.md) |`Steeltoe.Connectors` | Required: Supported driver [^1] (MySQL, PostgreSQL, SQL Server, MongoDB, CosmosDB, Redis/Valkey, RabbitMQ) | | [Eureka Service Discovery](../discovery/netflix-eureka.md) |`Steeltoe.Discovery.Eureka` | Optional: `Steeltoe.Management.Endpoint` for health checks | | [Consul Service Discovery](../discovery/hashicorp-consul.md) |`Steeltoe.Discovery.Consul` | N/A | | [Configuration-based Service Discovery](../discovery/configuration-based.md) |`Steeltoe.Discovery.Configuration` | N/A | @@ -38,11 +38,11 @@ builder.AddSteeltoe(); | [Actuators](../management/index.md) | `Steeltoe.Management.Endpoint` | N/A | | [Distributed Tracing](../tracing/index.md) | `Steeltoe.Management.Tracing` | N/A | -[^1]: Individual connector clients will only be configured if a corresponding supported driver NuGet package reference is also included. +[^1]: Individual connector clients are only configured if a corresponding supported driver NuGet package reference is also included. ## Excluding Components -If you wish to exclude a component from the automatic bootstrap process, you may add the feature's assembly name to the exclusions list. One example where this feature would be desired is if you want to control the order in which configuration providers are added. This example shows how to provide exclusions: +If you want to exclude a component from the automatic bootstrap process, you may add the feature's assembly name to the exclusions list. One example where this feature would be desired is if you want to control the order in which configuration providers are added. This example shows how to provide exclusions: ```csharp using Steeltoe.Bootstrap.AutoConfiguration; @@ -52,11 +52,11 @@ builder.AddSteeltoe(assemblyNamesToExclude); ``` > [!TIP] -> The static class `SteeltoeAssemblyNames` enables to easily find the name of any specific assembly to exclude. +> The static class `SteeltoeAssemblyNames` enables you to easily find the name of any specific assembly to exclude. ## Logging inside Configuration Providers -For some Steeltoe components, primarily configuration providers, providing a `LoggerFactory` is required to retrieve logs for debugging. Use the optional parameter to provide one as needed: +For some Steeltoe components, primarily configuration providers, a `LoggerFactory` is required to retrieve logs for debugging. Use the optional parameter to provide one as needed: ```csharp using Microsoft.Extensions.Logging.Debug; @@ -72,7 +72,7 @@ builder.AddSteeltoe(loggerFactory); ``` Alternatively, you can use `BootstrapLoggerFactory`. It logs to the console until the service container has been built. -Once the service container has become available, it automatically upgrades existing loggers to use the application configuration. +After the service container has become available, it automatically upgrades existing loggers to use the application configuration. ```csharp using Steeltoe.Bootstrap.AutoConfiguration; @@ -84,11 +84,11 @@ builder.AddSteeltoe(loggerFactory); ## Limitations -At this time there is no support for: +Currently unsupported: * Features that need to be configured directly in `IApplicationBuilder`, such as Cloud Foundry SSO and JWT. * Features that require a custom type (such as a `DbContext`) for setup. ## Feedback -Love it? Hate it? Want to know more or make a suggestion? Let us know by [filing an issue](https://github.com/SteeltoeOSS/Steeltoe/issues/new/choose), [joining us on slack](https://slack.steeltoe.io/) or [Tweeting at us](https://twitter.com/steeltoeoss) +Love it? Hate it? Want to know more or make a suggestion? Let us know by filing an [issue](https://github.com/SteeltoeOSS/Steeltoe/issues/new/choose), joining us on [Slack](https://slack.steeltoe.io/) or [Tweeting us](https://twitter.com/steeltoeoss) diff --git a/api/v4/configuration/cloud-foundry-provider.md b/api/v4/configuration/cloud-foundry-provider.md index fab58612..d6c3e2e2 100644 --- a/api/v4/configuration/cloud-foundry-provider.md +++ b/api/v4/configuration/cloud-foundry-provider.md @@ -1,16 +1,16 @@ # Cloud Foundry Provider -The Cloud Foundry provider enables the standard Cloud Foundry environment variables (`VCAP_APPLICATION`, `VCAP_SERVICES`, and `CF_*`) to be parsed and accessed as configuration data within a .NET application. +The Cloud Foundry provider enables the standard Cloud Foundry environment variables (`VCAP_APPLICATION`, `VCAP_SERVICES`, and `CF_*`) to be parsed and accessed as configuration data within a .NET application. -Cloud Foundry creates and uses these environment variables to communicate an application's environment and configuration to the application code running inside a container. More specifically, the values found in `VCAP_APPLICATION` provide information about the application's resource limits, routes (URIs), and version numbers, among other things. The `VCAP_SERVICES` environment variable provides information about the external services (databases, caches, and so on) to which the application is bound, along with details on how to contact those services. +Cloud Foundry creates and uses these environment variables to communicate an application's environment and configuration to the application code running inside a container. More specifically, the values found in `VCAP_APPLICATION` provide information about the application's resource limits, routes (URIs), and version numbers, among other things. The `VCAP_SERVICES` environment variable provides information about the external services (databases, caches, and so on) to which the application is bound, along with details for contacting those services. -You can read more information on the Cloud Foundry environment variables at the [Cloud Foundry docs](https://docs.cloudfoundry.org/devguide/deploy-apps/environment-variable.html) website. +For more information about the Cloud Foundry environment variables, see the [Cloud Foundry documentation](https://docs.cloudfoundry.org/devguide/deploy-apps/environment-variable.html). -## Usage +## Using the Cloud Foundry Provider You should have a good understanding of how the [.NET Configuration System](https://learn.microsoft.com/aspnet/core/fundamentals/configuration) works before starting to use this provider. -To use the Steeltoe Cloud Foundry provider, you need to do the following: +To use the Steeltoe Cloud Foundry provider: 1. Add the appropriate NuGet package reference to your project. 1. Add the provider to the host builder or configuration builder. @@ -19,13 +19,13 @@ To use the Steeltoe Cloud Foundry provider, you need to do the following: ### Add NuGet Reference -To use the provider, you need to add a reference to the `Steeltoe.Configuration.CloudFoundry` NuGet package. +To use the provider, add a reference to the `Steeltoe.Configuration.CloudFoundry` NuGet package. ### Add Configuration Provider with Options The `AddCloudFoundryConfiguration()` host builder extension method is the easiest way to set things up. It performs -both of the individual steps described below: add the configuration provider and configure options. -The following example shows how to do so: +both of the individual steps described below: adding the configuration provider and configuring the options. +See the following example: ```csharp using Steeltoe.Configuration.CloudFoundry; @@ -34,7 +34,7 @@ var builder = WebApplication.CreateBuilder(args); builder.AddCloudFoundryConfiguration(); ``` -#### Add Configuration Provider +#### Add Configuration Provider without options If you don't want to use the host builder extension method, the following code shows how to add the Cloud Foundry configuration provider to the `ConfigurationBuilder`: @@ -48,7 +48,7 @@ var configuration = configurationBuilder.Build(); ### Access Configuration Data -Once the configuration has been built, the values from the `VCAP_APPLICATION` and `VCAP_SERVICES` environment variables have been added to the application's configuration data and become available under keys prefixed with `vcap:application` and `vcap:services` respectively. +After the configuration has been built, the values from the `VCAP_APPLICATION` and `VCAP_SERVICES` environment variables have been added to the application's configuration data and become available under keys prefixed with `vcap:application` and `vcap:services`, respectively. You can access the values from the `VCAP_APPLICATION` environment variable settings directly from the `IConfiguration` as follows: @@ -57,9 +57,9 @@ var appName = configuration["vcap:application:application_name"]; var instanceId = configuration["vcap:application:instance_id"]; ``` -A list of all `VCAP_APPLICATION` keys is available in the [VCAP_APPLICATION](https://docs.CloudFoundry.org/devguide/deploy-apps/environment-variable.html#VCAP-APPLICATION) topic of the Cloud Foundry documentation. +A list of all `VCAP_APPLICATION` keys is available in [VCAP_APPLICATION](https://docs.CloudFoundry.org/devguide/deploy-apps/environment-variable.html#VCAP-APPLICATION), in the Cloud Foundry documentation. -You can also directly access the values from the `VCAP_SERVICES` environment variable. For example, to access the information about the first instance of a bound Cloud Foundry service with the name `service-name`, you could code the following: +You can also access the values directly from the `VCAP_SERVICES` environment variable. For example, to access the information about the first instance of a bound Cloud Foundry service with the name `service-name`, you could code the following: ```csharp var name = configuration["vcap:services:service-name:0:name"]; @@ -69,15 +69,15 @@ var uri = configuration["vcap:services:service-name:0:credentials:uri"]; A list of all `VCAP_SERVICES` keys is available in the [VCAP_SERVICES](https://docs.CloudFoundry.org/devguide/deploy-apps/environment-variable.html#VCAP-SERVICES) topic of the Cloud Foundry documentation. > [!NOTE] -> This provider uses the built-in .NET [JSON configuration provider](https://learn.microsoft.com/dotnet/core/extensions/configuration-providers#json-configuration-provider) when parsing the JSON provided in the `VCAP_*` environment variables. As a result, you can expect the exact same key names and behavior as you see when parsing JSON configuration files (such as `appsettings.json`) in your application. +> This provider uses the built-in .NET [JSON configuration provider](https://learn.microsoft.com/dotnet/core/extensions/configuration-providers#json-configuration-provider) when parsing the JSON provided in the `VCAP_*` environment variables. As a result, you can expect exactly the same key names and behavior as you see when parsing JSON configuration files (such as `appsettings.json`) in your application. ### Access Configuration Data as Options -Alternatively, instead of accessing the Cloud Foundry configuration data directly from the configuration, you can use the [Options Pattern](https://learn.microsoft.com/aspnet/core/fundamentals/configuration/options) together with [Dependency Injection](https://learn.microsoft.com/aspnet/core/fundamentals/dependency-injection) to obtain an instance of the option classes into your controllers and views. +Alternatively, instead of accessing the Cloud Foundry configuration data directly from the configuration, you can use the [Options Pattern](https://learn.microsoft.com/aspnet/core/fundamentals/configuration/options) with [Dependency Injection](https://learn.microsoft.com/aspnet/core/fundamentals/dependency-injection) to obtain an instance of the option classes into your controllers and views. The Cloud Foundry provider includes two additional classes, `CloudFoundryApplicationOptions` and `CloudFoundryServicesOptions`. You can configure both to bind to the parsed `VCAP_*` data. -If you're not using the host builder extension method mentioned above, the `AddCloudFoundryOptions()` method can be used to configure the Cloud Foundry option classes. This method binds the parsed `VCAP_*` data to the `CloudFoundryApplicationOptions` and `CloudFoundryServicesOptions` classes. The following example shows how to do so: +If you're not using the host builder extension method described earlier, you can use the `AddCloudFoundryOptions()` method to configure the Cloud Foundry option classes. This method binds the parsed `VCAP_*` data to the `CloudFoundryApplicationOptions` and `CloudFoundryServicesOptions` classes. See the following example: ```csharp using Steeltoe.Configuration.CloudFoundry; @@ -87,7 +87,7 @@ builder.Configuration.AddCloudFoundry(); builder.Services.AddCloudFoundryOptions(); ``` -Once this is done, you can access these configuration objects in the controllers or views of an application by using normal Dependency Injection, as follows: +After this is done, you can access these configuration objects in the controllers or views of an application by using normal Dependency Injection, as follows: ```csharp using Microsoft.AspNetCore.Mvc; diff --git a/api/v4/configuration/config-server-provider.md b/api/v4/configuration/config-server-provider.md index b98c3d3a..a19888be 100644 --- a/api/v4/configuration/config-server-provider.md +++ b/api/v4/configuration/config-server-provider.md @@ -2,13 +2,13 @@ This provider enables the Spring Cloud Config Server to be used as a source of configuration data for a .NET application. -The Spring Cloud Config Server is an application configuration service that gives you a central place to manage an application's configuration values externally across all environments. As an application moves through the deployment pipeline from development to test and into production, you can use the config server to manage the configuration between environments and be certain that the application has everything it needs to run when you migrate it. The config server easily supports labeled versions of environment-specific configurations and is accessible to a wide range of tooling for managing its content. +The Spring Cloud Config Server is an application configuration service that gives you a central place to manage an application's configuration values externally across all environments. As an application moves through the deployment pipeline from development to test and into production, you can use the Config Server to manage the configuration between environments and be certain that the application has everything it needs to run when you migrate it. The Config Server supports labeled versions of environment-specific configurations and is accessible to a wide range of tooling for managing its content. To gain a better understanding of the Spring Cloud Config Server, you should read the [Spring Cloud Config documentation](https://spring.io/projects/spring-cloud-config). In addition to the Quick Start provided later, you can refer to the [Steeltoe ConfigurationProviders](https://github.com/SteeltoeOSS/Samples/tree/main/Configuration/src/ConfigurationProviders) sample application when you need to understand how to use this provider. -## Usage +## Using the Config Server Provider You should know how the [.NET Configuration System](https://learn.microsoft.com/aspnet/core/fundamentals/configuration) works before starting to use this provider. A basic understanding of the `ConfigurationBuilder` and how to add providers to the builder is necessary. @@ -17,20 +17,23 @@ You should also have a good understanding of the [Spring Cloud Config Server](ht To use the Steeltoe provider, you need to do the following: 1. Add the appropriate NuGet package reference to your project. -1. Configure the settings that the Steeltoe provider uses to access the Spring Cloud Config Server. +1. Configure the settings that the Steeltoe provider uses to access Spring Cloud Config Server. 1. Add the provider to the host builder or configuration builder. 1. Optionally, bind the configuration data to a class using the Options Pattern. 1. Inject and use `IConfiguration` or `IOptions<>` to access configuration data. ### Add NuGet Reference -To use the provider, you need to add a reference to the `Steeltoe.Configuration.ConfigServer` NuGet package. +To use the provider, add a reference to the `Steeltoe.Configuration.ConfigServer` NuGet package. ### Configure Settings The most convenient way to configure settings for the provider is to put them in a file and then use one of the other file-based configuration providers to read them. -The following example shows some provider settings that have been put in a JSON file. Only two settings are really necessary. `Spring:Application:Name` configures the "application name" to be `sample`, and `Spring:Cloud:Config:Uri` configures the address of the config server. +The following example shows some provider settings that have been put in a JSON file. Only two settings are required: + +* `Spring:Application:Name` configures the application name to be `sample`. +* `Spring:Cloud:Config:Uri` configures the address of the Config Server. > [!TIP] > The `Spring:Application:Name` key is also used by various other Steeltoe components. @@ -50,40 +53,39 @@ The following example shows some provider settings that have been put in a JSON } ``` -The following table describes all the settings that can be used to configure the behavior of the provider: +The following table describes all the settings that can be used to configure the behavior of the provider. +Each key must be prefixed with `Spring:Cloud:Config:`. | Key | Description | Default | -| --- | --- | --- | -| `Name` | Application name for which to request configuration. | | -| `Enabled` | Enable or disable the config server client. | `true` | -| `Uri` | Comma-separated list of config server endpoints. | `http://localhost:8888` | -| `Env` | Environment or profile used in the server request. | `Production` | -| `ValidateCertificates` | Enable or disable server certificate validation. | `true` | -| `Label` | Comma-separated list of labels to request. | | -| `Timeout` | Time to wait for response from server, in milliseconds. | `60_000` (1 min) | -| `PollingInterval` | How often to check for changes in Config Server. | | -| `Username` | Username for basic authentication. | | -| `Password` | Password for basic authentication. | | -| `FailFast` | Enable or disable failure at startup. | `false` | -| `Headers` | Extra HTTP headers which are added to config server requests. | | -| `Token` | HashiCorp Vault authentication token. | | -| `TokenTtl` | HashiCorp Vault token renewal TTL, in milliseconds. Valid on Cloud Foundry only. | `300_000` (5 min) | -| `TokenRenewRate` | HashiCorp Vault token renewal rate, in milliseconds. Valid on Cloud Foundry only. | `60_000` (1 min) | -| `DisableTokenRenewal` | Enable or disable HashiCorp Vault token renewal. Valid on Cloud Foundry only. | `false` | -| `Retry:Enabled` | Enable or disable retry logic. | `false` | -| `Retry:MaxAttempts` | Max retries if retry enabled. | `6` | -| `Retry:InitialInterval` | Starting interval, in milliseconds. | `1000` | -| `Retry:MaxInterval` | Maximum retry interval, in milliseconds. | `2000` | -| `Retry:Multiplier` | Retry interval multiplier. | `1.1` | -| `ClientId` | OAuth2 client ID when using OAuth security. | | -| `ClientSecret` | OAuth2 client secret when using OAuth security. | | -| `AccessTokenUri` | URI to use to obtain OAuth access token. | | -| `Discovery:Enabled` | Enable or disable the Discovery First feature. | `false` | -| `Discovery:ServiceId` | Config Server service ID to use in Discovery First feature. | `configserver` | -| `Health:Enabled` | Enable or disable config server health check contributor. | `true` | -| `Health:TimeToLive` | Health check contributor cache time to live, in milliseconds. | `300_000` (5 min) | - -As mentioned earlier, all settings above should start with `Spring:Cloud:Config:` +| --- | ----------- | ------- | +| `Name` | Application name for which to request configuration | | +| `Enabled` | Enable or disable the Config Server client | `true` | +| `Uri` | Comma-separated list of Config Server endpoints | `http://localhost:8888` | +| `Env` | Environment or profile used in the server request | `Production` | +| `ValidateCertificates` | Enable or disable server certificate validation | `true` | +| `Label` | Comma-separated list of labels to request | | +| `Timeout` | Time to wait for response from server, in milliseconds | `60_000` (1 min) | +| `PollingInterval` | How often to check for changes in Config Server | | +| `Username` | Username for basic authentication | | +| `Password` | Password for basic authentication | | +| `FailFast` | Enable or disable failure at startup | `false` | +| `Headers` | Extra HTTP headers that are added to Config Server requests | | +| `Token` | HashiCorp Vault authentication token | | +| `TokenTtl` | HashiCorp Vault token renewal TTL, in milliseconds (used on Cloud Foundry only) | `300_000` (5 min) | +| `TokenRenewRate` | HashiCorp Vault token renewal rate, in milliseconds (used on Cloud Foundry only) | `60_000` (1 min) | +| `DisableTokenRenewal` | Enable or disable HashiCorp Vault token renewal (used on Cloud Foundry only) | `false` | +| `Retry:Enabled` | Enable or disable retry logic | `false` | +| `Retry:MaxAttempts` | Max retries if retry enabled | `6` | +| `Retry:InitialInterval` | Starting interval, in milliseconds | `1000` | +| `Retry:MaxInterval` | Maximum retry interval, in milliseconds | `2000` | +| `Retry:Multiplier` | Retry interval multiplier | `1.1` | +| `ClientId` | OAuth2 client ID when using OAuth security | | +| `ClientSecret` | OAuth2 client secret when using OAuth security | | +| `AccessTokenUri` | URI to use to obtain OAuth access token | | +| `Discovery:Enabled` | Enable or disable the Discovery First feature | `false` | +| `Discovery:ServiceId` | Config Server service ID to use in Discovery First feature | `configserver` | +| `Health:Enabled` | Enable or disable Config Server health check contributor | `true` | +| `Health:TimeToLive` | Health check contributor cache time to live, in milliseconds | `300_000` (5 min) | > [!TIP] > If you use self-signed certificates on Cloud Foundry, you might run into certificate validation issues when pushing an application. @@ -91,16 +93,16 @@ As mentioned earlier, all settings above should start with `Spring:Cloud:Config: ### Add Configuration Provider -Once the provider's settings have been defined and put in a file (such as a JSON file), the next step is to read them and make them available to the provider. +After the provider's settings have been defined and put in a file (such as a JSON file), the next step is to read them and make them available to the provider. In the next C# example, the provider's configuration settings from the preceding example are put in the `appsettings.json` file included with the application. Then, by using the .NET JSON configuration provider, we can read the settings by adding the JSON provider to the configuration builder (`AddJsonFile("appsettings.json")`). -Then, after the JSON provider has been added, you can add the config server provider to the builder. Steeltoe provides an extension method, `AddConfigServer()`, that you can use to do so. +Then, after the JSON provider has been added, you can add the Config Server provider to the builder. Steeltoe provides an extension method, `AddConfigServer()`, that you can use to do this. -Because the JSON provider that reads `appsettings.json` has been added *before* the config server provider, the JSON-based settings become available to the Steeltoe provider. Note that you do not have to use JSON for the Steeltoe settings. You can use any of the other off-the-shelf configuration providers for the settings (such as INI files, environment variables, and so on). +Because the JSON provider that reads `appsettings.json` has been added *before* the Config Server provider, the JSON-based settings become available to the Steeltoe provider. Note that you do not have to use JSON for the Steeltoe settings. You can use any of the other off-the-shelf configuration providers for the settings (such as INI files, environment variables, and so on). -> [!CAUTION] -> You need to use the `Add*()` methods to add the source of the config server clients settings (`AddJsonFile(..)`) *before* you use `AddConfigServer(..)`. Otherwise, the settings are not picked up and used. +> [!IMPORTANT] +> You must use the `Add*()` methods to add the source of the Config Server clients settings, such as `AddJsonFile()`, *before* you use `AddConfigServer(..)`. Otherwise, the settings are not picked up and used. The following sample shows how to add a configuration provider: @@ -129,7 +131,7 @@ builder.AddConfigServer(); When you want to use a Config Server on Cloud Foundry and you have installed [Spring Cloud Services](https://github.com/SteeltoeOSS/Samples/blob/main/CommonTasks.md#provision-sccs-on-cloud-foundry), you can create and bind an instance of it to your application by using the Cloud Foundry CLI, as follows: -```bash +```shell # Create a Config Server instance named `myConfigServer` cf create-service p-config-server standard myConfigServer @@ -143,7 +145,7 @@ cf bind-service myApp myConfigServer cf restage myApp ``` -Once the service is bound to the application, the config server settings are available and can be set up in `VCAP_SERVICES`. +After the service is bound to the application, the Config Server settings are available and can be set up in `VCAP_SERVICES`. Then, when you push the application, the Steeltoe provider takes the settings from the service binding and merges those settings with the settings that you have provided through other configuration mechanisms (such as `appsettings.json`). @@ -153,12 +155,12 @@ If there are any merge conflicts, the last provider added to the configuration t When the `ConfigurationBuilder` builds the configuration, the Config Server client makes the appropriate REST calls to the Config Server and retrieves the configuration values based on the settings that have been provided. -If there are any errors or problems accessing the server, the application continues to initialize, but the values from the server are not retrieved. If this is not the behavior you want, you should set `Spring:Cloud:Config:FailFast` to `true`. Once that is done, the application fails to start if problems occur during the retrieval. +If there are any errors or problems accessing the server, the application continues to initialize, but the values from the server are not retrieved. If this is not the behavior you want, set `Spring:Cloud:Config:FailFast` to `true`. After that is done, the application fails to start if problems occur during the retrieval. > [!TIP] -> To diagnose startup errors, activate bootstrap logging as described [here](../bootstrap/index.md#logging-inside-configuration-providers). +> To diagnose startup errors, activate bootstrap logging as described in [Application Bootstrapping](../bootstrap/index.md#logging-inside-configuration-providers). -After the configuration has been built, you can access the retrieved data directly by using `IConfiguration`. The following example shows how to do so: +After the configuration has been built, you can access the retrieved data directly by using `IConfiguration`. See the following example: ```csharp var configuration = configurationBuilder.Build(); @@ -166,57 +168,57 @@ string? property1 = configuration["example:property1"]; string? property2 = configuration["example:property2"]; ``` -Alternatively, you can create a class to hold your configuration data and then use the [Options Pattern](https://learn.microsoft.com/aspnet/core/fundamentals/configuration/options) together with [Dependency Injection](https://learn.microsoft.com/aspnet/core/fundamentals/dependency-injection) to obtain an instance of your options class into your controllers and views. +Alternatively, you can create a class to hold your configuration data and then use the [Options Pattern](https://learn.microsoft.com/aspnet/core/fundamentals/configuration/options) with [Dependency Injection](https://learn.microsoft.com/aspnet/core/fundamentals/dependency-injection) to get an instance of your options class into your controllers and views. -To do so, first create a class representing the configuration data you expect to retrieve from the server, as follows: +1. First create a class representing the configuration data you expect to retrieve from the server, as follows: -```csharp -public class ExampleOptions -{ - public string? Property1 { get; set; } - public string? Property2 { get; set; } -} -``` + ```csharp + public class ExampleOptions + { + public string? Property1 { get; set; } + public string? Property2 { get; set; } + } + ``` -Next, use the code below to bind the `example:*` values to an instance of the `ExampleOptions` class. +1. Bind the `example:*` values to an instance of the `ExampleOptions` class using the following code. -```csharp -var builder = WebApplication.CreateBuilder(args); -builder.Services.AddOptions().BindConfiguration("example"); -``` + ```csharp + var builder = WebApplication.CreateBuilder(args); + builder.Services.AddOptions().BindConfiguration("example"); + ``` -After this has been done, you can gain access to the data in your `Controller` or `View` through dependency injection. The following example shows how to do so: +1. Now you can gain access to the data in your `Controller` or `View` through dependency injection. The following example shows how to do this: -```csharp -using Microsoft.AspNetCore.Mvc; -using Microsoft.Extensions.Options; + ```csharp + using Microsoft.AspNetCore.Mvc; + using Microsoft.Extensions.Options; -public class HomeController(IOptionsSnapshot optionsSnapshot) - : Controller -{ - public IActionResult Index() + public class HomeController(IOptionsSnapshot optionsSnapshot) + : Controller { - ExampleOptions options = optionsSnapshot.Value; - - ViewData["property1"] = options.Property1; - ViewData["property2"] = options.Property2; - ViewData["property2"] = options.Property2; - return View(); + public IActionResult Index() + { + ExampleOptions options = optionsSnapshot.Value; + + ViewData["property1"] = options.Property1; + ViewData["property2"] = options.Property2; + ViewData["property2"] = options.Property2; + return View(); + } } -} -``` + ``` ### Configuring Discovery First -The default behavior for the Steeltoe Config Client is to access the Config Server through the `Spring:Cloud:Config:Uri` configuration setting. This of course requires that the application contains an `appsettings.json` or an environment variable with the Config Server's address set in `Spring:Cloud:Config:Uri`. This mode of operation, the default, is called "Config First". +The default behavior for the Steeltoe Config Client is to access the Config Server through the `Spring:Cloud:Config:Uri` configuration setting. This requires that the application contains an `appsettings.json` or an environment variable with the Config Server's address set in `Spring:Cloud:Config:Uri`. This mode of operation, the default, is called "Config First." -Alternatively, you can set up your Config Server to register with a discovery service such as Netflix Eureka. This enables your application to look up the address of the Config Server by using a discovery service instead of configuring it in `appsettings.json`. Note that you have to specifically configure your Config Server deployment to register with a discovery service, as this does not happen automatically. See the Spring Cloud Config Server documentation for how to do so. +Alternatively, you can set up your Config Server to register with a discovery service such as Netflix Eureka. This enables your application to look up the address of the Config Server by using a discovery service instead of configuring it in `appsettings.json`. Note that you have to specifically configure your Config Server deployment to register with a discovery service; this does not happen automatically. See the Spring Cloud Config Server documentation for how to do this. -However, with the default "Config First" mode of the Steeltoe client, you are not able to take advantage of the Config Server registration unless you change the clients' mode of operation to "Discovery First". To do so: +However, with the default "Config First" mode of the Steeltoe client, you cannot take advantage of the Config Server registration unless you change the clients' mode of operation to "Discovery First." To do this: -1. If your application does not use a service discovery service, you need to configure your application to do so. See the [Steeltoe Discovery documentation](../discovery/initialize-discovery-client.md) for the details on how. At a minimum, you need to configure the Eureka Server address. +1. If your application does not use a service discovery service, you need to configure your application to do so. See the [Steeltoe Discovery documentation](../discovery/initialize-discovery-client.md) for instructions. At a minimum, you must configure the Eureka Server address. 1. Change the Steeltoe Config Server client setting `Spring:Cloud:Config:Discovery:Enabled` to `true` (the default is `false`). -1. If your Config Server is registered with Eureka using a name other than "configserver", use `Spring:Cloud:Config:Discovery:ServiceId` to specify the name used by the client for lookup. +1. If your Config Server is registered with Eureka using a name other than `configserver`, use `Spring:Cloud:Config:Discovery:ServiceId` to specify the name used by the client for lookup. Note that the cost for using this mode of operation is an extra network roundtrip on startup to locate the Config Server service registration. The benefit is that, as long as the discovery service is at a fixed point, the Config Server can change its address and no changes to applications are needed. @@ -238,15 +240,19 @@ In some cases, you may want to fail the startup of your application if it cannot If you expect that the Config Server may occasionally be unavailable when your application starts, you can make it keep trying after a failure. -First, you need to set `Spring:Cloud:Config:FailFast` to `true`. Then you need to enable retry by setting `Spring:Cloud:Config:Retry:Enabled` to `true`. +1. First, set `Spring:Cloud:Config:FailFast` to `true`. +1. Then, enable retry by setting `Spring:Cloud:Config:Retry:Enabled` to `true`. -The default behavior is to retry six times with an initial back-off interval of 1000ms and an exponential multiplier of 1.1 for subsequent back-offs. You can configure these settings (and others) by setting the `Spring:Cloud:Config:Retry:*` configuration settings described earlier. +The default behavior is to retry six times with an initial back-off interval of 1000 ms and an exponential multiplier of 1.1 for subsequent back-offs. You can configure these settings (and others) by setting the `Spring:Cloud:Config:Retry:*` configuration settings described earlier. ### Configuring Multiple URLs -To ensure high availability when you have multiple instances of Config Server deployed and expect one or more instances to be unavailable from time to time, you can either specify multiple URLs as a comma-separated list for `Spring:Cloud:Config:Uri` or have all your instances register in a Service Registry such as Eureka (if you use "Discovery First" mode). +To ensure high availability when you have multiple instances of Config Server deployed, and you expect one or more instances to be unavailable from time to time, you can do one of the following: + +* Specify multiple URLs as a comma-separated list for `Spring:Cloud:Config:Uri` +* Have all your instances register in a Service Registry such as Eureka (if you use "Discovery First" mode) -Note that doing so ensures high availability only when the Config Server is not running or responding (for example, when the server has exited or when a connection timeout has occurred). For example, if the Config Server returns a 500 (Internal Server Error) response or the Steeltoe client receives a 401 from the Config Server (due to bad credentials or other causes), the client does not try to fetch properties from other URLs. An error of that kind indicates a user issue rather than an availability problem. +Note that this ensures high availability only when the Config Server is not running or responding (for example, when the server has exited or when a connection timeout has occurred). For example, if the Config Server returns a 500 (Internal Server Error) response or the Steeltoe client receives a 401 from the Config Server (due to bad credentials or other causes), the client does not try to fetch properties from other URLs. An error of that kind indicates a user issue rather than an availability problem. If you use HTTP basic auth security on your Config Server, it is possible to use per-Config Server auth credentials by embedding the credentials in each URL you specify for the `Spring:Cloud:Config:Uri` setting. If you use any other kind of security mechanism, you cannot currently use per-Config Server authentication and authorization. @@ -278,4 +284,4 @@ Aside from PEM files, Steeltoe supports a single file in PKCS#12 format: ``` > [!TIP] -> A single certificate can be shared with both Config Server and Eureka, by using the key "Certificates" instead of "Certificates:ConfigServer". +> A single certificate can be shared with both Config Server and Eureka by using the key `Certificates` instead of `Certificates:ConfigServer`. diff --git a/api/v4/configuration/decryption-provider.md b/api/v4/configuration/decryption-provider.md index 52d50226..3c83421a 100644 --- a/api/v4/configuration/decryption-provider.md +++ b/api/v4/configuration/decryption-provider.md @@ -1,14 +1,15 @@ # Decryption Provider The decryption provider decrypts secrets generated by the Spring Cloud Config Server encryption method. For more details on generating secrets, -you should read the [Spring Cloud documentation](https://cloud.spring.io/spring-cloud-static/spring-cloud.html#_encryption_and_decryption_2) and the [Spring Cloud Config Server documentation](https://docs.spring.io/spring-cloud-config/docs/current/reference/html/#_encryption_and_decryption) -on encrypting and decrypting. +see the [Spring Cloud documentation](https://cloud.spring.io/spring-cloud-static/spring-cloud.html#_encryption_and_decryption_2) and the [Spring Cloud Config Server documentation](https://docs.spring.io/spring-cloud-config/docs/current/reference/html/#_encryption_and_decryption) +about encrypting and decrypting. The two main use cases for the decryption provider are: + - Decrypting encrypted secrets hosted by Config Server - Storing encrypted secrets in a git repository -To use the provider, you need to add a reference to the `Steeltoe.Configuration.Encryption` NuGet package. +To use the provider, add a reference to the `Steeltoe.Configuration.Encryption` NuGet package. Then the decryption provider can be enabled as follows: ```csharp @@ -18,9 +19,9 @@ var builder = WebApplication.CreateBuilder(args); builder.Configuration.AddDecryption(); ``` -This will use the Spring Cloud Config encryption mechanism. +This uses the Spring Cloud Config encryption mechanism. -Any configuration value prefixed with `{cipher}` will be decrypted using the configured key: +Any configuration value prefixed with `{cipher}` is decrypted using the configured key: ```json { @@ -28,53 +29,54 @@ Any configuration value prefixed with `{cipher}` will be decrypted using the con } ``` -To decrypt secrets, the decryption provider needs to be configured to match the encryption settings. +To decrypt secrets, the decryption provider must be configured to match the encryption settings. There are two types of encryption: symmetric and asymmetric. -For symmetric encryption, a shared key is used to decrypt the secrets: -```json -{ - "Encrypt": { - "Enabled": true, - "Key": "12345678901234567890" - } -} -``` +* For symmetric encryption, a shared key is used to decrypt the secrets: -> [!CAUTION] -> The shared key should not be part of any source code repository, but should be passed in some other way to the application. + ```json + { + "Encrypt": { + "Enabled": true, + "Key": "12345678901234567890" + } + } + ``` -For asymmetric encryption, the configuration should be as follows: + > [!CAUTION] + > The shared key should not be part of any source code repository, but should be passed to the application in some other way. -```json -{ - "Encrypt": { - "Enabled": true, - "KeyStore": { - "Location": "path/to/keystore", - "Password": "keystore_password", - "Alias": "keyalias" +* For asymmetric encryption, the configuration should be as follows: + + ```json + { + "Encrypt": { + "Enabled": true, + "KeyStore": { + "Location": "path/to/keystore", + "Password": "keystore_password", + "Alias": "keyalias" + } + } } - } -} -``` + ``` -> [!CAUTION] -> The password and the keystore file should not be part of any source code repository, but should be passed in some other way to the application. + > [!CAUTION] + > The password and the keystore file should not be part of any source code repository, but should be passed to the application in some other way. The following table describes the configuration settings that you can apply to the decryption provider: | Key | Description | Default | -| --- | --- | --- | -| `Encrypt:Enabled` | Enable decryption of encrypted `{cipher}` values. | `false` | -| `Encrypt:Rsa:Strong` | When set to `true`, the "strong" GCM AES algorithm is used. Otherwise, the standard CBC algorithm is used. | `false` | -| `Encrypt:Rsa:Salt` | Salt for the random secret used to encrypt cipher text. | `deadbeef` | -| `Encrypt:Rsa:Algorithm` | The RSA algorithm to use (`DEFAULT` or `OAEP`). | `DEFAULT` | -| `Encrypt:KeyStore:Location` | Location of the keystore file. Only PKCS12 store is supported. | | -| `Encrypt:KeyStore:Password` | Password that locks the keystore. | | -| `Encrypt:KeyStore:Alias` | Alias for a key in the store. | | -| `Encrypt:Key` | A symmetric key. As a stronger alternative, consider using a keystore. | | +| --- | ----------- | ------- | +| `Encrypt:Enabled` | Enable decryption of encrypted `{cipher}` values | `false` | +| `Encrypt:Rsa:Strong` | When set to `true`, the "strong" GCM AES algorithm is used; otherwise, the standard CBC algorithm is used | `false` | +| `Encrypt:Rsa:Salt` | Salt for the random secret used to encrypt cipher text | `deadbeef` | +| `Encrypt:Rsa:Algorithm` | The RSA algorithm to use (`DEFAULT` or `OAEP`) | `DEFAULT` | +| `Encrypt:KeyStore:Location` | Location of the keystore file (PKCS12 store is supported) | | +| `Encrypt:KeyStore:Password` | Password that locks the keystore | | +| `Encrypt:KeyStore:Alias` | Alias for a key in the store | | +| `Encrypt:Key` | A symmetric key; as a stronger alternative, consider using a keystore | | ## Custom encryption @@ -106,4 +108,4 @@ builder.Configuration.AddDecryption(new ExampleTextDecryptor(), NullLoggerFactor ``` > [!WARNING] -> Creating encryption algorithms is notoriously difficult. Only use this if you know what you are doing. +> Creating encryption algorithms is notoriously difficult. Use this only if you know what you are doing. diff --git a/api/v4/configuration/index.md b/api/v4/configuration/index.md index f21f55e4..89c507a4 100644 --- a/api/v4/configuration/index.md +++ b/api/v4/configuration/index.md @@ -11,15 +11,15 @@ Each value contained in the configuration is tied to a string-typed key or name. * Environment variables * Custom providers -To better understand .NET configuration services, you should read the [ASP.NET Core documentation](https://learn.microsoft.com/aspnet/core/fundamentals/configuration). Note that, while the documentation link suggests this service is tied to ASP.NET Core, it is not. It can be used in many different application types, including Console, ASP.NET 4.x., UWP, and others. +To better understand .NET configuration services, see the [ASP.NET Core documentation](https://learn.microsoft.com/aspnet/core/fundamentals/configuration). Note that, while the documentation link suggests this service is tied to ASP.NET Core, it is not. It can be used in many different application types, including Console, ASP.NET 4.x., UWP, and others. -Steeltoe adds additional configuration providers to the preceding list: +Steeltoe adds the following configuration providers to the preceding list: -* Cloud Foundry (JSON from the `VCAP_APPLICATION` and `VCAP_SERVICES` environment variables) * Spring Cloud Config Server +* Random value generator * Placeholder resolvers * Decryption of encrypted values -* Random value generator +* Cloud Foundry (JSON from the `VCAP_APPLICATION` and `VCAP_SERVICES` environment variables) * Spring Boot configuration -The following sections provide more detail on each of these Steeltoe providers. +The following sections provide more detail about each of these Steeltoe providers. diff --git a/api/v4/configuration/placeholder-provider.md b/api/v4/configuration/placeholder-provider.md index 95a0930f..2c07a03c 100644 --- a/api/v4/configuration/placeholder-provider.md +++ b/api/v4/configuration/placeholder-provider.md @@ -2,15 +2,15 @@ The placeholder resolver enables usage of `${....}` placeholders in your configuration. The provider lets you define configuration values as placeholders and have them be substituted with evaluated values at runtime during configuration access, based on the values of other configuration keys. -A placeholder takes the form of `${key:subkey1:subkey2?defaultValue}`, where `key:subkey1:subkey2` represents another key in the configuration. At runtime, when you access a configuration key whose value contains a placeholder, the resolver is called to substitute the placeholder with a value that exists in the configuration. If no value is found at the placeholder key, the placeholder is returned unresolved. But if a default value is specified in the placeholder, that default value is returned instead. +A placeholder takes the form of `${key:subkey1:subkey2?defaultValue}`, where `key:subkey1:subkey2` represents another key in the configuration. At runtime, when you access a configuration key for which the value contains a placeholder, the resolver is called to substitute the placeholder with a value that exists in the configuration. If no value is found at the placeholder key, the placeholder is returned unresolved. But if a default value is specified in the placeholder, that default value is returned instead. Note that placeholder defaults (for example, `defaultValue`) can also be defined to be placeholders, and they are resolved as well. -## Usage +## Using the Placeholder Provider You should have a good understanding of how the [.NET Configuration System](https://learn.microsoft.com/aspnet/core/fundamentals/configuration) works before starting to use this provider. -To use the Steeltoe placeholder resolver provider, you need to: +To use the Steeltoe placeholder resolver provider: 1. Add the appropriate NuGet package reference to your project. 1. Add the provider to the Configuration Builder. @@ -18,11 +18,11 @@ To use the Steeltoe placeholder resolver provider, you need to: ### Add NuGet Reference -To use the provider, you need to add a reference to the `Steeltoe.Configuration.Placeholder` NuGet package. +To use the provider, add a reference to the `Steeltoe.Configuration.Placeholder` NuGet package. ### Add Configuration Provider -To have placeholders resolved when accessing your configuration data, you need to add the placeholder resolver provider to the `ConfigurationBuilder`. +To have placeholders resolved when accessing your configuration data, add the placeholder resolver provider to the `ConfigurationBuilder`. ```csharp using Steeltoe.Configuration.Placeholder; @@ -33,11 +33,11 @@ builder.Configuration.AddPlaceholderResolver(); > [!IMPORTANT] > The placeholder resolver works by wrapping and replacing (effectively taking ownership of) all existing configuration sources already added to the `ConfigurationBuilder`. -> As a result, you typically will want to add it as the *last* provider. +> As a result, you typically want to add it as the *last* provider. ### Access Configuration Data -Once the configuration has been built, the placeholder resolver is used to resolve any placeholders as you access your configuration data. You can access the configuration data as you normally would, and the resolver tries to resolve any placeholder before returning the value for the key requested. +After the configuration has been built, the placeholder resolver is used to resolve any placeholders as you access your configuration data. You can access the configuration data as you normally would, and the resolver tries to resolve any placeholder before returning the value for the key requested. Consider the following `appsettings.json` file: @@ -53,7 +53,6 @@ Consider the following `appsettings.json` file: } } } - ... } ``` diff --git a/api/v4/configuration/random-value-provider.md b/api/v4/configuration/random-value-provider.md index 745324f5..279e8b26 100644 --- a/api/v4/configuration/random-value-provider.md +++ b/api/v4/configuration/random-value-provider.md @@ -2,7 +2,7 @@ Sometimes, you might need to generate random values as part of your application's configuration values. -The Steeltoe random value generator is a configuration provider that you can use to do just that. It can produce integers, longs, GUIDs, or strings, as the following examples show: +The Steeltoe random value generator is a configuration provider that you can use to produce integers, longs, GUIDs, or strings, as the following examples show: ```csharp string? randomValue = builder.Configuration["random:value"]; @@ -13,7 +13,7 @@ int randomNumberLessThanTen = builder.Configuration.GetValue("random:int(10 int randomNumberInRange = builder.Configuration.GetValue("random:int[1024,65536]"); ``` -You can also use the generator together with property placeholders. For example, consider the following `appsettings.json`: +You can also use the generator with property placeholders. For example, consider the following `appsettings.json`: ```json { @@ -28,11 +28,11 @@ You can also use the generator together with property placeholders. For example, } ``` -## Usage +## Using the Random Value Provider You should have a good understanding of how the [.NET Configuration System](https://learn.microsoft.com/aspnet/core/fundamentals/configuration) works before starting to use this provider. -To use the Steeltoe random value provider, you need to: +To use the Steeltoe random value provider: 1. Add the appropriate NuGet package reference to your project. 1. Add the provider to the Configuration Builder. @@ -40,13 +40,11 @@ To use the Steeltoe random value provider, you need to: ### Add NuGet Reference -To use the provider, you need to add a reference to the `Steeltoe.Configuration.RandomValue` NuGet package. +To use the provider, add a reference to the `Steeltoe.Configuration.RandomValue` NuGet package. ### Add Configuration Provider -To have the ability to generate random values from the configuration, you need to add the random value provider to the `ConfigurationBuilder`. - -The following example shows how to do so: +To have the ability to generate random values from the configuration, add the random value provider to the `ConfigurationBuilder`. See the following example: ```csharp using Steeltoe.Configuration.RandomValue; @@ -56,11 +54,11 @@ builder.Configuration.AddRandomValueSource(); ``` > [!TIP] -> If you wish to generate random values as part of using placeholders, you need to add the random value provider to the builder *before* you add the placeholder resolver. +> To generate random values as part of using placeholders, add the random value provider to the builder *before* you add the placeholder resolver. ### Access Random Value Data -Once the configuration has been built, the random value provider can be used to generate values. You can access the configuration data by using the appropriate `random` keys. +After the configuration has been built, the random value provider can be used to generate values. You can access the configuration data by using the appropriate `random` keys. Consider the following `HomeController` example: diff --git a/api/v4/configuration/spring-boot-provider.md b/api/v4/configuration/spring-boot-provider.md index eb339304..0de0f8e9 100644 --- a/api/v4/configuration/spring-boot-provider.md +++ b/api/v4/configuration/spring-boot-provider.md @@ -5,11 +5,11 @@ This provider exists for interoperability with Spring Boot environment variables The Steeltoe Spring Boot configuration provider reads the JSON in the `SPRING_BOOT_APPLICATION` environment variable and adds its contents to the configuration. It does the same for command-line arguments. In both cases, any `.` delimiters in configuration keys are converted to `:`, which is the configuration key separator used by .NET. Likewise, Spring array syntax, such as `[1]`, is converted to .NET array syntax `:1`. -## Usage +## Using the Spring Boot Provider You should have a good understanding of how the [.NET Configuration System](https://learn.microsoft.com/aspnet/core/fundamentals/configuration) works before starting to use this provider. -To use the Steeltoe Spring Boot provider, you need to: +To use the Steeltoe Spring Boot provider: 1. Add the appropriate NuGet package reference to your project. 1. Add the provider to the Configuration Builder. @@ -17,13 +17,13 @@ To use the Steeltoe Spring Boot provider, you need to: ### Add NuGet Reference -To use the provider, you need to add a reference to the `Steeltoe.Configuration.SpringBoot` NuGet package. +To use the provider, add a reference to the `Steeltoe.Configuration.SpringBoot` NuGet package. ### Add Configuration Provider -To access Spring Boot configuration data, you need to add the Spring Boot provider to the `ConfigurationBuilder`. +To access Spring Boot configuration data, add the Spring Boot provider to the `ConfigurationBuilder`. -The following example shows how to do so: +See the following example: ```csharp using Steeltoe.Configuration.SpringBoot; @@ -35,7 +35,7 @@ builder.Configuration.AddSpringBootFromCommandLine(args); ### Access Spring Boot Data -Once the configuration has been built, the Spring Boot provider can be used to access Spring-style keys in .NET syntax. +After the configuration has been built, you can use the Spring Boot provider to access Spring-style keys in .NET syntax. For example: ```csharp diff --git a/api/v4/connectors/cosmosdb.md b/api/v4/connectors/cosmosdb.md index 351130a0..01c91cd3 100644 --- a/api/v4/connectors/cosmosdb.md +++ b/api/v4/connectors/cosmosdb.md @@ -2,11 +2,12 @@ This connector simplifies accessing [Azure CosmosDB](https://azure.microsoft.com/products/cosmos-db/) databases. It supports the following .NET drivers: -- [Microsoft.Azure.Cosmos](https://www.nuget.org/packages/Microsoft.Azure.Cosmos), which provides a `CosmosClient`. -The remainder of this page assumes you're familiar with the [basic concepts of Steeltoe Connectors](./usage.md). +- [Microsoft.Azure.Cosmos](https://www.nuget.org/packages/Microsoft.Azure.Cosmos), which provides a `CosmosClient` -## Usage +The remainder of this topic assumes that you are familiar with the basic concepts of Steeltoe Connectors. See [Overview](./usage.md) for more information. + +## Using the CosmosDB connector To use this connector: @@ -24,7 +25,7 @@ Also add a NuGet reference to one of the .NET drivers listed above, as you would ### Configure connection string -The CosmosDB connection string can be obtained as described [here](https://learn.microsoft.com/azure/cosmos-db/nosql/how-to-dotnet-get-started#retrieve-your-account-connection-string). +The CosmosDB connection string can be obtained as described in the [Microsoft documentation](https://learn.microsoft.com/azure/cosmos-db/nosql/how-to-dotnet-get-started#retrieve-your-account-connection-string). The following example `appsettings.json` uses the emulator: @@ -43,12 +44,12 @@ The following example `appsettings.json` uses the emulator: } ``` -Notice this configuration file contains the database name, in addition to the connection string. This value is exposed +Notice that this configuration file contains the database name, in addition to the connection string. This value is exposed as `CosmosDbOptions.Database`. ### Initialize Steeltoe Connector -Update your `Program.cs` as below to initialize the Connector: +Update your `Program.cs` to initialize the Connector: ```csharp using Steeltoe.Connectors.CosmosDb; @@ -59,75 +60,79 @@ builder.AddCosmosDb(); ### Use CosmosClient -Start by defining a class that contains container data: -```csharp -using Newtonsoft.Json; +To retrieve data from CosmosDB in your app, use the following steps: -public class SampleObject -{ - [JsonProperty(PropertyName = "id")] - public string Id { get; set; } +1. Define a class that contains container data: - public string? Text { get; set; } -} -``` + ```csharp + using Newtonsoft.Json; -To obtain a `CosmosClient` instance in your application, inject the Steeltoe factory in a controller or view: + public class SampleObject + { + [JsonProperty(PropertyName = "id")] + public string Id { get; set; } -```csharp -using Microsoft.AspNetCore.Mvc; -using Microsoft.Azure.Cosmos; -using Microsoft.Azure.Cosmos.Linq; -using Steeltoe.Connectors; -using Steeltoe.Connectors.CosmosDb; + public string? Text { get; set; } + } + ``` -public class HomeController : Controller -{ - public async Task Index( - [FromServices] ConnectorFactory connectorFactory) - { - var connector = connectorFactory.Get(); - CosmosClient client = connector.GetConnection(); +1. To obtain a `CosmosClient` instance in your application, inject the Steeltoe factory in a controller or view: - Container container = client.GetContainer(connector.Options.Database, "TestContainer"); - List sampleObjects = new(); + ```csharp + using Microsoft.AspNetCore.Mvc; + using Microsoft.Azure.Cosmos; + using Microsoft.Azure.Cosmos.Linq; + using Steeltoe.Connectors; + using Steeltoe.Connectors.CosmosDb; - await foreach (SampleObject sampleObject in GetAllAsync(container)) + public class HomeController : Controller + { + public async Task Index( + [FromServices] ConnectorFactory connectorFactory) { - sampleObjects.Add(sampleObject); - } + var connector = connectorFactory.Get(); + CosmosClient client = connector.GetConnection(); - return View(sampleObjects); - } + Container container = client.GetContainer(connector.Options.Database, "TestContainer"); + List sampleObjects = new(); - private async IAsyncEnumerable GetAllAsync(Container container) - { - using FeedIterator iterator = - container.GetItemLinqQueryable().ToFeedIterator(); + await foreach (SampleObject sampleObject in GetAllAsync(container)) + { + sampleObjects.Add(sampleObject); + } - while (iterator.HasMoreResults) + return View(sampleObjects); + } + + private async IAsyncEnumerable GetAllAsync(Container container) { - FeedResponse response = await iterator.ReadNextAsync(); + using FeedIterator iterator = + container.GetItemLinqQueryable().ToFeedIterator(); - foreach (SampleObject sampleObject in response) + while (iterator.HasMoreResults) { - yield return sampleObject; + FeedResponse response = await iterator.ReadNextAsync(); + + foreach (SampleObject sampleObject in response) + { + yield return sampleObject; + } } } } -} -``` + ``` A complete sample app that uses `CosmosClient` is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/CosmosDb. ## Cloud Foundry This Connector supports the following service brokers: -- [VMware Tanzu Cloud Service Broker for Azure](https://docs.vmware.com/en/Tanzu-Cloud-Service-Broker-for-Azure/1.4/csb-azure/GUID-index.html) + +- [VMware Tanzu Cloud Service Broker for Azure](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-microsoft-azure/1-10/csb-azure/index.html) You can create and bind an instance to your application by using the Cloud Foundry CLI: -```bash +```shell # Create CosmosDB service cf create-service csb-azure-cosmosdb-sql mini myCosmosDbService diff --git a/api/v4/connectors/extensibility.md b/api/v4/connectors/extensibility.md index 47e8bfe0..7e8cc99c 100644 --- a/api/v4/connectors/extensibility.md +++ b/api/v4/connectors/extensibility.md @@ -1,6 +1,6 @@ # Extensibility -Connectors were redesigned from scratch in Steeltoe v4. At the time of writing, extensibility is not yet available. +Connectors were redesigned in Steeltoe v4, and extensibility is not yet available. We intend to address this gap in the near future. Please follow along and add any input you may have on [this issue](https://github.com/SteeltoeOSS/Steeltoe/issues/1154). See [Advanced settings](usage.md#advanced-settings) to customize the built-in Connectors. diff --git a/api/v4/connectors/index.md b/api/v4/connectors/index.md index fdb46d46..4e580110 100644 --- a/api/v4/connectors/index.md +++ b/api/v4/connectors/index.md @@ -6,12 +6,12 @@ Connectors are primarily a bonding layer between your infrastructure and your ap Connectors don't directly manipulate the connection to backing services, but do contain logic for turning raw credentials into formatted connection strings and also provide health monitoring tools. -Get started with the [basic concepts](usage.md) or go directly to any supported technology: +Get started with the basic concepts in [Usage](usage.md) or go directly to any supported technology: -- [MySql](mysql.md) +- [MySQL](mysql.md) - [Microsoft SQL Server](microsoft-sql-server.md) - [PostgreSQL](postgresql.md) - [RabbitMQ](rabbitmq.md) - [MongoDB](mongodb.md) - [CosmosDB](cosmosdb.md) -- [Redis](redis.md) +- [Redis/Valkey](redis.md) diff --git a/api/v4/connectors/microsoft-sql-server.md b/api/v4/connectors/microsoft-sql-server.md index 6143765c..28a338ad 100644 --- a/api/v4/connectors/microsoft-sql-server.md +++ b/api/v4/connectors/microsoft-sql-server.md @@ -2,15 +2,17 @@ This connector simplifies accessing [Microsoft SQL Server](https://www.microsoft.com/sql-server) databases. It supports the following .NET drivers: -- [Microsoft.Data.SqlClient](https://www.nuget.org/packages/Microsoft.Data.SqlClient), which provides an ADO.NET `DbConnection`. -- [System.Data.SqlClient](https://www.nuget.org/packages/System.Data.SqlClient), which provides an ADO.NET `DbConnection`. -- [Microsoft.EntityFrameworkCore.SqlServer](https://www.nuget.org/packages/Microsoft.EntityFrameworkCore.SqlServer), which provides [Entity Framework Core](https://learn.microsoft.com/ef/core) support. -The remainder of this page assumes you're familiar with the [basic concepts of Steeltoe Connectors](./usage.md). +- [Microsoft.Data.SqlClient](https://www.nuget.org/packages/Microsoft.Data.SqlClient), which provides an ADO.NET `DbConnection` +- [System.Data.SqlClient](https://www.nuget.org/packages/System.Data.SqlClient), which provides an ADO.NET `DbConnection` +- [Microsoft.EntityFrameworkCore.SqlServer](https://www.nuget.org/packages/Microsoft.EntityFrameworkCore.SqlServer), which provides [Entity Framework Core](https://learn.microsoft.com/ef/core) support -## Usage +The remainder of this topic assumes that you are familiar with the basic concepts of Steeltoe Connectors. See [Overview](./usage.md) for more information. + +## Using the Microsoft SQL Server Connector To use this connector: + 1. Create a SQL Server instance or use [SQL Server Express LocalDB](https://learn.microsoft.com/sql/database-engine/configure-windows/sql-server-express-localdb). 1. Add NuGet references to your project. 1. Configure your connection string in `appsettings.json`. @@ -26,7 +28,7 @@ Also add a NuGet reference to one of the .NET drivers listed above, as you would ### Configure connection string -The available connection string parameters for SQL Server are documented [here](https://learn.microsoft.com/dotnet/api/microsoft.data.sqlclient.sqlconnection.connectionstring#remarks). +The available connection string parameters for SQL Server are documented in the [Microsoft documentation](https://learn.microsoft.com/dotnet/api/microsoft.data.sqlclient.sqlconnection.connectionstring#remarks). The following example `appsettings.json` uses SQL Server Express LocalDB: @@ -86,65 +88,69 @@ public class HomeController : Controller ### Use Entity Framework Core -Start by defining your `DbContext` class: -```csharp -public class AppDbContext : DbContext -{ - public DbSet SampleEntities => Set(); +To retrieve data from SQL Server in your app using Entity Framework Core, use the following steps: - public AppDbContext(DbContextOptions options) - : base(options) +1. Define your `DbContext` class: + + ```csharp + public class AppDbContext : DbContext { + public DbSet SampleEntities => Set(); + + public AppDbContext(DbContextOptions options) + : base(options) + { + } } -} -public class SampleEntity -{ - public long Id { get; set; } - public string? Text { get; set; } -} -``` + public class SampleEntity + { + public long Id { get; set; } + public string? Text { get; set; } + } + ``` -Next, call the `UseSqlServer()` Steeltoe extension method from `Program.cs` to initialize Entity Framework Core: +1. Call the `UseSqlServer()` Steeltoe extension method from `Program.cs` to initialize Entity Framework Core: -```csharp -using Steeltoe.Connectors.EntityFrameworkCore.SqlServer; -using Steeltoe.Connectors.SqlServer; + ```csharp + using Steeltoe.Connectors.EntityFrameworkCore.SqlServer; + using Steeltoe.Connectors.SqlServer; -var builder = WebApplication.CreateBuilder(args); -builder.AddSqlServer(); + var builder = WebApplication.CreateBuilder(args); + builder.AddSqlServer(); -builder.Services.AddDbContext( - (serviceProvider, options) => options.UseSqlServer(serviceProvider)); -``` + builder.Services.AddDbContext( + (serviceProvider, options) => options.UseSqlServer(serviceProvider)); + ``` -Once you have configured and added your `DbContext` to the service container, +1. After you have configured and added your `DbContext` to the service container, you can inject it and use it in a controller or view: -```csharp -using Microsoft.AspNetCore.Mvc; -using Microsoft.EntityFrameworkCore; + ```csharp + using Microsoft.AspNetCore.Mvc; + using Microsoft.EntityFrameworkCore; -public class HomeController : Controller -{ - public async Task Index([FromServices] AppDbContext appDbContext) + public class HomeController : Controller { - List entities = await appDbContext.SampleEntities.ToListAsync(); - return View(entities); + public async Task Index([FromServices] AppDbContext appDbContext) + { + List entities = await appDbContext.SampleEntities.ToListAsync(); + return View(entities); + } } -} -``` + ``` A complete sample app that uses Entity Framework Core with SQL Server is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/SqlServerEFCore. ## Cloud Foundry This Connector supports the following service brokers: -- [VMware Tanzu Cloud Service Broker for Azure](https://docs.vmware.com/en/Tanzu-Cloud-Service-Broker-for-Azure/1.4/csb-azure/GUID-index.html) + +- [VMware Tanzu Cloud Service Broker for Azure](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-microsoft-azure/1-12/csb-azure/index.html) You can create and bind an instance to your application by using the Cloud Foundry CLI: -```bash +```shell # Create SQL Server service cf create-service csb-azure-mssql small-v2 mySqlServerService diff --git a/api/v4/connectors/mongodb.md b/api/v4/connectors/mongodb.md index c38d8554..db9bcb59 100644 --- a/api/v4/connectors/mongodb.md +++ b/api/v4/connectors/mongodb.md @@ -2,11 +2,12 @@ This connector simplifies accessing [MongoDB](https://www.mongodb.com/) databases. It supports the following .NET drivers: -- [MongoDB.Driver](https://www.nuget.org/packages/MongoDB.Driver), which provides an `IMongoClient`. -The remainder of this page assumes you're familiar with the [basic concepts of Steeltoe Connectors](./usage.md). +- [MongoDB.Driver](https://www.nuget.org/packages/MongoDB.Driver), which provides an `IMongoClient` -## Usage +The remainder of this topic assumes that you are familiar with the basic concepts of Steeltoe Connectors. See [Overview](./usage.md) for more information. + +## Using the MongoDB connector To use this connector: @@ -24,9 +25,9 @@ Also add a NuGet reference to one of the .NET drivers listed above, as you would ### Configure connection string -The available connection string parameters for MongoDB are documented [here](https://www.mongodb.com/docs/manual/reference/connection-string/). +The available connection string parameters for MongoDB are described in the [MongoDB documentation](https://www.mongodb.com/docs/manual/reference/connection-string/). -The following example `appsettings.json` uses the docker container from above: +The following example `appsettings.json` uses the docker container referred to earlier: ```json { @@ -43,12 +44,12 @@ The following example `appsettings.json` uses the docker container from above: } ``` -Notice this configuration file contains the database name, in addition to the connection string. This value is exposed +Notice that this configuration file contains the database name, in addition to the connection string. This value is exposed as `MongoDbOptions.Database`. ### Initialize Steeltoe Connector -Update your `Program.cs` as below to initialize the Connector: +Update your `Program.cs` to initialize the Connector: ```csharp using Steeltoe.Connectors.MongoDb; @@ -59,53 +60,55 @@ builder.AddMongoDb(); ### Use IMongoClient -Start by defining a class that contains collection data: -```csharp -using MongoDB.Bson; +1. Define a class that contains collection data: -public class SampleObject -{ - public ObjectId Id { get; set; } - public string? Text { get; set; } -} -``` + ```csharp + using MongoDB.Bson; -To obtain an `IMongoClient` instance in your application, inject the Steeltoe factory in a controller or view: + public class SampleObject + { + public ObjectId Id { get; set; } + public string? Text { get; set; } + } + ``` -```csharp -using Microsoft.AspNetCore.Mvc; -using MongoDb.Data; -using MongoDB.Driver; -using Steeltoe.Connectors; -using Steeltoe.Connectors.MongoDb; +1. Obtain an `IMongoClient` instance in your application by injecting the Steeltoe factory in a controller or view: -public class HomeController : Controller -{ - public async Task Index( - [FromServices] ConnectorFactory connectorFactory) + ```csharp + using Microsoft.AspNetCore.Mvc; + using MongoDb.Data; + using MongoDB.Driver; + using Steeltoe.Connectors; + using Steeltoe.Connectors.MongoDb; + + public class HomeController : Controller { - var connector = connectorFactory.Get(); - IMongoClient client = connector.GetConnection(); + public async Task Index( + [FromServices] ConnectorFactory connectorFactory) + { + var connector = connectorFactory.Get(); + IMongoClient client = connector.GetConnection(); - IMongoDatabase database = client.GetDatabase(connector.Options.Database); - IMongoCollection collection = database.GetCollection("SampleObjects"); - List sampleObjects = await collection.Find(obj => true).ToListAsync(); + IMongoDatabase database = client.GetDatabase(connector.Options.Database); + IMongoCollection collection = database.GetCollection("SampleObjects"); + List sampleObjects = await collection.Find(obj => true).ToListAsync(); - return View(sampleObjects); + return View(sampleObjects); + } } -} -``` + ``` A complete sample app that uses `IMongoClient` is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/MongoDb. ## Cloud Foundry This Connector supports the following service brokers: -- [VMware Tanzu Cloud Service Broker for Azure](https://docs.vmware.com/en/Tanzu-Cloud-Service-Broker-for-Azure/1.4/csb-azure/GUID-index.html) + +- [VMware Tanzu Cloud Service Broker for Azure](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-microsoft-azure/1-12/csb-azure/index.html) You can create and bind an instance to your application by using the Cloud Foundry CLI: -```bash +```shell # Create MongoDB service cf create-service csb-azure-mongodb small myMongoDbService @@ -119,6 +122,6 @@ cf restage myApp ## Kubernetes This Connector supports the [Service Binding Specification for Kubernetes](https://github.com/servicebinding/spec). -It can be used through the Bitnami [Services Toolkit](https://docs.vmware.com/en/VMware-Tanzu-Application-Platform/1.5/tap/services-toolkit-install-services-toolkit.html). +It can be used through the [Services Toolkit](https://techdocs.broadcom.com/us/en/vmware-tanzu/standalone-components/tanzu-application-platform/1-12/tap/services-toolkit-install-services-toolkit.html). -For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/MongoDb#running-on-tanzu-application-platform-tap. +For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/MongoDb#running-on-tanzu-platform-for-kubernetes. diff --git a/api/v4/connectors/mysql.md b/api/v4/connectors/mysql.md index 00774ec4..169e274e 100644 --- a/api/v4/connectors/mysql.md +++ b/api/v4/connectors/mysql.md @@ -2,14 +2,15 @@ This connector simplifies accessing [MySQL](https://www.mysql.com/) databases. It supports the following .NET drivers: -- [MySqlConnector](https://www.nuget.org/packages/MySqlConnector), which provides an ADO.NET `DbConnection`. -- [MySql.Data](https://www.nuget.org/packages/MySql.Data), which provides an ADO.NET `DbConnection`. -- [Pomelo.EntityFrameworkCore.MySql](https://www.nuget.org/packages/Pomelo.EntityFrameworkCore.MySql), which provides [Entity Framework Core](https://learn.microsoft.com/ef/core) support. -- [MySql.EntityFrameworkCore](https://www.nuget.org/packages/MySql.EntityFrameworkCore), which provides [Entity Framework Core](https://learn.microsoft.com/ef/core) support. -The remainder of this page assumes you're familiar with the [basic concepts of Steeltoe Connectors](./usage.md). +- [MySqlConnector](https://www.nuget.org/packages/MySqlConnector), which provides an ADO.NET `DbConnection` +- [MySql.Data](https://www.nuget.org/packages/MySql.Data), which provides an ADO.NET `DbConnection` +- [Pomelo.EntityFrameworkCore.MySql](https://www.nuget.org/packages/Pomelo.EntityFrameworkCore.MySql), which provides [Entity Framework Core](https://learn.microsoft.com/ef/core) support +- [MySql.EntityFrameworkCore](https://www.nuget.org/packages/MySql.EntityFrameworkCore), which provides [Entity Framework Core](https://learn.microsoft.com/ef/core) support -## Usage +The remainder of this topic assumes that you are familiar with the basic concepts of Steeltoe Connectors. See [Overview](./usage.md) for more information. + +## Using the MySQL connector To use this connector: @@ -21,16 +22,19 @@ To use this connector: ### Add NuGet References -To use this connector, add a NuGet reference to `Steeltoe.Connectors`. If you're using Entity Framework Core, add a -NuGet reference to `Steeltoe.Connectors.EntityFrameworkCore` instead. +To use this connector, add a NuGet reference to `Steeltoe.Connectors`. +If you're using Entity Framework Core, add a NuGet reference to `Steeltoe.Connectors.EntityFrameworkCore` instead. Also add a NuGet reference to one of the .NET drivers listed above, as you would if you were not using Steeltoe. ### Configure connection string -The available connection string parameters for MySQL are documented [here](https://mysqlconnector.net/connection-options/) and [here](https://dev.mysql.com/doc/refman/8.0/en/connecting-using-uri-or-key-value-pairs.html#connection-parameters-base). +For the available connection string parameters for MySQL, see: + +* [MySQL Connector documentation](https://mysqlconnector.net/connection-options/) +* [MySQL documentation](https://dev.mysql.com/doc/refman/8.0/en/connecting-using-uri-or-key-value-pairs.html#connection-parameters-base) -The following example `appsettings.json` uses the docker container from above: +The following example `appsettings.json` uses the docker container referred to earlier: ```json { @@ -48,7 +52,7 @@ The following example `appsettings.json` uses the docker container from above: ### Initialize Steeltoe Connector -Update your `Program.cs` as below to initialize the Connector: +Update your `Program.cs` as shown here to initialize the Connector: ```csharp using Steeltoe.Connectors.MySql; @@ -90,67 +94,71 @@ A complete sample app that uses `MySqlConnection` is provided at https://github. ### Use Entity Framework Core -Start by defining your `DbContext` class: -```csharp -public class AppDbContext : DbContext -{ - public DbSet SampleEntities => Set(); +To retrieve data from MySQL in your app using Entity Framework Core, use the following steps: - public AppDbContext(DbContextOptions options) - : base(options) +1. Define your `DbContext` class: + + ```csharp + public class AppDbContext : DbContext { + public DbSet SampleEntities => Set(); + + public AppDbContext(DbContextOptions options) + : base(options) + { + } } -} -public class SampleEntity -{ - public long Id { get; set; } - public string? Text { get; set; } -} -``` + public class SampleEntity + { + public long Id { get; set; } + public string? Text { get; set; } + } + ``` -Next, call the `UseMySql()` Steeltoe extension method from `Program.cs` to initialize Entity Framework Core: +1. Call the `UseMySql()` Steeltoe extension method from `Program.cs` to initialize Entity Framework Core: -```csharp -using Steeltoe.Connectors.EntityFrameworkCore.MySql; -using Steeltoe.Connectors.MySql; + ```csharp + using Steeltoe.Connectors.EntityFrameworkCore.MySql; + using Steeltoe.Connectors.MySql; -var builder = WebApplication.CreateBuilder(args); -builder.AddMySql(); + var builder = WebApplication.CreateBuilder(args); + builder.AddMySql(); -builder.Services.AddDbContext( - (serviceProvider, options) => options.UseMySql(serviceProvider)); -``` + builder.Services.AddDbContext( + (serviceProvider, options) => options.UseMySql(serviceProvider)); + ``` -Once you have configured and added your `DbContext` to the service container, +1. After you have configured and added your `DbContext` to the service container, you can inject it and use it in a controller or view: -```csharp -using Microsoft.AspNetCore.Mvc; -using Microsoft.EntityFrameworkCore; + ```csharp + using Microsoft.AspNetCore.Mvc; + using Microsoft.EntityFrameworkCore; -public class HomeController : Controller -{ - public async Task Index([FromServices] AppDbContext appDbContext) + public class HomeController : Controller { - List entities = await appDbContext.SampleEntities.ToListAsync(); - return View(entities); + public async Task Index([FromServices] AppDbContext appDbContext) + { + List entities = await appDbContext.SampleEntities.ToListAsync(); + return View(entities); + } } -} -``` + ``` A complete sample app that uses Entity Framework Core with MySQL is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/MySqlEFCore. ## Cloud Foundry This Connector supports the following service brokers: -- [VMware SQL with MySQL for Tanzu Application Service](https://docs.vmware.com/en/VMware-SQL-with-MySQL-for-Tanzu-Application-Service/3.0/mysql-for-tas/index.html) -- [VMware Tanzu Cloud Service Broker for Azure](https://docs.vmware.com/en/Tanzu-Cloud-Service-Broker-for-Azure/1.4/csb-azure/GUID-index.html) -- [VMware Tanzu Cloud Service Broker for GCP](https://docs.vmware.com/en/Tanzu-Cloud-Service-Broker-for-GCP/1.2/csb-gcp/GUID-index.html) + +- [VMware Tanzu for MySQL on Cloud Foundry](https://techdocs.broadcom.com/us/en/vmware-tanzu/data-solutions/tanzu-for-mysql-on-cloud-foundry/3-3/mysql-for-tpcf/about_mysql_vms.html) +- [VMware Tanzu Cloud Service Broker for Azure](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-microsoft-azure/1-9/csb-azure/index.html) +- [VMware Tanzu Cloud Service Broker for GCP](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-gcp/1-8/csb-gcp/index.html) You can create and bind an instance to your application by using the Cloud Foundry CLI: -```bash +```shell # Create MySQL service cf create-service p.mysql db-small myMySqlService @@ -164,6 +172,6 @@ cf restage myApp ## Kubernetes This Connector supports the [Service Binding Specification for Kubernetes](https://github.com/servicebinding/spec). -It can be used through the Bitnami [Services Toolkit](https://docs.vmware.com/en/VMware-Tanzu-Application-Platform/1.5/tap/services-toolkit-install-services-toolkit.html). +It can be used through the [Services Toolkit](https://techdocs.broadcom.com/us/en/vmware-tanzu/standalone-components/tanzu-application-platform/1-12/tap/services-toolkit-install-services-toolkit.html). -For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/MySql#running-on-tanzu-application-platform-tap. +For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/MySql#running-on-tanzu-platform-for-kubernetes. diff --git a/api/v4/connectors/postgresql.md b/api/v4/connectors/postgresql.md index 541b3d46..f308e39c 100644 --- a/api/v4/connectors/postgresql.md +++ b/api/v4/connectors/postgresql.md @@ -2,12 +2,13 @@ This connector simplifies accessing [PostgreSQL](https://www.postgresql.org/) databases. It supports the following .NET drivers: -- [Npgsql](https://www.nuget.org/packages/Npgsql), which provides an ADO.NET `DbConnection`. -- [Npgsql.EntityFrameworkCore.PostgreSQL](https://www.nuget.org/packages/Npgsql.EntityFrameworkCore.PostgreSQL), which provides [Entity Framework Core](https://learn.microsoft.com/ef/core) support. -The remainder of this page assumes you're familiar with the [basic concepts of Steeltoe Connectors](./usage.md). +- [Npgsql](https://www.nuget.org/packages/Npgsql), which provides an ADO.NET `DbConnection` +- [Npgsql.EntityFrameworkCore.PostgreSQL](https://www.nuget.org/packages/Npgsql.EntityFrameworkCore.PostgreSQL), which provides [Entity Framework Core](https://learn.microsoft.com/ef/core) support -## Usage +The remainder of this topic assumes that you are familiar with the basic concepts of Steeltoe Connectors. See [Overview](./usage.md) for more information. + +## Using the PostgreSQL connector To use this connector: @@ -26,9 +27,9 @@ Also add a NuGet reference to one of the .NET drivers listed above, as you would ### Configure connection string -The available connection string parameters for PostgreSQL are documented [here](https://www.npgsql.org/doc/connection-string-parameters.html). +The available connection string parameters for PostgreSQL are described in the [Npgsql documentation](https://www.npgsql.org/doc/connection-string-parameters.html). -The following example `appsettings.json` uses the docker container from above: +The following example `appsettings.json` uses the docker container referred to earlier: ```json { @@ -46,7 +47,7 @@ The following example `appsettings.json` uses the docker container from above: ### Initialize Steeltoe Connector -Update your `Program.cs` as below to initialize the Connector: +Update your `Program.cs` to initialize the Connector: ```csharp using Steeltoe.Connectors.PostgreSql; @@ -88,66 +89,70 @@ A complete sample app that uses `NpgsqlConnection` is provided at https://github ### Use Entity Framework Core -Start by defining your `DbContext` class: -```csharp -public class AppDbContext : DbContext -{ - public DbSet SampleEntities => Set(); +To retrieve data from PostgreSQL in your app using Entity Framework Core, use the following steps: + +1. Define your `DbContext` class: - public AppDbContext(DbContextOptions options) - : base(options) + ```csharp + public class AppDbContext : DbContext { + public DbSet SampleEntities => Set(); + + public AppDbContext(DbContextOptions options) + : base(options) + { + } } -} -public class SampleEntity -{ - public long Id { get; set; } - public string? Text { get; set; } -} -``` + public class SampleEntity + { + public long Id { get; set; } + public string? Text { get; set; } + } + ``` -Next, call the `UseNpgsql()` Steeltoe extension method from `Program.cs` to initialize Entity Framework Core: +1. Call the `UseNpgsql()` Steeltoe extension method from `Program.cs` to initialize Entity Framework Core: -```csharp -using Steeltoe.Connectors.EntityFrameworkCore.PostgreSql; -using Steeltoe.Connectors.PostgreSql; + ```csharp + using Steeltoe.Connectors.EntityFrameworkCore.PostgreSql; + using Steeltoe.Connectors.PostgreSql; -var builder = WebApplication.CreateBuilder(args); -builder.AddPostgreSql(); + var builder = WebApplication.CreateBuilder(args); + builder.AddPostgreSql(); -builder.Services.AddDbContext( - (serviceProvider, options) => options.UseNpgsql(serviceProvider)); -``` + builder.Services.AddDbContext( + (serviceProvider, options) => options.UseNpgsql(serviceProvider)); + ``` -Once you have configured and added your `DbContext` to the service container, +1. After you have configured and added your `DbContext` to the service container, you can inject it and use it in a controller or view: -```csharp -using Microsoft.AspNetCore.Mvc; -using Microsoft.EntityFrameworkCore; + ```csharp + using Microsoft.AspNetCore.Mvc; + using Microsoft.EntityFrameworkCore; -public class HomeController : Controller -{ - public async Task Index([FromServices] AppDbContext appDbContext) + public class HomeController : Controller { - List entities = await appDbContext.SampleEntities.ToListAsync(); - return View(entities); + public async Task Index([FromServices] AppDbContext appDbContext) + { + List entities = await appDbContext.SampleEntities.ToListAsync(); + return View(entities); + } } -} -``` + ``` A complete sample app that uses Entity Framework Core with PostgreSQL is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/PostgreSqlEFCore. ## Cloud Foundry This Connector supports the following service brokers: -- [VMware Tanzu Cloud Service Broker for Azure](https://docs.vmware.com/en/Tanzu-Cloud-Service-Broker-for-Azure/1.4/csb-azure/GUID-index.html) -- [VMware Tanzu Cloud Service Broker for GCP](https://docs.vmware.com/en/Tanzu-Cloud-Service-Broker-for-GCP/1.2/csb-gcp/GUID-index.html) + +- [VMware Tanzu Cloud Service Broker for Azure](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-microsoft-azure/1-9/csb-azure/index.html) +- [VMware Tanzu Cloud Service Broker for GCP](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-gcp/1-8/csb-gcp/index.html) You can create and bind an instance to your application by using the Cloud Foundry CLI: -```bash +```shell # Create PostgreSQL service cf create-service csb-azure-postgresql small myPostgreSqlService @@ -161,6 +166,6 @@ cf restage myApp ## Kubernetes This Connector supports the [Service Binding Specification for Kubernetes](https://github.com/servicebinding/spec). -It can be used through the Bitnami [Services Toolkit](https://docs.vmware.com/en/VMware-Tanzu-Application-Platform/1.5/tap/services-toolkit-install-services-toolkit.html). +It can be used through the [Services Toolkit](https://techdocs.broadcom.com/us/en/vmware-tanzu/standalone-components/tanzu-application-platform/1-12/tap/services-toolkit-install-services-toolkit.html). -For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/PostgreSql#running-on-tanzu-application-platform-tap. +For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/PostgreSql#running-on-tanzu-platform-for-kubernetes. diff --git a/api/v4/connectors/rabbitmq.md b/api/v4/connectors/rabbitmq.md index 396aac46..caca3a49 100644 --- a/api/v4/connectors/rabbitmq.md +++ b/api/v4/connectors/rabbitmq.md @@ -2,11 +2,12 @@ This connector simplifies accessing [RabbitMQ](https://www.rabbitmq.com/) message brokers. It supports the following .NET drivers: -- [RabbitMQ.Client](https://www.nuget.org/packages/RabbitMQ.Client), which provides an `IConnection`. -The remainder of this page assumes you're familiar with the [basic concepts of Steeltoe Connectors](./usage.md). +- [RabbitMQ.Client](https://www.nuget.org/packages/RabbitMQ.Client), which provides an `IConnection` -## Usage +The remainder of this topic assumes that you are familiar with the basic concepts of Steeltoe Connectors. See [Overview](./usage.md) for more information. + +## Using the RabbitMQ connector To use this connector: @@ -24,9 +25,9 @@ Also add a NuGet reference to one of the .NET drivers listed above, as you would ### Configure connection string -The available connection string parameters for RabbitMQ are documented [here](https://www.rabbitmq.com/uri-spec.html). +The available connection string parameters for RabbitMQ are described in the [RabbitMQ documentation](https://www.rabbitmq.com/uri-spec.html). -The following example `appsettings.json` uses the docker container from above: +The following example `appsettings.json` uses the docker container referred to earlier: ```json { @@ -44,7 +45,7 @@ The following example `appsettings.json` uses the docker container from above: ### Initialize Steeltoe Connector -Update your `Program.cs` as below to initialize the Connector: +Update your `Program.cs` to initialize the Connector: ```csharp using Steeltoe.Connectors.RabbitMQ; @@ -87,11 +88,12 @@ A complete sample app that uses `IConnection` is provided at https://github.com/ ## Cloud Foundry This Connector supports the following service brokers: -- [VMware RabbitMQ for Tanzu Application Service](https://docs.vmware.com/en/VMware-RabbitMQ-for-Tanzu-Application-Service/2.2/tanzu-rmq/GUID-index.html) + +- [VMware Tanzu RabbitMQ on Cloud Foundry](https://techdocs.broadcom.com/us/en/vmware-tanzu/data-solutions/tanzu-rabbitmq-on-cloud-foundry/10-0/tanzu-rabbitmq-cloud-foundry/index.html) You can create and bind an instance to your application by using the Cloud Foundry CLI: -```bash +```shell # Create RabbitMQ service cf create-service p.rabbitmq single-node myRabbitMQService @@ -105,6 +107,6 @@ cf restage myApp ## Kubernetes This Connector supports the [Service Binding Specification for Kubernetes](https://github.com/servicebinding/spec). -It can be used through the Bitnami [Services Toolkit](https://docs.vmware.com/en/VMware-Tanzu-Application-Platform/1.5/tap/services-toolkit-install-services-toolkit.html). +It can be used through the [Services Toolkit](https://techdocs.broadcom.com/us/en/vmware-tanzu/standalone-components/tanzu-application-platform/1-12/tap/services-toolkit-install-services-toolkit.html). -For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/RabbitMQ#running-on-tanzu-application-platform-tap. +For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/RabbitMQ#running-on-tanzu-platform-for-kubernetes. diff --git a/api/v4/connectors/redis.md b/api/v4/connectors/redis.md index a13976a1..651ca37d 100644 --- a/api/v4/connectors/redis.md +++ b/api/v4/connectors/redis.md @@ -1,17 +1,19 @@ -# Redis +# Redis/Valkey + +This connector simplifies accessing [Redis](https://redis.io/) and [Valkey](https://valkey.io/) databases. -This connector simplifies accessing [Redis](https://redis.io/) databases. It supports the following .NET drivers: -- [StackExchange.Redis](https://www.nuget.org/packages/StackExchange.Redis), which provides an `IConnectionMultiplexer`. -- [Microsoft.Extensions.Caching.StackExchangeRedis](https://www.nuget.org/packages/Microsoft.Extensions.Caching.StackExchangeRedis), which provides an `IDistributedCache`. -The remainder of this page assumes you're familiar with the [basic concepts of Steeltoe Connectors](./usage.md). +- [StackExchange.Redis](https://www.nuget.org/packages/StackExchange.Redis), which provides an `IConnectionMultiplexer` +- [Microsoft.Extensions.Caching.StackExchangeRedis](https://www.nuget.org/packages/Microsoft.Extensions.Caching.StackExchangeRedis), which provides an `IDistributedCache` + +The remainder of this topic assumes that you are familiar with the basic concepts of Steeltoe Connectors. See [Overview](./usage.md) for more information. -## Usage +## Using the Redis Connector To use this connector: -1. Create a Redis server instance or use a [docker container](https://github.com/SteeltoeOSS/Samples/blob/main/CommonTasks.md#redis). +1. Create a Redis/Valkey server instance or use a [Redis docker container](https://github.com/SteeltoeOSS/Samples/blob/main/CommonTasks.md#redis) or [Valkey docker container](https://github.com/SteeltoeOSS/Samples/blob/main/CommonTasks.md#valkey). 1. Add NuGet references to your project. 1. Configure your connection string in `appsettings.json`. 1. Initialize the Steeltoe Connector at startup. @@ -25,9 +27,9 @@ Also add a NuGet reference to one of the .NET drivers listed above, as you would ### Configure connection string -The available connection string parameters for Redis are documented [here](https://stackexchange.github.io/StackExchange.Redis/Configuration.html). +The available connection string parameters for Redis are described in [StackExchange.Redis](https://stackexchange.github.io/StackExchange.Redis/Configuration.html). -The following example `appsettings.json` uses the docker container from above: +The following example `appsettings.json` works with either docker container referred to earlier: ```json { @@ -45,7 +47,7 @@ The following example `appsettings.json` uses the docker container from above: ### Initialize Steeltoe Connector -Update your `Program.cs` as below to initialize the Connector: +Update your `Program.cs` to initialize the Connector: ```csharp using Steeltoe.Connectors.Redis; @@ -81,7 +83,7 @@ public class HomeController : Controller } ``` -A complete sample app that uses `IConnectionMultiplexer` is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/Redis. +For a complete sample app that uses `IConnectionMultiplexer`, see https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/Redis. ### Use IDistributedCache @@ -109,18 +111,20 @@ public class HomeController : Controller } ``` -A complete sample app that uses `IDistributedCache` is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/Redis. +For a complete sample app that uses `IDistributedCache`, see https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/Redis. ## Cloud Foundry This Connector supports the following service brokers: -- [Redis for VMware Tanzu Application Service](https://docs.vmware.com/en/Redis-for-VMware-Tanzu-Application-Service/3.1/redis-tanzu-application-service/GUID-index.html) -- [VMware Tanzu Cloud Service Broker for Azure](https://docs.vmware.com/en/Tanzu-Cloud-Service-Broker-for-Azure/1.4/csb-azure/GUID-index.html) -- [VMware Tanzu Cloud Service Broker for GCP](https://docs.vmware.com/en/Tanzu-Cloud-Service-Broker-for-GCP/1.2/csb-gcp/GUID-index.html) + +- [Redis for VMware Tanzu Application Service](https://techdocs.broadcom.com/us/en/vmware-tanzu/data-solutions/redis-for-tanzu-application-service/3-5/redis-for-tas/index.html) +- [Tanzu for Valkey on Cloud Foundry](https://techdocs.broadcom.com/us/en/vmware-tanzu/data-solutions/tanzu-for-valkey-on-cloud-foundry/4-0/valkey-on-cf/index.html) +- [VMware Tanzu Cloud Service Broker for Azure](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-microsoft-azure/1-12/csb-azure/index.html) +- [VMware Tanzu Cloud Service Broker for GCP](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/tanzu-cloud-service-broker-for-gcp/1-5/csb-gcp/index.html) You can create and bind an instance to your application by using the Cloud Foundry CLI: -```bash +```shell # Create Redis service cf create-service p-redis shared-vm myRedisService @@ -134,6 +138,6 @@ cf restage myApp ## Kubernetes This Connector supports the [Service Binding Specification for Kubernetes](https://github.com/servicebinding/spec). -It can be used through the Bitnami [Services Toolkit](https://docs.vmware.com/en/VMware-Tanzu-Application-Platform/1.5/tap/services-toolkit-install-services-toolkit.html). +It can be used through the [Services Toolkit](https://techdocs.broadcom.com/us/en/vmware-tanzu/standalone-components/tanzu-application-platform/1-12/tap/services-toolkit-install-services-toolkit.html). -For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/Redis#running-on-tanzu-application-platform-tap. +For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/Redis#running-on-tanzu-platform-for-kubernetes. diff --git a/api/v4/connectors/usage.md b/api/v4/connectors/usage.md index b190ba9d..ea95a54e 100644 --- a/api/v4/connectors/usage.md +++ b/api/v4/connectors/usage.md @@ -1,19 +1,19 @@ -## Overview +# Overview -Steeltoe Connectors provide access to both low-level connection strings and higher-level driver-specific .NET +Steeltoe Connectors provide access to both low-level connection strings and higher-level, driver-specific .NET connection/client instances. Local connection strings are merged with settings from the cloud. [Health checks](../management/health.md) are registered for use with Steeltoe Management Actuators. Additional extension methods are provided for integration with Entity Framework Core. -This page covers the basic concepts of Connectors, how they work, and how to use them. -The rest of the pages cover information that is specific to the various .NET drivers. +This topic covers the basic concepts of Connectors, how they work, and how to use them. +The remaining Connectors topics cover information specific to the various .NET drivers. -### Connection strings +## Connection strings -At its core, a Steeltoe Connector reads a connection string from appsettings and exposes it via the +A Steeltoe Connector reads a connection string from `appsettings` and exposes it through the [ASP.NET Options pattern](https://learn.microsoft.com/aspnet/core/fundamentals/configuration/options). -For example, given the next `appsettings.json`: +For example, given the following `appsettings.json`: ```json { @@ -30,8 +30,8 @@ For example, given the next `appsettings.json`: } ``` -and NuGet references to `Steeltoe.Connectors` and [Npgsql](https://www.nuget.org/packages/Npgsql), -the code fragment below reads the PostgreSQL connection string and prints it. +And NuGet references to `Steeltoe.Connectors` and [Npgsql](https://www.nuget.org/packages/Npgsql), +the following code fragment reads the PostgreSQL connection string and prints it. ```csharp using Microsoft.Extensions.Options; @@ -46,7 +46,7 @@ var options = app.Services.GetRequiredService>(); Console.WriteLine(options.Value.ConnectionString); ``` -This outputs: +The output is: ``` Host=localhost;Database=steeltoe;Username=steeltoe;Password=steeltoe;Log Parameters=True @@ -55,32 +55,33 @@ Host=localhost;Database=steeltoe;Username=steeltoe;Password=steeltoe;Log Paramet Notice that the parameter names are slightly different in the printed output. This is because Steeltoe relies on the [DbConnectionStringBuilder](https://learn.microsoft.com/dotnet/api/system.data.common.dbconnectionstringbuilder) of the [PostgreSQL .NET driver](https://www.npgsql.org/doc/api/Npgsql.NpgsqlConnectionStringBuilder.html), which normalizes the parameter names. -The advantage of this approach is that you're free to use any driver-specific connection string parameters, +The advantage of this approach is that you can use any driver-specific connection string parameters, without the need for Steeltoe to understand them first. > [!NOTE] > Earlier versions of Steeltoe assigned default values (such as "localhost") for required connection string parameters that were not specified -in configuration. This is no longer the case. In practice, this means you'll need to configure a connection string in most cases to run locally. +in configuration. This is no longer the case. In practice, this means that to run locally, you must configure a connection string in most cases. ### Cloud-hosted applications When your app is running in Cloud Foundry or Kubernetes, the Connector enriches the local connection string from `appsettings.json` -by merging any cloud-provided parameters into it. The resulting connection string is exposed via the Options pattern in the -same way as described above. +by merging any cloud-provided parameters into it. The resulting connection string is exposed through the Options pattern in the +same way as described in the previous section. The Connector automatically detects when merging is needed: + - When running in Cloud Foundry, it reads the connection parameters from the JSON in the `VCAP_SERVICES` environment variable. For more information on `VCAP_SERVICES`, see the [Cloud Foundry documentation](https://docs.cloudfoundry.org/services/binding-credentials.html). - When running in Kubernetes, it reads the secret files from the directory that the `SERVICE_BINDING_ROOT` environment variable points to. For more information on `SERVICE_BINDING_ROOT`, see the [Service Binding Specification for Kubernetes](https://github.com/servicebinding/spec). -### Named connection strings +## Named connection strings -Multiple service bindings can be accessed using named options. Just replace "Default" in your `appsettings.json` with the name +Multiple service bindings can be accessed using named options. Replace `Default` in your `appsettings.json` with the name of the service binding. -For example, the next `appsettings.json` file contains two named connection strings: +For example, the following `appsettings.json` file contains two named connection strings that can be accessed in the code fragment that follows the `appsettings.json`: ```json { @@ -101,8 +102,6 @@ For example, the next `appsettings.json` file contains two named connection stri } ``` -which can be accessed using the code fragment below. - ```csharp using Microsoft.Extensions.Options; using Steeltoe.Connectors.PostgreSql; @@ -117,22 +116,22 @@ Console.WriteLine(optionsMonitor.Get("MyServiceOne").ConnectionString); Console.WriteLine(optionsMonitor.Get("MyServiceTwo").ConnectionString); ``` -This outputs: +This is the output: ``` Host=host1;Database=db1;Username=user1;Password=pass1;Include Error Detail=True Host=host1;Database=db2;Username=user2;Password=pass2;Log Parameters=True ``` -When using cloud hosting, the local connection string names need to match the service binding names in the cloud for proper +When using cloud hosting, the local connection string names must match the service binding names in the cloud for proper merging to take place. -However, for convenience, if you have a single named service binding in the cloud, you can just use "Default" locally. -This is useful if you don't know the cloud-hosted service binding name upfront while developing your application. +However, for convenience, if you have a single named service binding in the cloud, you can use `Default` locally. +This is useful if you don't know the cloud-hosted service binding name upfront as you are developing your application. ## Connection/client instances -On top of the exposed connection string, a Steeltoe Connector provides a factory to obtain driver-specific connection/client instances. +In addition to the exposed connection string, a Steeltoe Connector provides a factory to obtain driver-specific connection/client instances. The example below uses the same `appsettings.json` file from before, but obtains a connection from the factory: @@ -162,8 +161,9 @@ using NpgsqlConnection connectionOne = connectorOne.GetConnection(); connectionOne.Open(); ``` -Per named service, `ConnectorFactory` either returns a new connection/client instance each time or caches the first one, +`ConnectorFactory` either returns a new connection/client instance each time or caches the first one, based on documented best practices for the specific .NET driver. +The cached instance is per named service, so when both service1 and service2 exist, there are two cached instances. ## Legacy host builders @@ -173,7 +173,8 @@ If you're using the legacy [IHostBuilder](https://learn.microsoft.com/aspnet/cor [IWebHostBuilder](https://learn.microsoft.com/aspnet/core/fundamentals/host/web-host), you need to call two methods instead. For example, when using MySQL with `IWebHostBuilder`, add a NuGet reference to -[MySqlConnector](https://www.nuget.org/packages/MySqlConnector) and call both `ConfigureMySql()` and `AddMySql()`: +[MySqlConnector](https://www.nuget.org/packages/MySqlConnector) and call both `ConfigureMySql()` and `AddMySql()` +as shown in the following example: ```csharp using Microsoft.AspNetCore; @@ -203,7 +204,7 @@ internal static class Program To use the merged connection string with Entity Framework Core, add a NuGet reference to `Steeltoe.Connectors.EntityFrameworkCore` and call the corresponding `Use*` Steeltoe method, in addition to adding the Connector to the host builder as shown before. -For example, given the next `appsettings.json`: +For example, given the following `appsettings.json` example: ```json { @@ -249,7 +250,7 @@ public class AppDbContext : DbContext } ``` -This outputs: +This is the output: ``` Data Source=(localdb)\mssqllocaldb;Initial Catalog=ExampleDB;Pooling=True @@ -271,7 +272,7 @@ builder.Services.AddDbContext( ## Advanced settings -Usage of the ASP.NET Options pattern by Steeltoe Connectors enables configuring them using custom code. +Steeltoe Connectors use the ASP.NET Options pattern, which allows you to configure connections using custom code. For example, the code below adds the application name to the MongoDB connection URL at runtime: @@ -293,9 +294,9 @@ builder.Services.Configure(options => }); ``` -The Steeltoe Connector extension methods provide overloads to influence how they work. This enables to hook in custom logic -to construct the connection/client instance and override its lifetime. Or override if and how health checks are registered. -See the documentation on `ConnectorConfigureOptionsBuilder` and `ConnectorAddOptionsBuilder` for details. +The Steeltoe Connector extension methods provide overloads to influence how they work. This allows you to hook in custom logic +to construct the connection/client instance and override its lifetime, or to override whether and how health checks are registered. +See the documentation about `ConnectorConfigureOptionsBuilder` and `ConnectorAddOptionsBuilder` for details. The example below overrides the creation of the Redis `ConnectionMultiplexer` instance and turns off health checks: @@ -327,7 +328,7 @@ builder.AddRedis(null, addOptions => ``` The Steeltoe Connector extension methods for Entity Framework Core take an optional parameter to configure the driver-specific -settings. But because Steeltoe has no compile-time reference to the drivers, you need to upcast its parameter first. +settings. But because Steeltoe has no compile-time reference to the drivers, you must upcast its parameter first. The next example activates the retry policy on the SQL Server provider for Entity Framework Core: diff --git a/api/v4/discovery/configuration-based.md b/api/v4/discovery/configuration-based.md index bcad67fd..268cafb7 100644 --- a/api/v4/discovery/configuration-based.md +++ b/api/v4/discovery/configuration-based.md @@ -1,19 +1,19 @@ # Configuration-based discovery client -The simplest form of service discovery is by storing the list of app instances in .NET configuration. +The simplest way to use service discovery is by storing the list of app instances in .NET configuration. ## Configuration settings An app instance in configuration contains the following keys: | Key | Description | -| --- | --- | --- | -| `ServiceId` | The app friendly name. | -| `Host` | The hostname or IP address of the service instance. | -| `Port` | The port number the service instance is listening on. | -| `IsSecure` | Whether to use HTTP or HTTPS to access the service instance. | +| --- | ----------- | +| `ServiceId` | The app friendly name | +| `Host` | The hostname or IP address of the service instance | +| `Port` | The port number the service instance is listening on | +| `IsSecure` | Whether to use HTTP or HTTPS to access the service instance | -For example, the `appsettings.json` file below adds one instance of "billingService" and two instances of "shippingService". +For example, the `appsettings.json` file shown here adds one instance of `billingService` and two instances of `shippingService`. ```json { @@ -42,8 +42,9 @@ For example, the `appsettings.json` file below adds one instance of "billingServ } ``` -Using the above configuration, sending an HTTP request to `http://shippingService/api?id=123` with Steeltoe service discovery -activated would send the request to either: +Using the preceding configuration, sending an HTTP request to `http://shippingService/api?id=123` with Steeltoe service discovery +activated sends the request to either: + - `https://one.internal.shipping.company.com:888/api?id=123` - `https://two.internal.shipping.company.com:999/api?id=123` diff --git a/api/v4/discovery/discovering-services.md b/api/v4/discovery/discovering-services.md index 74dd7a09..02509619 100644 --- a/api/v4/discovery/discovering-services.md +++ b/api/v4/discovery/discovering-services.md @@ -8,8 +8,8 @@ The recommended approach is to use a typed `HttpClient`, supplied through [HttpClientFactory](https://learn.microsoft.com/aspnet/core/fundamentals/http-requests). Call the `.AddServiceDiscovery()` extension method from the `Steeltoe.Discovery.HttpClients` NuGet package to activate service discovery. -> [!NOTE] -> The `AddServiceDiscovery()` extension method takes an optional `ILoadBalancer` parameter. +> [!TIP] +> The `AddServiceDiscovery()` extension method takes an optional `ILoadBalancer` type parameter. > If no load balancer is provided, the built-in `RandomLoadBalancer` is activated, > which uses randomized selection of service instances. diff --git a/api/v4/discovery/hashicorp-consul.md b/api/v4/discovery/hashicorp-consul.md index a1e021f6..0fed3bc2 100644 --- a/api/v4/discovery/hashicorp-consul.md +++ b/api/v4/discovery/hashicorp-consul.md @@ -1,15 +1,15 @@ # HashiCorp Consul discovery client -The Steeltoe Consul discovery client lets an application register/unregister itself with a Consul server +The Steeltoe Consul discovery client allows an application to register and unregister itself with a Consul server and provides querying for service instances registered by other applications. -Once activated, the client registers the currently running app with Consul and starts a background thread that +After it is activated, the client registers the currently running app with Consul and starts a background thread that periodically sends a TTL heartbeat to the Consul server (this is optional). -The client fetches no service registrations until asked for, and doesn't cache them. +The client doesn't fetch service registrations until they are asked for, and it doesn't cache them. -## Usage +## Using HashiCorp Consul discovery client -To use this discovery client, add a NuGet package reference to `Steeltoe.Discovery.Consul` and initialize it from your `Program.cs`: +To use this discovery client, add a NuGet package reference to `Steeltoe.Discovery.Consul` and initialize it from `Program.cs`. ```csharp var builder = WebApplication.CreateBuilder(args); @@ -22,85 +22,88 @@ var app = builder.Build(); ## Configuration settings -To get the Steeltoe discovery client to properly communicate with the Consul server, you need to provide -a few configuration settings. There are several sections you may need to configure. +To get the Steeltoe discovery client to properly communicate with the Consul server, there are various settings and sections to configure. What you provide depends on whether you want your application to register the running app and/or whether it also needs to query for other apps. -The first section pertains to configuring the information needed to connect to the Consul server. -All of these settings should start with `Consul:`. - -| Key | Description | Default | -| --- | --- | --- | -| `Host` | Hostname or IP address of the Consul server. | `localhost` | -| `Port` | Port number the Consul server is listening on. | `8500` | -| `Scheme` | Scheme to connect with the Consul server (`http` or `https`). | `http` | -| `Datacenter` | The datacenter name passed in each request to the server. | | -| `Token` | Authentication token passed in each request to the server. | | -| `WaitTime` | The maximum duration for a blocking request. | | -| `Username` | Username for HTTP authentication. | | -| `Password` | Password for HTTP authentication. | | -| `Discovery:Enabled` | Whether to enable the Consul client. | `true` | - -The second section you may need to specify pertains to registering the running app. -All of these settings should start with `Consul:Discovery:`. - -| Key | Description | Default | -| --- | --- | --- | -| `Register` | Whether to register the running app as a service instance. | `true` | -| `FailFast` | Throw an exception (instead of logging an error) if registration fails. | `true` | -| `Retry:Enabled` | Whether to try again when registering the running app fails. | `false` | -| `Retry:MaxAttempts` | Maximum number of registration attempts (if retries are enabled). | `6` | -| `Retry:InitialInterval` | The time to wait (in milliseconds) after the first registration failure. | `1000` | -| `Retry:Multiplier` | The factor to increment the next interval with. | `1.1` | -| `Retry:MaxInterval` | Upper bound (in milliseconds) for intervals. | `2000` | -| `Deregister` | Whether to de-register the running app on shutdown. | `true` | -| `ServiceName` | Friendly name to register the running app with. | computed | -| `Scheme` | Scheme to register the running app with (`http` or `https`). | `http` | -| `HostName` | Hostname to register the running app with (if `PreferIPAddress` is `false`). | computed | -| `IPAddress` | IP address to register the running app with (if `PreferIPAddress` is `true`). | computed | -| `UseNetworkInterfaces` | Query the operating system for network interfaces to determine `HostName` and `IPAddress`. | `false` | -| `PreferIPAddress` | Register the running app with IP address instead of hostname. | `false` | -| `Port` | Port number to register the running app with. | | -| `UseAspNetCoreUrls` | Register with the port number ASP.NET Core is listening on. | `true` | -| `InstanceId` | The unique ID to register the running app under. | computed | -| `Tags` | Array of tags used when registering the running app. | | -| `Meta` | Metadata key/value pairs used when registering the running app. | see [Configuring metadata](#configuring-metadata)| -| `InstanceGroup` | Metadata `group` value to use when registering the running app. | | -| `InstanceZone` | Metadata zone value to use when registering the running app. | | -| `DefaultZoneMetadataName` | Metadata key name for `InstanceZone`. | `zone` | -| `RegisterHealthCheck` | Whether to enable periodic health checking for the running app. | `true` | -| `HealthCheckCriticalTimeout` | Duration after which Consul deregisters the running app when in state `critical`. [^1] | `30m` | -| `Heartbeat:Enabled` | Whether the running app periodically sends TTL (time-to-live) heartbeats. [^1] | `true` | -| `Heartbeat:TtlValue` | How often a TTL heartbeat must be sent to be considered healthy. | `30` | +The first section is for configuring the information needed to connect to the Consul server. +All of these settings must start with `Consul:`. + +| Key | Description | Default | +| ------ | ----------- | ------- | +| `Host` | Hostname or IP address of the Consul server | `localhost` | +| `Port` | Port number the Consul server is listening on | `8500` | +| `Scheme` | Scheme to connect with the Consul server (`http` or `https`) | `http` | +| `Datacenter` | The datacenter name passed in each request to the server | | +| `Token` | Authentication token passed in each request to the server | | +| `WaitTime` | The maximum duration for a blocking request | | +| `Username` | Username for HTTP authentication | | +| `Password` | Password for HTTP authentication | | +| `Discovery:Enabled` | Whether to enable the Consul client | `true` | + +The second section (optional) pertains to registering the running app. +All of these settings must start with `Consul:Discovery:`. + +| Key | Description | Default | +| ---------- | ----------- | ------- | +| `Register` | Whether to register the running app as a service instance | `true` | +| `FailFast` | Throw an exception (instead of logging an error) if registration fails | `true` | +| `Retry:Enabled` | Whether to try again when registering the running app fails | `false` | +| `Retry:MaxAttempts` | Maximum number of registration attempts (if retries are enabled) | `6` | +| `Retry:InitialInterval` | The time to wait (in milliseconds) after the first registration failure | `1000` | +| `Retry:Multiplier` | The factor to use when incrementing the next interval | `1.1` | +| `Retry:MaxInterval` | Upper bound (in milliseconds) for intervals | `2000` | +| `Deregister` | Whether to de-register the running app on shutdown | `true` | +| `ServiceName` | Friendly name with which to register the running app | computed | +| `Scheme` | Scheme with which to register the running app (`http` or `https`) | `http` | +| `HostName` | Hostname with which to register the running app (if `PreferIPAddress` is `false`) | computed | +| `IPAddress` | IP address with which to register the running app (if `PreferIPAddress` is `true`) | computed | +| `UseNetworkInterfaces` | Query the operating system for network interfaces to determine `HostName` and `IPAddress` | `false` | +| `PreferIPAddress` | Register the running app with IP address instead of hostname | `false` | +| `Port` | Port number with which to register the running app | | +| `UseAspNetCoreUrls` | Register with the port number ASP.NET Core is listening on | `true` | +| `InstanceId` | The unique ID under which to register the running app | computed | +| `Tags` | Array of tags used when registering the running app | | +| `Meta` | Metadata key/value pairs used when registering the running app | see [Configuring metadata](#configuring-metadata) | +| `InstanceGroup` | Metadata `group` value to use when registering the running app | | +| `InstanceZone` | Metadata zone value to use when registering the running app | | +| `DefaultZoneMetadataName` | Metadata key name for `InstanceZone` | `zone` | +| `RegisterHealthCheck` | Whether to enable periodic health checking for the running app | `true` | +| `HealthCheckCriticalTimeout` | Duration after which Consul deregisters the running app when in state `critical` [^1] | `30m` | +| `Heartbeat:Enabled` | Whether the running app periodically sends TTL (time-to-live) heartbeats [^1] | `true` | +| `Heartbeat:TtlValue` | How often a TTL heartbeat must be sent to be considered healthy | `30` | | `Heartbeat:TtlUnit` | Unit for `TtlValue` (`ms`, `s`, `m` or `h`) | `s` | -| `Heartbeat:IntervalRatio` | Rate at which the running app sends TTL heartbeats, relative to `TtlValue` with `TtlUnit`. | `0.66` | -| `HealthCheckPath` | Relative URL to the health endpoint of the running app. [^2] | `/actuator/health` | -| `HealthCheckUrl` | Absolute URL to the health endpoint of the running app (overrides `HealthCheckPath`). [^2] | | -| `HealthCheckTlsSkipVerify` | Whether Consul should skip TLS verification for HTTP health checks. [^2] | `false` | -| `HealthCheckInterval` | How often Consul should perform an HTTP health check. [^2] | `10s` | -| `HealthCheckTimeout` | The timeout Consul should use for an HTTP health check. [^2] | `10s` | +| `Heartbeat:IntervalRatio` | Rate at which the running app sends TTL heartbeats, relative to `TtlValue` with `TtlUnit` | `0.66` | +| `HealthCheckPath` | Relative URL to the health endpoint of the running app [^2] | `/actuator/health` | +| `HealthCheckUrl` | Absolute URL to the health endpoint of the running app (overrides `HealthCheckPath`) [^2] | | +| `HealthCheckTlsSkipVerify` | Whether Consul should skip TLS verification for HTTP health checks [^2] | `false` | +| `HealthCheckInterval` | How often Consul should perform HTTP health checks [^2] | `10s` | +| `HealthCheckTimeout` | The timeout Consul should use for HTTP health checks [^2] | `10s` | -[^1]: This setting only has effect when `RegisterHealthCheck` is `true` -[^2]: This setting only has effect when `RegisterHealthCheck` is `true` and `Heartbeat:Enabled` is `false` +[^1]: This setting only affects operation when `RegisterHealthCheck` is `true` -The last section pertains to querying for app instances. -All of these settings should start with `Consul:Discovery:`. +[^2]: This setting only affects operation when `RegisterHealthCheck` is `true` and `Heartbeat:Enabled` is `false` + +This section pertains to querying for app instances. +All of these settings must start with `Consul:Discovery:`. | Key | Description | Default | -| --- | --- | --- | -| `DefaultQueryTag` | The tag to filter on when querying for service instances. | | -| `QueryPassing` | Filter on health status 'passing' when querying for service instances. | `true` | +| --- | ----------- | ------- | +| `DefaultQueryTag` | The tag to filter on when querying for service instances | | +| `QueryPassing` | Filter on health status passing when querying for service instances | `true` | + +For more information about these settings, see the Consul documentation: -For a deeper understanding of these settings, see the Consul documentation on -[registering services](https://developer.hashicorp.com/consul/api-docs/agent/service#register-service), -[health setup during registration](https://developer.hashicorp.com/consul/api-docs/agent/check#register-check) and -[filtering service instances](https://developer.hashicorp.com/consul/api-docs/health). +* [Registering services](https://developer.hashicorp.com/consul/api-docs/agent/service#register-service), +* [Health setup during registration](https://developer.hashicorp.com/consul/api-docs/agent/check#register-check) and +* [Filtering service instances](https://developer.hashicorp.com/consul/api-docs/health). ### Configuring metadata Steeltoe sends metadata (string-based key/value pairs) when registering the currently running app. -Additional metadata can be added in configuration, for example: +Additional metadata can be added in configuration. + +For example: ```json { @@ -117,13 +120,13 @@ Additional metadata can be added in configuration, for example: By default, the following metadata is added: -| Key | Value | -| - | - | -| `group` | Value from `Consul:Discovery:InstanceGroup` | -| Value from `Consul:Discovery:DefaultZoneMetadataName` | Value from `Consul:Discovery:InstanceZone` | +| Key | Value | +| ---------| ----- | +| `group` | Value from `Consul:Discovery:InstanceGroup` | +| Value from `Consul:Discovery:DefaultZoneMetadataName` | Value from `Consul:Discovery:InstanceZone` | | `secure` | Value at `Consul:Discovery:Scheme` equals `https` | ## Health Contributor -The `Steeltoe.Discovery.Consul` package includes an `IHealthContributor` that verifies the Consul server is reachable. +The `Steeltoe.Discovery.Consul` package includes an `IHealthContributor` that verifies that the Consul server is reachable. This health contributor is automatically added to the service container. diff --git a/api/v4/discovery/index.md b/api/v4/discovery/index.md index 7c141264..cf6c6ad8 100644 --- a/api/v4/discovery/index.md +++ b/api/v4/discovery/index.md @@ -2,21 +2,21 @@ Service Discovery enables the use of friendly names for the microservices your app depends on. These microservices typically register themselves at startup to a discovery server, which acts as a central registry. -Each time your app connects to such a microservice, the friendly name is resolved to the actual scheme/host/port by querying the discovery server. +Each time your app connects to one of those microservices, the friendly name is resolved to the actual scheme/host/port by querying the discovery server. -A discovery server can track multiple instances for a single friendly name, which enables your app to load-balance over them. +A discovery server can track multiple instances for a single friendly name, which enables your app to load-balance across instances. It also tracks whether your microservice instances are still alive, using health checks and/or keep-alives. While service discovery enables changing infrastructure without affecting your app, its real power lies in scalability. Discovery servers can typically be run in a cluster to eliminate the single point of failure. -And because they monitor the liveliness of your microservice instances, you can easily scale them up and down. +And because they monitor the liveness of your microservice instances, you can easily scale them up and down. Steeltoe facilitates both registration and querying of discovery servers by providing various implementations of `IDiscoveryClient`. To resolve friendly names, Steeltoe provides implementations of `ILoadBalancer`, which rely on `IDiscoveryClient`. -To use service discovery, you need to: +To use service discovery: -- Add the appropriate NuGet package references to your project -- Register the desired discovery client(s) in the dependency container -- Configure the chosen discovery client(s) for registration and/or consumption -- Activate the provided `HttpClient`/`HttpClientFactory` facilities to resolve friendly names +1. Add the appropriate NuGet package references to your project. +1. Register the desired discovery client(s) in the dependency container. +1. Configure the chosen discovery client(s) for registration and/or consumption. +1. Activate the provided `HttpClient`/`HttpClientFactory` facilities to resolve friendly names. diff --git a/api/v4/discovery/initialize-discovery-client.md b/api/v4/discovery/initialize-discovery-client.md index 102aeff2..beecf2a9 100644 --- a/api/v4/discovery/initialize-discovery-client.md +++ b/api/v4/discovery/initialize-discovery-client.md @@ -3,20 +3,20 @@ This section describes how to activate the Steeltoe discovery client(s), which is a prerequisite for resolving friendly names. Your app can use multiple clients, but is limited to a single instance per server type. -Fundamentally, several things need to happen: +Fundamentally, you have to follow these steps: -1. Add NuGet package references to your project -1. Register the desired discovery client(s) in the dependency container -1. Configure the discovery client(s) -1. Optional: enable debug logging +1. Add NuGet package references to your project. +1. Register the desired discovery client(s) in the dependency container. +1. Configure the discovery client(s). +1. Optional: enable debug logging. ## Add NuGet packages -To get started with Steeltoe Discovery, add a reference to the package(s) containing the discovery technology you may wish to use. +To get started with Steeltoe Discovery, add a reference to the package(s) containing the discovery technology you want to use. Each package also includes all the relevant dependencies. | Package | Description | -| --- | --- | +| ------- | ----------- | | `Steeltoe.Discovery.Configuration` | Query app instances stored in .NET configuration | | `Steeltoe.Discovery.Consul` | Use [HashiCorp Consul](https://www.consul.io/) server | | `Steeltoe.Discovery.Eureka` | Use [Spring Cloud Eureka](https://projects.spring.io/spring-cloud/docs/1.0.3/spring-cloud.html#spring-cloud-eureka-server) server | @@ -24,7 +24,7 @@ Each package also includes all the relevant dependencies. ## ServiceCollection extension methods After installing the NuGet package(s), the next step is to add the Steeltoe discovery client(s) to the service container. -Update your `Program.cs` as shown below: +Update your `Program.cs` as shown here: ```csharp var builder = WebApplication.CreateBuilder(args); @@ -38,18 +38,18 @@ var app = builder.Build(); ``` > [!TIP] -> Alternatively, `builder.AddSteeltoe()` (Steeltoe Bootstrap Auto Configuration) can be used, which uses reflection to determine -> which discovery assemblies are loaded, adding the appropriate clients automatically. +> Alternatively, you can use `builder.AddSteeltoe()` (Steeltoe Bootstrap Auto Configuration), +> which uses reflection to determine which discovery assemblies are loaded and adds the appropriate clients automatically. ## Client configuration Discovery clients need to be explicitly configured to fetch application instances and/or register your app with the discovery server. -See the sub-page for the discovery technology of choice on how to set it up. +See the sub-topic for the discovery technology of choice for instructions about setting it up. ## Enable debug logging Sometimes, you may want to turn on debug logging for service discovery. -To do so, you can modify the `appsettings.json` file and turn on debug logging for the Steeltoe components. +To turn on debug logging, modify the `appsettings.json` file and turn on debug logging for the Steeltoe components. The following example shows a typical `appsettings.json` file: diff --git a/api/v4/discovery/netflix-eureka.md b/api/v4/discovery/netflix-eureka.md index 1e11a625..fd7439cf 100644 --- a/api/v4/discovery/netflix-eureka.md +++ b/api/v4/discovery/netflix-eureka.md @@ -1,14 +1,14 @@ # Netflix Eureka discovery client -The Steeltoe Eureka discovery client lets an application register/unregister itself with a Eureka server +The Steeltoe Eureka discovery client allows an application to register and unregister itself with a Eureka server and provides querying for service instances registered by other applications. -Once activated, the client begins to operate in the background, both registering and renewing service registrations, +After it is activated, the client begins to operate in the background, both registering and renewing service registrations, sending periodic heartbeats to the Eureka server, and also periodically fetching the service registry from the server. -## Usage +## Using Netflix Eureka discovery client -To use this discovery client, add a NuGet package reference to `Steeltoe.Discovery.Eureka` and initialize it from your `Program.cs`: +To use this discovery client, add a NuGet package reference to `Steeltoe.Discovery.Eureka` and initialize it from `Program.cs`. ```csharp var builder = WebApplication.CreateBuilder(args); @@ -21,8 +21,7 @@ var app = builder.Build(); ## Configuration settings -To get the Steeltoe discovery client to properly communicate with the Eureka server, you need to provide -a few configuration settings. There are several sections you may need to configure. +To get the Steeltoe discovery client to properly communicate with the Eureka server, there are several sections you may need to configure. What you provide depends on whether you want your application to register the running app and/or whether it needs to query for other apps. @@ -32,76 +31,79 @@ In most cases, unless you are confident that you understand the effects of chang we recommend that you use the defaults. > [!TIP] -> Since Steeltoe v4, most of these settings can be changed at runtime, which updates the Eureka server accordingly. +> Since Steeltoe v4, most of these settings can be changed at runtime, and the Eureka server is updated accordingly. ### General -The following table describes the configuration settings that control the overall behavior of the client. -All of these settings should start with `Eureka:Client:`. - -| Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether to enable the Eureka client. | `true` | -| `ServiceUrl` | Comma-delimited list of Eureka server endpoints. | `http://localhost:8761/eureka/` | -| `AccessTokenUri` | URL to obtain OAuth2 access token from, before connecting to the Eureka server. | | -| `ClientId` | Client ID for obtaining an access token. | | -| `ClientSecret` | Secret for obtaining an access token. | | -| `Validate_Certificates` | Whether the client validates server certificates. | `true` | -| `EurekaServer:ShouldGZipContent` | Whether to auto-decompress responses from the Eureka server. | `true` | -| `EurekaServer:RetryCount` | Number of times to retry Eureka server requests. | `2` | -| `EurekaServer:ConnectTimeoutSeconds` | How long to wait (in seconds) before a connection to the Eureka server times out. | `5` | -| `EurekaServer:ProxyHost` | Proxy hostname used in contacting the Eureka server. | | -| `EurekaServer:ProxyPort` | Proxy port number used in contacting the Eureka server. | | -| `EurekaServer:ProxyUserName` | Proxy username used in contacting the Eureka server. | | -| `EurekaServer:ProxyPassword` | Proxy password used in contacting the Eureka server. | | -| `Health:Enabled` | Whether to activate an `IHealthContributor` that verifies connectivity to the Eureka server. | `true` | +The following table describes the configuration settings that control the behavior of the client. +All of these settings must start with `Eureka:Client:`. + +| Key | Description | Default | +| --------- | ----------- | ------- | +| `Enabled` | Whether to enable the Eureka client | `true` | +| `ServiceUrl` | Comma-separated list of Eureka server endpoints | `http://localhost:8761/eureka/` | +| `AccessTokenUri` | URL at which to obtain OAuth2 access token, before connecting to the Eureka server | | +| `ClientId` | Client ID for obtaining an access token | | +| `ClientSecret` | Secret for obtaining an access token | | +| `Validate_Certificates` | Whether the client validates server certificates | `true` | +| `EurekaServer:ShouldGZipContent` | Whether to auto-decompress responses from the Eureka server | `true` | +| `EurekaServer:RetryCount` | Number of times to retry Eureka server requests | `2` | +| `EurekaServer:ConnectTimeoutSeconds` | How long to wait (in seconds) before a connection to the Eureka server times out | `5` | +| `EurekaServer:ProxyHost` | Proxy hostname used in contacting the Eureka server | | +| `EurekaServer:ProxyPort` | Proxy port number used in contacting the Eureka server | | +| `EurekaServer:ProxyUserName` | Proxy username used in contacting the Eureka server | | +| `EurekaServer:ProxyPassword` | Proxy password used in contacting the Eureka server | | +| `Health:Enabled` | Whether to activate an `IHealthContributor` that verifies connectivity to the Eureka server | `true` | ### Registration The configuration settings below pertain to registering the currently running app as a service instance in Eureka. -All of these settings should start with `Eureka:Client:`. +All of these settings must start with `Eureka:Client:`. | Key | Description | Default | -| --- | --- | --- | -| `ShouldRegisterWithEureka` | Whether to register the running app as a service instance. | `true` | -| `Health:CheckEnabled` | Whether to query ASP.NET health checks and `IHealthContributor`s during registration and renewals, in order to determine the status of the running app to report back to Eureka (see section below). | `true` | +| --- | ----------- | ------- | +| `ShouldRegisterWithEureka` | Whether to register the running app as a service instance | `true` | +| `Health:CheckEnabled` | Whether to query ASP.NET health checks and `IHealthContributor`s during registration and renewals, to determine the status of the running app to report back to Eureka (see [Configuring health checks](#configuring-health-checks)) | `true` | Additionally, the table below lists the configuration settings that control *how* to register the instance. -All of these settings should start with `Eureka:Instance:`. +All of these settings must start with `Eureka:Instance:`. | Key | Description | Default | -| --- | --- | --- | -| `InstanceId` | Unique ID (within the scope of the app name) of the instance to be registered with Eureka. | computed | -| `AppName` | Name of the application to be registered with Eureka. | computed | -| `AppGroup` | Name of the application group to be registered with Eureka. | | -| `MetadataMap` | Name/value pairs associated with the instance. | computed | -| `HostName` | Hostname on which the instance is registered. | computed | -| `IPAddress` | IP address on which the instance is registered. | computed | -| `UseNetworkInterfaces` | Query the operating system for network interfaces to determine `HostName` and `IPAddress`. | `false` | -| `PreferIPAddress` | Whether to register with `IPAddress` instead of `HostName`. | `false` | -| `VipAddress` | Comma-delimited list of VIP addresses for the instance. | computed | -| `SecureVipAddress` | Comma-delimited list of secure VIP addresses for the instance. | computed | -| `Port` | Non-secure port number on which the instance should receive traffic. | computed | -| `NonSecurePortEnabled` | Whether the non-secure port should be enabled. [^1] | computed | -| `SecurePort` | Secure port on which the instance should receive traffic. | computed | -| `SecurePortEnabled` | Whether the secure port should be enabled. [^1] | computed | -| `RegistrationMethod` | How to register on Cloud Foundry. Can be `route`, `direct`, or `hostname`. [^2] | | -| `InstanceEnabledOnInit` | Whether the instance should take traffic as soon as it is registered. [^3] | `true` | -| `LeaseRenewalIntervalInSeconds` | How often (in seconds) the client sends heartbeats to Eureka to indicate that it is still alive. | `30` | -| `LeaseExpirationDurationInSeconds` | Time (in seconds) that the Eureka server waits since it received the last heartbeat before it marks the instance as down. | `90` | -| `StatusPageUrlPath` | Relative path to the status page for the instance. [^4] | `/info` | -| `StatusPageUrl` | Absolute URL to the status page for the instance (overrides `StatusPageUrlPath`). | computed | -| `HomePageUrlPath` | Relative path to the home page URL for the instance. | `/` | -| `HomePageUrl` | Absolute URL to the home page for the instance (overrides `HomePageUrlPath`). | computed | -| `HealthCheckUrlPath` | Relative path to the health check endpoint of the instance. [^4] | `/health` | -| `HealthCheckUrl` | Absolute URL for health checks of the instance (overrides `HealthCheckUrlPath`). | computed | -| `SecureHealthCheckUrl` | Secure absolute URL for health checks of the instance (overrides `HealthCheckUrlPath`). | computed | -| `AsgName` | AWS auto-scaling group name associated with the instance. | | -| `DataCenterInfo` | Data center the instance is deployed to (`Netflix`, `Amazon` or `MyOwn`). | MyOwn | +| --- | ----------- | ------- | +| `InstanceId` | Unique ID (within the scope of the app name) of the instance to be registered with Eureka | computed | +| `AppName` | Name of the application to be registered with Eureka | computed | +| `AppGroup` | Name of the application group to be registered with Eureka | | +| `MetadataMap` | Name/value pairs associated with the instance | computed | +| `HostName` | Hostname on which the instance is registered | computed | +| `IPAddress` | IP address on which the instance is registered | computed | +| `UseNetworkInterfaces` | Query the operating system for network interfaces to determine `HostName` and `IPAddress` | `false` | +| `PreferIPAddress` | Whether to register with `IPAddress` instead of `HostName` | `false` | +| `VipAddress` | Comma-separated list of VIP addresses for the instance | computed | +| `SecureVipAddress` | Comma-separated list of secure VIP addresses for the instance | computed | +| `Port` | Non-secure port number on which the instance should receive traffic | computed | +| `NonSecurePortEnabled` | Whether the non-secure port should be enabled [^1] | computed | +| `SecurePort` | Secure port on which the instance should receive traffic | computed | +| `SecurePortEnabled` | Whether the secure port should be enabled [^1] | computed | +| `RegistrationMethod` | How to register on Cloud Foundry; can be `route`, `direct`, or `hostname` [^2] | | +| `InstanceEnabledOnInit` | Whether the instance should take traffic as soon as it is registered [^3] | `true` | +| `LeaseRenewalIntervalInSeconds` | How often (in seconds) the client sends heartbeats to Eureka to indicate that it is still alive | `30` | +| `LeaseExpirationDurationInSeconds` | Time (in seconds) that the Eureka server waits after receiving the last heartbeat before it marks the instance as down | `90` | +| `StatusPageUrlPath` | Relative path to the status page for the instance [^4] | `/info` | +| `StatusPageUrl` | Absolute URL to the status page for the instance (overrides `StatusPageUrlPath`) | computed | +| `HomePageUrlPath` | Relative path to the home page URL for the instance | `/` | +| `HomePageUrl` | Absolute URL to the home page for the instance (overrides `HomePageUrlPath`) | computed | +| `HealthCheckUrlPath` | Relative path to the health check endpoint of the instance [^4] | `/health` | +| `HealthCheckUrl` | Absolute URL for health checks of the instance (overrides `HealthCheckUrlPath`) | computed | +| `SecureHealthCheckUrl` | Secure absolute URL for health checks of the instance (overrides `HealthCheckUrlPath`) | computed | +| `AsgName` | AWS auto-scaling group name associated with the instance | | +| `DataCenterInfo` | Data center the instance is deployed to (`Netflix`, `Amazon`, or `MyOwn`) | `MyOwn` | [^1]: When both non-secure and secure ports are enabled, the secure port is preferred during service discovery. + [^2]: Specify `direct` to use container-to-container networking on Cloud Foundry. Specify `hostname` to force using `HostName`. -[^3]: When set to `false`, call `EurekaApplicationInfoManager.UpdateInstance()` after initialization to mark the instance as up. + +[^3]: When set to `false`, call `EurekaApplicationInfoManager.UpdateInstance()` after initialization to mark the instance as `UP`. + [^4]: Add a NuGet package reference to `Steeltoe.Management.Endpoint` to use its `health` and `info` actuator paths. The values for `Port` and `SecurePort`, and whether they are enabled, are automatically determined from the ASP.NET address bindings. [^1] @@ -110,21 +112,21 @@ for how to influence them using environment variables. It is also possible to use dynamic port bindings (by setting the port number to `0` in ASP.NET). In that case, Steeltoe adds a random number (outside the valid port range) to the `InstanceId` to make it unique. -Once the app has fully started, the assigned port numbers are updated in Eureka, but the `InstanceId` does not change. +After the app has fully started, the assigned port numbers are updated in Eureka, but the `InstanceId` does not change. ### Querying -The configuration settings that pertain to querying the Eureka registry for apps (used by the load balancers during service discovery) are listed below. -All of these settings should start with `Eureka:Client:`. +The configuration settings that pertain to querying the Eureka registry for apps (used by the load balancers during service discovery) are shown in the following table. +All of these settings must start with `Eureka:Client:`. | Key | Description | Default | -| --- | --- | --- | -| `ShouldFetchRegistry` | Whether to periodically fetch registry information from the Eureka server. | `true` | -| `RegistryFetchIntervalSeconds` | How often (in seconds) to fetch registry information from the Eureka server. | `30` | -| `ShouldFilterOnlyUpInstances` | Whether to include only instances with UP status after fetching the list of applications. | `true` | -| `ShouldDisableDelta` | Whether to fetch the full registry each time or fetch only deltas. | `false` | -| `RegistryRefreshSingleVipAddress` | Whether to only fetch registry information for the specified VIP address. | `false` | -| `Health:MonitoredApps` | Comma-delimited list of applications in Eureka this app depends on (see section below). | | +| --- | ----------- | ------- | +| `ShouldFetchRegistry` | Whether to periodically fetch registry information from the Eureka server | `true` | +| `RegistryFetchIntervalSeconds` | How often (in seconds) to fetch registry information from the Eureka server | `30` | +| `ShouldFilterOnlyUpInstances` | Whether to include only instances with `UP` status after fetching the list of applications | `true` | +| `ShouldDisableDelta` | Whether to fetch the full registry each time (`true`) or fetch only deltas (`false`) | `false` | +| `RegistryRefreshSingleVipAddress` | Whether to fetch registry information only for the specified VIP address | `false` | +| `Health:MonitoredApps` | Comma-separated list of applications in Eureka that this app depends on (see [Configuring health contributors](#configuring-health-contributors)) | | ## Configuring health contributors @@ -136,7 +138,7 @@ compute the health of the connection. This contributor is automatically activated, but can be turned off by setting `Eureka:Client:Health:Enabled` to `false`. The second contributor that you can enable is the `EurekaApplicationsHealthContributor`. -By default, this contributor is not enabled, so you must add it to the service container yourself: +By default, this contributor is not enabled, so you must add it to the service container explicitly: ```csharp builder.Services.AddSingleton(); @@ -144,10 +146,11 @@ builder.Services.AddSingleton(); appManager.UpdateInstance(newStatus: null, newOverriddenStatus: null, @@ -195,8 +196,8 @@ appManager.UpdateInstance(newStatus: null, newOverriddenStatus: null, }); ``` -> [!WARN] -> Once metadata has been updated from code, later metadata changes in configuration are ignored. +> [!IMPORTANT] +> After metadata has been updated from code, later metadata changes in configuration are ignored. In general, additional metadata does not change the behavior of applications, unless they are made aware of the meaning of the metadata. @@ -213,7 +214,9 @@ add the path to your certificate file(s) to `appsettings.json`. For example: } } ``` + or: + ```json "Certificates": { "Eureka": { @@ -227,14 +230,16 @@ or: > To support certificate rotation, the configuration keys and the files on disk are automatically monitored for changes. > [!TIP] -> A single certificate can be shared with both Config Server and Eureka, by using the key "Certificates" instead of "Certificates:Eureka". +> A single certificate can be shared with both Config Server and Eureka by using the key `Certificates`, instead of `Certificates:Eureka`. ### Using custom HTTP headers -The communication with Eureka server uses the `HttpClientFactory` [pattern](https://learn.microsoft.com/dotnet/architecture/microservices/implement-resilient-applications/use-httpclientfactory-to-implement-resilient-http-requests), -which makes it aware of DNS changes over time and enables to tweak the handler pipeline. +The communication with Eureka server uses the `HttpClientFactory` pattern, +which makes it aware of DNS changes over time and enables it to tweak the handler pipeline. For more information, +see the [Microsoft documentation](https://learn.microsoft.com/dotnet/architecture/microservices/implement-resilient-applications/use-httpclientfactory-to-implement-resilient-http-requests). + +To send a custom HTTP header with every request, create a `DelegatingHandler` and add it to the pipeline. -To send a custom HTTP header with every request, create a `DelegatingHandler` and add it to the pipeline: ```csharp builder.Services.AddEurekaDiscoveryClient(); builder.Services.AddTransient(); @@ -257,5 +262,5 @@ public sealed class ExtraRequestHeaderDelegatingHandler : DelegatingHandler } ``` -> [!NOTE] -> To send an extra header to the OAuth2 endpoint, replace `"Eureka"` with `"AccessTokenForEureka"` in the example above. +> [!TIP] +> To send an extra header to the OAuth2 endpoint, replace `"Eureka"` with `"AccessTokenForEureka"` in the preceding example. diff --git a/api/v4/fileshares/index.md b/api/v4/fileshares/index.md index 5bdc23be..d20fbd9b 100644 --- a/api/v4/fileshares/index.md +++ b/api/v4/fileshares/index.md @@ -1,5 +1,5 @@ # Windows Network File Shares -Steeltoe's `WindowsNetworkFileShare` class provides a simplified experience for interacting with SMB file shares by making [P/Invoke calls](https://learn.microsoft.com/cpp/dotnet/how-to-call-native-dlls-from-managed-code-using-pinvoke) to underlying Windows APIs, specifically to `mpr.dll`. For more background on SMB, see the [Microsoft SMB Protocol documentation](https://learn.microsoft.com/windows/win32/fileio/microsoft-smb-protocol-and-cifs-protocol-overview). +The Steeltoe `WindowsNetworkFileShare` class provides a simplified experience for interacting with SMB file shares by making [P/Invoke calls](https://learn.microsoft.com/cpp/dotnet/how-to-call-native-dlls-from-managed-code-using-pinvoke) to underlying Windows APIs, specifically to `mpr.dll`. For more information about SMB, see the [Microsoft SMB Protocol documentation](https://learn.microsoft.com/windows/win32/fileio/microsoft-smb-protocol-and-cifs-protocol-overview). -Network shares are not the most cloud-native way to deal with files. For new development, consider exploring message queues, caches, blob stores, and NoSQL stores. The alternatives offer greater resiliency and decoupling from backing services. That said, sometimes the alternatives are not viable. For .NET applications deployed to Microsoft Windows Servers, Steeltoe provides a stepping stone towards cloud-native in the form of the `WindowsNetworkFileShare`. For applications deployed to Linux hosts on the Tanzu Platform, [volume services](https://docs.vmware.com/en/VMware-Tanzu-Application-Service/6.0/tas-for-vms/enable-vol-services.html) are available. +Network shares are not the most cloud-native way to deal with files. For new development, consider exploring message queues, caches, blob stores, and NoSQL stores. The alternatives offer greater resiliency and decoupling from backing services. That said, sometimes the alternatives are not viable. For .NET applications deployed to Microsoft Windows Servers, Steeltoe provides a stepping stone towards cloud-native deployment in the form of the `WindowsNetworkFileShare`. For applications deployed to Linux hosts on the Tanzu Platform, [volume services](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform/tanzu-platform-for-cloud-foundry/10-0/tpcf/enable-vol-services.html) are available. diff --git a/api/v4/fileshares/usage.md b/api/v4/fileshares/usage.md index becff280..4b3e145c 100644 --- a/api/v4/fileshares/usage.md +++ b/api/v4/fileshares/usage.md @@ -1,10 +1,10 @@ -# Usage +# Using Network File Shares Before starting with Steeltoe's Windows Network File Share library, you should already have a plan for interacting with the file system. Steeltoe only manages the connection to the file share. ## Add NuGet References -To use the `WindowsNetworkFileShare` class, you need to add a reference to the `Steeltoe.Common.Net` NuGet package. +To use the `WindowsNetworkFileShare` class, add a reference to the `Steeltoe.Common.Net` NuGet package. ## Managing the Connection @@ -36,9 +36,9 @@ using (new WindowsNetworkFileShare(@"\\server\path", new NetworkCredential("user ### Managing Credentials -Credentials are generally required for interacting with SMB shares. `WindowsNetworkFileShare` does not have an opinion on where those credentials are stored. However, as a general guideline, storing credentials with your application's code or standard configuration is not recommended. Consider using the [CredHub Service Broker](https://docs.vmware.com/en/VMware-Tanzu-Application-Service/6.0/tas-for-vms/credhub-index.html) for storing and retrieving your credentials. +Credentials are generally required for interacting with SMB shares. `WindowsNetworkFileShare` does not have an opinion on where those credentials are stored. However, as a general guideline, storing credentials with your application's code or standard configuration is not recommended. Consider using the [CredHub Service Broker](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/credhub-service-broker/services/credhub-sb/index.html) for storing and retrieving your credentials. -When used in conjunction with the Cloud Foundry Configuration Provider, you can access the values as follows: +When used with the Cloud Foundry Configuration Provider, you can access the values as follows: ```shell dotnet add package Steeltoe.Configuration.CloudFoundry diff --git a/api/v4/initializr/index.md b/api/v4/initializr/index.md index 2f19084f..acacf910 100644 --- a/api/v4/initializr/index.md +++ b/api/v4/initializr/index.md @@ -2,12 +2,15 @@ An Initializr jumpstarts .NET development by generating projects based on project metadata. Metadata may include, among other properties, a project name, a namespace, and a list of dependencies. -At the core of an Initializr is the _[InitializrService](https://github.com/SteeltoeOSS/InitializrService)_. -_InitializrService_ provides several REST/HTTP endpoints, which includes an endpoint to generate projects, and an endpoint to provide smart clients the metadata needed to construct user interfaces. +At the core of an Initializr is the [Steeltoe InitializrService](https://github.com/SteeltoeOSS/InitializrService). +InitializrService provides several REST/HTTP endpoints, including: -It is possible to have a fully functioning Initializr deployment by simply deploying the _InitializrService_. -A more user-friendly deployment may include a user interface, such as a web frontend or an IDE plugin. -A deployment may also leverage a _[Spring Cloud Config Server](https://cloud.spring.io/spring-cloud-config/multi/multi__spring_cloud_config_server.html)_ to access a configuration store. -As an example, the [Steeltoe Initializr deployment](https://start.steeltoe.io) includes _[InitializrWeb](https://github.com/SteeltoeOSS/InitializrWeb)_ for a friendly user experience and a _Spring Cloud Config Server_ using a GitHub-maintained configuration. +* an endpoint to generate projects +* an endpoint to provide smart clients the metadata needed to construct user interfaces -_InitializrWeb_ is the reference UI for the Steeltoe Initializr and is an example of a smart client. It uses project metadata from the _InitializrService_ to populate its web controls with, for example, supported .NET target frameworks and Steeltoe versions. +It is possible to have a fully functioning Initializr deployment by simply deploying the InitializrService. +A more user-friendly deployment might include a user interface, such as a web frontend. +A deployment may also use a [Spring Cloud Config Server](https://cloud.spring.io/spring-cloud-config/multi/multi__spring_cloud_config_server.html) to access a configuration store. +As an example, the [Steeltoe Initializr deployment](https://start.steeltoe.io) includes [InitializrWeb](https://github.com/SteeltoeOSS/InitializrWeb) for a friendly user experience and a Spring Cloud Config Server using a GitHub-maintained configuration. + +InitializrWeb is the reference UI for the Steeltoe Initializr and is an example of a smart client. It uses project metadata from the InitializrService to populate its web controls with, for example, supported .NET target frameworks and Steeltoe versions. diff --git a/api/v4/initializr/initializr-service.md b/api/v4/initializr/initializr-service.md index 786233d3..ea5b7061 100644 --- a/api/v4/initializr/initializr-service.md +++ b/api/v4/initializr/initializr-service.md @@ -1,6 +1,6 @@ # InitializrService -The _InitializrService_ provides 4 REST/HTTP endpoints: +The InitializrService provides four REST/HTTP endpoints: * `api/` * `api/about` @@ -10,9 +10,9 @@ The _InitializrService_ provides 4 REST/HTTP endpoints: ## `api/` `api/` accepts `GET` requests and returns a help document. -The document includes available parameters (and their defaults) and dependencies, as well as CLI samples. +The document includes available parameters (and their defaults) and dependencies, plus CLI samples. -```bash +```shell # sample: view help doc $ http -p b https://start.steeltoe.io/api/ ... @@ -30,9 +30,9 @@ The URI templates take a set of parameters to customize the result of a request. ## `api/about` -`api/about` accepts `GET` requests and returns the _InitialzrService_ "About" information. +`api/about` accepts `GET` requests and returns the InitializrService "About" information. -```bash +```shell # sample: view "About" document $ http -p b https://start.steeltoe.io/api/about { @@ -46,11 +46,11 @@ $ http -p b https://start.steeltoe.io/api/about ## `api/config` -`api/config` accepts `GET` requests and returns _InitializrService_ configuration. -The returned document includes *all* configuration which can include superfluous details. -Sub-endpoints are available allowing more targeted responses. +`api/config` accepts `GET` requests and returns InitializrService configuration. +The returned document includes *all* configuration, which can include superfluous details. +Sub-endpoints are available, allowing more targeted responses. -`api/config/projectMetadata` can be used by smart clients, such as the _InitializrWeb_, to assist in creating user interfaces. +`api/config/projectMetadata` can be used by smart clients, such as the InitializrWeb, to assist in creating user interfaces. The following endpoints can be used by CLI users to browse project configuration options: @@ -61,7 +61,7 @@ The following endpoints can be used by CLI users to browse project configuration * `api/config/languages` * `api/config/steeltoeVersions` -```bash +```shell # sample: list available Steeltoe versions $ http -p b https://start.steeltoe.io/api/config/steeltoeVersions [ @@ -105,12 +105,13 @@ $ http https://start.steeltoe.io/api/config/dependencies | jq '.[] .values[] .id `api/project` accepts `GET` and `POST` requests and returns a project as an archive. -Projects are configured by using HTTP parameters, such as `name` for the project name and `steeltoeVersion` for the Steeltoe version. -The parameter `dependencies` is a little different than other parameters in that it is set to a comma-separated list of dependency IDs. +Projects are configured using HTTP parameters, such as `name` for the project name and `steeltoeVersion` for the Steeltoe version. +The parameter `dependencies` is different than other parameters in that it is set to a comma-separated list of dependency IDs. -_Note: to get a list of parameters and dependencies, send a `GET` request to `api/`._ +> [!TIP] +> To get a list of parameters and dependencies, send a `GET` request to `api/`. -```bash +```shell # sample: generate a .NET Core App 3.1 project with actuator endpoints and a Redis backend: $ http https://start.steeltoe.io/api/project dotNetFramework=netcoreapp3.1 dependencies==actuators,redis -d ``` diff --git a/api/v4/initializr/initializr-web.md b/api/v4/initializr/initializr-web.md index 313cae70..264db5c8 100644 --- a/api/v4/initializr/initializr-web.md +++ b/api/v4/initializr/initializr-web.md @@ -1,61 +1,60 @@ # InitializrWeb -_InitializrWeb_ is a web frontend for an Initializr deployment. -It uses _InitializrApi_-provided project metadata to populate its interface for easy perusal and selection by an end user. -After selecting desired project parameters, an end user uses _InitializrWeb_ to submit project generation requests to the _InitializrApi_. +InitializrWeb is a web frontend for an Initializr deployment. +It uses InitializrApi-provided project metadata to populate its interface for easy perusal and selection by an end user. +After selecting desired project parameters, an end user uses InitializrWeb to submit project generation requests to the InitializrApi. ## Overview Steeltoe Initializr -The interface is made up of 4 areas: +The interface is made up of four areas: * project configuration area * project action area (bottom) -* UI configuration (right) +* Dependencies configuration (right) * external links (left) The remainder of this document focuses on the project configuration and action areas. -## Configuration +## Project configuration -The configuration area exposes 5 project properties to the end user: +The configuration area exposes five project properties to the end user: -* name -* C# namespace -* application name -* description -* Steeltoe version -* .NET target framework -* .NET template -* dependencies +* **Name**: application name +* **Namespace**: code namespace +* **Description**: application description +* **Steeltoe**: Steeltoe version +* **.NET Framework**: .NET target framework +* **Language**: The programming language -## Actions +## Project actions -The actions area provides 3 project actions to the end user: +The actions area provides four project actions to the end user: -* generate -* explore -* share +* **Generate** +* **Explore** +* **Bookmark** +* **Share** ### Generate -Clicking "Generate" submits the current configuration to the _InitializrApi_ to generate a project archive. -The resultant project archive is a Zip file named based on the project name. +Clicking **Generate** submits the current configuration to the InitializrApi to generate a project archive. +The resultant project archive is a Zip file with a name based on the project name. Steeltoe Initializr generate a project ### Explore -Clicking "Explore" submits the current configuration to the _InitializrApi_ to generate a project archive. +Clicking **Explore** submits the current configuration to the InitializrApi to generate a project archive. The resultant project archive is expanded in the UI so that the end user can explore the project. Steeltoe Initializr explore project ### Share -Clicking "Share" displays a URL that represents the current project configuration. +Clicking **Share** displays a URL that represents the current project configuration. It can be shared with other developers or saved in a bookmark. -Note that the URL is specific to _InitializrWeb_ and cannot be used directly with the _InitializrApi_. +Note that the URL is specific to InitializrWeb and cannot be used directly with the InitializrApi. Steeltoe Initializr share project configuration diff --git a/api/v4/logging/dynamic-console-logging.md b/api/v4/logging/dynamic-console-logging.md index 381567a0..4209251d 100644 --- a/api/v4/logging/dynamic-console-logging.md +++ b/api/v4/logging/dynamic-console-logging.md @@ -1,15 +1,18 @@ # Dynamic Console Logging -This logging provider is a wrapper around the [Microsoft Console Logger](https://learn.microsoft.com/dotnet/core/extensions/logging-providers#console). It allows for querying the active loggers and their minimum levels, as well as then modifying the levels dynamically at runtime via the [loggers actuator](../management/loggers.md). +This logging provider is a wrapper around the [Microsoft Console Logger](https://learn.microsoft.com/dotnet/core/extensions/logging-providers#console). It allows you to: + +* Query the active loggers and their minimum levels +* Modify the levels dynamically at runtime using the [loggers actuator](../management/loggers.md) > [!CAUTION] > External tool integration involves sending the fully-qualified logger name over HTTP. Avoid using colons in the name of a logger to prevent invalid HTTP requests. -## Usage +## Using Dynamic Console Logging -Before starting to use Steeltoe provider, you should know how [Logging in .NET](https://learn.microsoft.com/aspnet/core/fundamentals/logging) works, as Steeltoe provides nothing more than a wrapper around the existing Microsoft console logger. +Before starting to use Steeltoe provider, you should know how [Logging in .NET](https://learn.microsoft.com/aspnet/core/fundamentals/logging) works; Steeltoe provides nothing more than a wrapper around the existing Microsoft console logger. -To use the Steeltoe logging provider, you need to: +To use the Steeltoe logging provider: 1. Add the appropriate NuGet package reference to your project. 1. Configure logging settings. @@ -17,15 +20,15 @@ To use the Steeltoe logging provider, you need to: ### Add NuGet References -To use the logging provider, you need to add a reference to the `Steeltoe.Logging.DynamicConsole` NuGet package. +To use the logging provider, add a reference to the `Steeltoe.Logging.DynamicConsole` NuGet package. ### Configure Settings -As mentioned earlier, the Steeltoe Logging provider is a wrapper around the Microsoft Console logging provider. Consequently, you can configure it the same way you would the Microsoft provider. For more details on how this is done, see [Configure logging](https://learn.microsoft.com/aspnet/core/fundamentals/logging#configure-logging). +The Steeltoe Logging provider is a wrapper around the Microsoft Console logging provider, so you can configure it the same way you would the Microsoft provider. For more details about how to do this, see [Configure logging](https://learn.microsoft.com/aspnet/core/fundamentals/logging#configure-logging). ### Add the Logging Provider -To use the provider, you need to add it to the logging builder by using the `AddDynamicConsole()` extension method: +To use the provider, add it to the logging builder by using the `AddDynamicConsole()` extension method: ```csharp using Steeltoe.Logging.DynamicConsole; diff --git a/api/v4/logging/dynamic-serilog-logging.md b/api/v4/logging/dynamic-serilog-logging.md index 6ee13c07..2199e747 100644 --- a/api/v4/logging/dynamic-serilog-logging.md +++ b/api/v4/logging/dynamic-serilog-logging.md @@ -1,10 +1,10 @@ # Dynamic Serilog Logging -This logging provider integrates with [Serilog](https://serilog.net/). It enables logger minimum levels configured via Serilog to be queried and modified at runtime via the [loggers actuator](../management/loggers.md). +This logging provider integrates with [Serilog](https://serilog.net/). It enables logger minimum levels configured through Serilog to be queried and modified at runtime using the [loggers actuator](../management/loggers.md). -## Usage +## Using Dynamic Serilog Logging -To use the Serilog Dynamic Logger, you need to do the following: +To use the Serilog logging provider: 1. Add the appropriate NuGet package reference to your project. 1. Configure Logging settings. @@ -12,11 +12,11 @@ To use the Serilog Dynamic Logger, you need to do the following: ### Add NuGet References -To use the logging provider, you need to add a reference to the `Steeltoe.Logging.DynamicSerilog` NuGet package. +To use the logging provider, add a reference to the `Steeltoe.Logging.DynamicSerilog` NuGet package. ### Configure Settings -As mentioned earlier, the Serilog Dynamic Logger provider extends Serilog. Consequently, you can configure it the same way you would Serilog. For more details on how this is done, see [Serilog-Settings-Configuration](https://github.com/serilog/serilog-settings-configuration). +The Serilog Dynamic Logger provider extends Serilog, so you can configure it the same way you would Serilog. For more information, see [Serilog-Settings-Configuration](https://github.com/serilog/serilog-settings-configuration). ```json { @@ -60,7 +60,7 @@ var serilogConfiguration = new LoggerConfiguration() ### Add Serilog Dynamic Logger -To use this logging provider, you need to add it to the logging builder by using the `AddDynamicSerilog()` extension method: +To use this logging provider, add it to the logging builder by using the `AddDynamicSerilog()` extension method: ```csharp using Steeltoe.Logging.DynamicSerilog; @@ -70,13 +70,14 @@ builder.Logging.AddDynamicSerilog(); ``` If you built the Serilog configuration from code, use the appropriate overload instead: + ```csharp builder.Logging.AddDynamicSerilog(serilogConfiguration); ``` ### Serilog API usage -Because dynamic logging is built on the `Microsoft.Extensions.Logging` abstractions, changing log levels dynamically **won't work** if you're using Serilog's static `Log` class directly. +Because dynamic logging is built on the `Microsoft.Extensions.Logging` abstractions, changing log levels dynamically **doesn't work** if you're using Serilog's static `Log` class directly. ```csharp using Serilog; @@ -103,7 +104,7 @@ var exampleLogger = loggerFactory.CreateLogger("Example"); exampleLogger.LogInformation("Hello from Example."); ``` -The Serilog dynamic logger supports the use of logger scopes, as well as Serilog's enrichers and destructuring. +The Serilog dynamic logger supports the use of logger scopes, and also Serilog's enrichers and destructuring. ```csharp using Serilog.Context; diff --git a/api/v4/logging/index.md b/api/v4/logging/index.md index 0422cbb9..f8f0be83 100644 --- a/api/v4/logging/index.md +++ b/api/v4/logging/index.md @@ -2,5 +2,5 @@ Steeltoe includes two logging providers that enhance existing logger libraries with support for managing minimum log levels at runtime through the [Steeltoe Management logger endpoint](../management/loggers.md) and [recording distributed trace information](../tracing/index.md#log-correlation). -* [Dynamic Console Logging](./dynamic-console-logging.md) works with `Microsoft.Extensions.Logging.Console`. +* [Dynamic Console Logging](./dynamic-console-logging.md) works with `Microsoft.Extensions.Logging.Console` * [Dynamic Serilog Logging](./dynamic-serilog-logging.md) works with `Serilog` diff --git a/api/v4/management/cloud-foundry.md b/api/v4/management/cloud-foundry.md index 3781c1e5..ca730f57 100644 --- a/api/v4/management/cloud-foundry.md +++ b/api/v4/management/cloud-foundry.md @@ -5,11 +5,11 @@ Integration with [Tanzu Apps Manager](https://techdocs.broadcom.com/us/en/vmware When used, this endpoint enables the following additional functionality on Cloud Foundry: * A variant of the [hypermedia](./hypermedia.md) endpoint is registered at `/cloudfoundryapplication`. -* All endpoints are additionally mapped under the base path `/cloudfoundryapplication`. +* All endpoints are also mapped under the base path `/cloudfoundryapplication`. * [Authentication and authorization](#security) for your Cloud Foundry environment is added to the request pipeline. -> [!NOTE] -> The Cloud Foundry integration will not work unless the [Cloud Foundry Configuration Provider](../configuration/cloud-foundry-provider.md) has also been configured. +> [!IMPORTANT] +> The Cloud Foundry integration works only when the [Cloud Foundry Configuration Provider](../configuration/cloud-foundry-provider.md) has also been configured. ## Configure Settings @@ -17,22 +17,22 @@ Typically, no additional configuration is needed. However, the following table d Each key must be prefixed with `Management:Endpoints:CloudFoundry`. | Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether the endpoint is enabled. | `true` | -| `ID` | The unique ID of the endpoint. | `""` | -| `Path` | The relative path at which the endpoint is exposed. | same as `ID` | -| `RequiredPermissions` | Permissions required to access the endpoint, when running on Cloud Foundry. | `Restricted` | -| `AllowedVerbs` | An array of HTTP verbs the endpoint is exposed at. | `GET` | -| `ValidateCertificates` | Whether to validate server certificates. | `true` | -| `ApplicationId` | The ID of the application used in permission checks. | | -| `CloudFoundryApi` | The URL of the Cloud Foundry API. | | +| --- | ----------- | ------- | +| `Enabled` | Whether the endpoint is enabled | `true` | +| `ID` | The unique ID of the endpoint | `""` | +| `Path` | The relative path at which the endpoint is exposed | same as `ID` | +| `RequiredPermissions` | Permissions required to access the endpoint when running on Cloud Foundry | `Restricted` | +| `AllowedVerbs` | An array of HTTP verbs at which the endpoint is exposed | `GET` | +| `ValidateCertificates` | Whether to validate server certificates | `true` | +| `ApplicationId` | The ID of the application used in permission checks | | +| `CloudFoundryApi` | The URL of the Cloud Foundry API | | ## Enable HTTP Access -The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. +The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting with the `Path` setting described in the preceding section. The default path is `/cloudfoundryapplication`. -See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. +See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. To add the actuator to the service container, add a [CORS](#cross-origin-resource-sharing) policy, register security middleware and map its route, use the `AddCloudFoundryActuator` extension method. @@ -48,15 +48,15 @@ builder.Services.AddCloudFoundryActuator(); ``` > [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators; +> this enables individually turning them on/off at runtime via configuration. ### Cross Origin Resource Sharing -When viewing an application in Apps Manager, HTTP requests are sent directly to application instances with the bearer token of the logged-in user attached. +When viewing an application in Apps Manager, HTTP requests are sent directly to application instances, with the bearer token of the logged-in user attached. The nature of this integration requires the use of Cross Origin Resource Sharing ([CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)). -The policy defined in Steeltoe intends to limit sharing to the minimum required for the endpoints to function, however there is no way for Steeltoe to discover or even guess at what the origin of an Apps Manager instance could be. -As such, the default policy will allow any origin, unless the policy is customized. You should consider [customizing the CORS policy](./using-endpoints.md#customizing-the-cors-policy) to be more specific. +The policy defined in Steeltoe intends to limit sharing to the minimum required for the endpoints to function; however, there is no way for Steeltoe to discover or infer what the origin of an Apps Manager instance could be. +As such, the default policy allows any origin, unless the policy is customized. You should consider [customizing the CORS policy](./using-endpoints.md#customizing-the-cors-policy) to be more specific. ## Security @@ -65,7 +65,7 @@ The Cloud Foundry security middleware requires a valid UAA access token to be pr Additionally, the security middleware evaluates the token to determine whether the authenticated user has permission to access the management endpoint. > [!NOTE] -> The Cloud Foundry security middleware is only active when your application is running on Cloud Foundry. +> The Cloud Foundry security middleware is active only when your application is running on Cloud Foundry. ## External access @@ -77,5 +77,5 @@ For this reason, all endpoints are exposed by default at `/cloudfoundryapplicati In addition, the endpoints may be secured by whatever security mechanism the application itself uses. For more details, see [securing actuators](./using-endpoints.md#securing-endpoints). > [!CAUTION] -> Applying an authorization policy on `/actuator` will also impact `/cloudfoundryapplication`, which will break the integration with Apps Manager. -> In order to prevent public access to `/actuator` when running on Cloud Foundry, consider configuring actuators to [use an alternate port](./using-endpoints.md#configure-global-settings). +> An authorization policy on `/actuator` also applies to `/cloudfoundryapplication`, which then breaks the integration with Apps Manager. +> To prevent public access to `/actuator` when running on Cloud Foundry, consider configuring actuators to [use an alternate port](./using-endpoints.md#configure-global-settings). diff --git a/api/v4/management/dbmigrations.md b/api/v4/management/dbmigrations.md index 5f9e24e4..875bbe2a 100644 --- a/api/v4/management/dbmigrations.md +++ b/api/v4/management/dbmigrations.md @@ -1,9 +1,9 @@ # Database Migrations -The Steeltoe Database Migrations endpoint exposes information about database migrations that are available to an application's data source that has been built with Entity Framework Core (EF Core). EF Core migrations give developers the ability to update an application's database schema while staying consistent with the application's data model without removing any existing data. +The Steeltoe Database Migrations endpoint exposes information about database migrations that are available to an application's data source that has been built with Entity Framework Core (EF Core). EF Core migrations give developers the ability to update an application's database schema while staying consistent with the application's data model, and without removing any existing data. -> [!NOTE] -> Please review Microsoft's [EF Core Migrations Overview](https://learn.microsoft.com/ef/core/managing-schemas/migrations) for more in-depth information. +> [!TIP] +> For more detailed information, see [EF Core Migrations Overview](https://learn.microsoft.com/ef/core/managing-schemas/migrations) in the Microsoft documentation. ## Configure Settings @@ -11,19 +11,19 @@ The following table describes the configuration settings that you can apply to t Each key must be prefixed with `Management:Endpoints:DbMigrations:`. | Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether the endpoint is enabled. | `true` | -| `ID` | The unique ID of the endpoint. | `dbmigrations` | -| `Path` | The relative path at which the endpoint is exposed. | same as `ID` | -| `RequiredPermissions` | Permissions required to access the endpoint, when running on Cloud Foundry. | `Restricted` | -| `AllowedVerbs` | An array of HTTP verbs the endpoint is exposed at. | `GET` | +| --- | ----------- | ------- | +| `Enabled` | Whether the endpoint is enabled | `true` | +| `ID` | The unique ID of the endpoint | `dbmigrations` | +| `Path` | The relative path at which the endpoint is exposed | same as `ID` | +| `RequiredPermissions` | Permissions required to access the endpoint when running on Cloud Foundry | `Restricted` | +| `AllowedVerbs` | An array of HTTP verbs at which the endpoint is exposed | `GET` | ## Enable HTTP Access -The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. +The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting with the `Path` setting described in the preceding section. The default path is `/actuator/dbmigrations`. -See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. +See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. To add the actuator to the service container and map its route, use the `AddDbMigrationsActuator` extension method. @@ -37,14 +37,14 @@ builder.Services.AddDbMigrationsActuator(); ``` > [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators; +> this enables individually turning them on/off at runtime via configuration. ## Sample Output -This endpoint returns a list of objects representing each registered `DbContext` along with its migrations, grouped by status (pending or applied). +This endpoint returns a list of objects representing each registered `DbContext`, along with its migrations, grouped by status (pending or applied). -The response will always be returned as JSON, like this: +The response is always returned as JSON: ```json { diff --git a/api/v4/management/env.md b/api/v4/management/env.md index 25eb7e47..b444e359 100644 --- a/api/v4/management/env.md +++ b/api/v4/management/env.md @@ -8,22 +8,22 @@ The following table describes the configuration settings that you can apply to t Each key must be prefixed with `Management:Endpoints:Env:`. | Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether the endpoint is enabled. | `true` | -| `ID` | The unique ID of the endpoint. | `env` | -| `Path` | The relative path at which the endpoint is exposed. | same as `ID` | -| `RequiredPermissions` | Permissions required to access the endpoint, when running on Cloud Foundry. | `Restricted` | -| `AllowedVerbs` | An array of HTTP verbs the endpoint is exposed at. | `GET` | -| `KeysToSanitize` | An array of keys to sanitize. [^1] | `[ "password", "secret", "key", "token", ".*credentials.*", "vcap_services" ]` | +| --- | ----------- | ------- | +| `Enabled` | Whether the endpoint is enabled | `true` | +| `ID` | The unique ID of the endpoint | `env` | +| `Path` | The relative path at which the endpoint is exposed | same as `ID` | +| `RequiredPermissions` | Permissions required to access the endpoint, when running on Cloud Foundry | `Restricted` | +| `AllowedVerbs` | An array of HTTP verbs at which the endpoint is exposed | `GET` | +| `KeysToSanitize` | An array of keys to sanitize [^1] | `[ "password", "secret", "key", "token", ".*credentials.*", "vcap_services" ]` | [^1]: A key can be a simple string that the property must end with, or a regular expression. A case-insensitive match is always performed. Use a single-element empty string to disable sanitization. ## Enable HTTP Access -The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. +The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting with the `Path` setting described in the preceding section. The default path is `/actuator/env`. -See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. +See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. To add the actuator to the service container and map its route, use the `AddEnvironmentActuator` extension method. @@ -37,14 +37,14 @@ builder.Services.AddEnvironmentActuator(); ``` > [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators; +> this enables individually turning them on/off at runtime via configuration. ## Sample Output This endpoint returns a list of objects representing information from `IConfiguration`. -The response will always be returned as JSON, like this: +The response is always returned as JSON: ```json { diff --git a/api/v4/management/health.md b/api/v4/management/health.md index ca5bfdf5..cd9dbe47 100644 --- a/api/v4/management/health.md +++ b/api/v4/management/health.md @@ -5,13 +5,13 @@ It is often used to monitor software and alert someone if a production system go Health information is collected from all `IHealthContributor` implementations registered in the application, as well as from [ASP.NET Core Health Checks](https://learn.microsoft.com/aspnet/core/host-and-deploy/health-checks). -Steeltoe includes several contributors out of the box that you can use. +Steeltoe includes several contributors, out-of-the-box, that you can use. Other Steeltoe components typically add their own contributors where applicable. -Also, and perhaps more importantly, you can write your own. +In addition, you can write your own. By default, the final application health state is computed by the registered `IHealthAggregator` implementation. It is responsible for sorting out all of the returned statuses from each `IHealthContributor` and [`IHealthCheck`](https://learn.microsoft.com/dotnet/api/microsoft.extensions.diagnostics.healthchecks.ihealthcheck) and deriving an overall application health state. -The built-in aggregator returns the "worst" status returned from the contributors and checks. +The built-in aggregator returns the *worst* status returned from the contributors and checks. ## Configure Settings @@ -19,26 +19,29 @@ The following table describes the configuration settings that you can apply to t Each key must be prefixed with `Management:Endpoints:Health:`. | Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether the endpoint is enabled. | `true` | -| `ID` | The unique ID of the endpoint. | `health` | -| `Path` | The relative path at which the endpoint is exposed. | same as `ID` | -| `RequiredPermissions` | Permissions required to access the endpoint, when running on Cloud Foundry. | `Restricted` | -| `AllowedVerbs` | An array of HTTP verbs the endpoint is exposed at. | `GET` | -| `ShowComponents` | Whether health check components should be included in the response. | `Never` | -| `ShowDetails` | Whether details of health check components should be included in the response. | `Never` | -| `Claim` | The claim required in `HttpContext.User` when `ShowComponents` and/or `ShowDetails` is set to `WhenAuthorized`. | | -| `Role` | The role required in `HttpContext.User` when `ShowComponents` and/or `ShowDetails` is set to `WhenAuthorized`. | | - -The depth of information exposed by the health endpoint depends on the `ShowComponents` and `ShowDetails` properties, which can both be configured with one of the following values: - -| Name | Description | -| --- | --- | -| `Never` | Never shown. | -| `WhenAuthorized` | Shown only to authorized users. | -| `Always` | Always shown. | - -`ShowDetails` only has an effect when `ShowComponents` is set to `Always`, or `WhenAuthorized` and the request is authorized. +| --- | ----------- | ------- | +| `Enabled` | Whether the endpoint is enabled | `true` | +| `ID` | The unique ID of the endpoint | `health` | +| `Path` | The relative path at which the endpoint is exposed | same as `ID` | +| `RequiredPermissions` | Permissions required to access the endpoint when running on Cloud Foundry | `Restricted` | +| `AllowedVerbs` | An array of HTTP verbs in which the endpoint is exposed | `GET` | +| `ShowComponents` | Whether health check components should be included in the response | `Never` | +| `ShowDetails` | Whether details of health check components should be included in the response | `Never` | +| `Claim` | The claim required in `HttpContext.User` when `ShowComponents` and/or `ShowDetails` is set to `WhenAuthorized` | | +| `Role` | The role required in `HttpContext.User` when `ShowComponents` and/or `ShowDetails` is set to `WhenAuthorized` | | + +The depth of information exposed by the health endpoint depends on the `ShowComponents` and `ShowDetails` properties; both can be configured with one of the following values: + +| Name | Description | +| ------- | ----------- | +| `Never` | Never shown | +| `WhenAuthorized` | Shown only to authorized users | +| `Always` | Always shown | + +`ShowDetails` has an effect only when `ShowComponents` is set to: + +* `Always` +* `WhenAuthorized` if the request is authorized Authorized users can be configured by setting `Claim` or `Role`. A user is considered to be authorized when they are in the given role or have the specified claim. @@ -63,10 +66,10 @@ The following example uses `Management:Endpoints:Health:Claim`: ## Enable HTTP Access -The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. +The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting with the `Path` setting described in the preceding section. The default path is `/actuator/health`. -See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. +See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. To add the actuator to the service container and map its route, use the `AddHealthActuator` extension method. @@ -80,12 +83,12 @@ builder.Services.AddHealthActuator(); ``` > [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators; +> this enables individually turning them on/off at runtime via configuration. By default, the health status is reflected in the HTTP response status code. For example, when a health check fails, the response status code is `503 Service Unavailable`. -The configuration key `Management:Endpoints:UseStatusCodeFromResponse` can be set to `false`, which makes the health response status code always be `200 OK`. +The configuration key `Management:Endpoints:UseStatusCodeFromResponse` can be set to `false`, which makes the health check always respond with status code `200 OK`. Clients can overrule this per request by sending an `X-Use-Status-Code-From-Response` HTTP header with the value `true` or `false`. > [!TIP] @@ -112,7 +115,7 @@ Clients can overrule this per request by sending an `X-Use-Status-Code-From-Resp This endpoint returns the top-level status, along with the details of the contributors and checks. -The response will always be returned as JSON, and this is the default value: +The response is always returned as JSON, and this is the default value: ```json { @@ -149,7 +152,7 @@ When `ShowComponents` and `ShowDetails` are set to `Always`, or when set to `Whe ## Health Groups -Should you need to check application health based on a subset of health contributors, you may specify the name of the grouping and a comma-separated list of contributors to include like this: +If you want to check application health based on a subset of health contributors, you can specify the name of the grouping and a comma-separated list of contributors to include: ```json { @@ -167,9 +170,9 @@ Should you need to check application health based on a subset of health contribu } ``` -While group names are case-sensitive, the entries in `Include` are case-insensitive and will only activate health contributors with a matching `Id`, and/or ASP.NET health check registrations with a matching name. +While group names are case-sensitive, the entries in `Include` are case-insensitive and activate only health contributors with a matching `Id`, and/or ASP.NET health check registrations with a matching name. -For any group that has been defined, you may access health information from the group by appending the group name to the HTTP request URL. For example: `/actuator/health/example-group`. +For any group that has been defined, you can access health information from the group by appending the group name to the HTTP request URL. For example: `/actuator/health/example-group`. `ShowComponents` and `ShowDetails` can also be set at the group level, overriding the settings found at the endpoint level. @@ -198,15 +201,16 @@ For any group that has been defined, you may access health information from the ### Kubernetes Health Groups Applications deployed on Kubernetes can provide information about their internal state with [Container Probes](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#container-probes). -Depending on your [Kubernetes configuration](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/), the kubelet will call those probes and react to the result. +Depending on your [Kubernetes configuration](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/), the kubelet calls those probes and reacts to the result. Steeltoe provides an [`ApplicationAvailability`](https://github.com/SteeltoeOSS/Steeltoe/blob/main/src/Management/src/Endpoint/Actuators/Health/Availability/ApplicationAvailability.cs) class for managing various types of application state. -Out of the box, support is provided for Liveness and Readiness, where each is exposed in a corresponding `IHealthContributor` and health group. -While these health contributors are included, they are disabled by default and must be enabled in configuration (as demonstrated in the example below). +Support is provided, out of the box, for Liveness and Readiness, where each is exposed in a corresponding `IHealthContributor` and health group. +While these health contributors are included, they are disabled by default and must be enabled in the configuration (as shown in the example below). To change the health contributors that are included in either of the two built-in groups, use the same style of configuration described above. -Please note that this will _replace_ these groupings, so if you would like to _add_ an `IHealthContributor` you will need to include the original entry. -These entries demonstrate enabling the probes, their groups and including disk space in both groups: +Note that this _replaces_ the default groupings, so if you want to _add_ an `IHealthContributor`, you must include the original entry. + +The following example enables both contributors and their groups, and specifies to include disk space in both groups: ```json { @@ -235,22 +239,27 @@ These entries demonstrate enabling the probes, their groups and including disk s #### Liveness -The "Liveness" state of an application instance tells whether its internal state allows it to work correctly, or recover by itself if it's currently failing. A broken "Liveness" state means that the application is in a state that it cannot recover from, and the infrastructure should restart the application. +The Liveness state of an application tells whether its internal state is valid. If Liveness is broken, this means that the application itself is in a failed state and cannot recover from it. In this case, the best course of action is to restart the application instance. -Out of the box, any of Steeltoe's extension methods that set up the health actuator will initialize the liveness state `LivenessState.Correct`. The only other defined state for liveness is `LivenessState.Broken`, though Steeltoe code does not currently cover any conditions that set this state. +Out of the box, any of Steeltoe's extension methods that set up the health actuator initialize the liveness state with `LivenessState.Correct`. The only other defined state for liveness is `LivenessState.Broken`, though Steeltoe code does not currently cover any conditions that set this state. -> [!NOTE] -> In general, the "Liveness" state should not depend on external system checks such as a database, queue, or cache server. Including checks on external systems could trigger massive restarts and cascading failures across the platform. +> [!CAUTION] +> In general, the Liveness state should not depend on external system checks such as a database, queue, or cache server. Including checks on external systems could trigger massive restarts and cascading failures across the platform. #### Readiness -The "Readiness" state of an application instance describes whether the application is ready to handle traffic. A failing "Readiness" state tells the platform that it should not route traffic to the application instance. +The Readiness state tells whether the application is ready to accept client requests. If the Readiness state is unready, the platform should not route traffic to this instance. If an application is too busy processing a task queue, then it could declare itself as busy until its load is manageable again. + +Out of the box, any of Steeltoe's extension methods that set up the health actuator also: -Out of the box, any of Steeltoe's extension methods that set up the health actuator will also register a callback on [`ApplicationStarted`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.hosting.iapplicationlifetime.applicationstarted) to initialize the readiness state to `AcceptingTraffic` when the application has started, and register a callback on [`ApplicationStopping`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.hosting.iapplicationlifetime.applicationstopping) to change the state to `RefusingTraffic` when the application begins to shut down. These are the only defined states for this availability type. +* Register a callback on [`ApplicationStarted`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.hosting.iapplicationlifetime.applicationstarted) to initialize the readiness state to `AcceptingTraffic` when the application has started +* Register a callback on [`ApplicationStopping`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.hosting.iapplicationlifetime.applicationstopping) to change the state to `RefusingTraffic` when the application begins to shut down + +These are the only defined states for this availability type. #### Managing Application Availability State -Application components can retrieve the current availability state at any time, by requesting `ApplicationAvailability` from the dependency injection container and calling methods on it: +Application components can retrieve the current availability state at any time by requesting `ApplicationAvailability` from the dependency injection container and calling methods on it: ```csharp [ApiController] @@ -285,7 +294,10 @@ app.Run(); ## Creating a Custom Health Contributor -If you wish to provide custom health information for your application, create a class that implements the `IHealthContributor` interface and then add it to the service container. +If you want to provide custom health information for your application: + +1. Create a class that implements the `IHealthContributor` interface. +1. Add the new class to the service container. The following example contributor always returns a `HealthStatus` of `WARNING`: @@ -355,7 +367,7 @@ When `ShowComponents` and `ShowDetails` are set to `Always`, or when set to `Whe ## ASP NET Core Health Checks -ASP.NET Core also offers [middleware and libraries](https://learn.microsoft.com/aspnet/core/host-and-deploy/health-checks) and abstractions for reporting health. There is wide community support for these abstractions from libraries such as [AspNetCore.Diagnostics.HealthChecks](https://github.com/Xabaril/AspNetCore.Diagnostics.HealthChecks). You can use these community-provided health checks and make them available over the health actuator endpoint (for integration with Cloud Foundry or any other infrastructure that depends on this format). In addition, Steeltoe Connectors expose functionality to get the connection string, which is needed to set up these community health checks. +ASP.NET Core offers [middleware and libraries](https://learn.microsoft.com/aspnet/core/host-and-deploy/health-checks) and abstractions for reporting health. There is wide community support for these abstractions from libraries such as [AspNetCore.Diagnostics.HealthChecks](https://github.com/Xabaril/AspNetCore.Diagnostics.HealthChecks). You can use these community-provided health checks and make them available using the health actuator (for integration with Cloud Foundry or any other infrastructure that depends on this format). In addition, Steeltoe Connectors expose functionality to get the connection string, which is needed to set up these community health checks. For example, to use the Steeltoe MySQL connector, but replace its health contributor with the ASP.NET Core community health check, use the following code in `Program.cs`: diff --git a/api/v4/management/heapdump.md b/api/v4/management/heapdump.md index 51cc6276..4514c096 100644 --- a/api/v4/management/heapdump.md +++ b/api/v4/management/heapdump.md @@ -7,25 +7,32 @@ You can use the Steeltoe Heap Dump endpoint to capture and download a mini-dump The following table describes the configuration settings that you can apply to the endpoint. Each key must be prefixed with `Management:Endpoints:HeapDump:`. -| Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether the endpoint is enabled. | `true` | -| `ID` | The unique ID of the endpoint. | `heapdump` | -| `Path` | The relative path at which the endpoint is exposed. | same as `ID` | -| `RequiredPermissions` | Permissions required to access the endpoint, when running on Cloud Foundry. | `Restricted` | -| `AllowedVerbs` | An array of HTTP verbs the endpoint is exposed at. | `GET` | -| `HeapDumpType` | Sets the type of heap dump to capture. | `Full` | +| Key | Description | Default | +| --------- | ----------- | ------- | +| `Enabled` | Whether the endpoint is enabled | `true` | +| `ID` | The unique ID of the endpoint | `heapdump` | +| `Path` | The relative path at which the endpoint is exposed | same as `ID` | +| `RequiredPermissions` | Permissions required to access the endpoint, when running on Cloud Foundry | `Restricted` | +| `AllowedVerbs` | An array of HTTP verbs at which the endpoint is exposed | `GET` | +| `HeapDumpType` | Sets the type of heap dump to capture | `Full` | The `HeapDumpType` setting is supported on Linux and Windows only. -Acceptable values are `Normal`, `WithHeap`, `Triage`, and `Full`. -On macOS, this setting is ignored and a gcdump is always captured. +Acceptable values are: + +* `Normal` +* `WithHeap` +* `Triage` +* `Full` + +> [!NOTE] +> On macOS, the `HeapDumpType` setting is ignored and a gcdump is always captured. ## Enable HTTP Access -The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. +The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting with the `Path` setting described in the preceding section. The default path is `/actuator/heapdump`. -See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. +See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. To add the actuator to the service container and map its route, use the `AddHeapDumpActuator` extension method. @@ -39,5 +46,5 @@ builder.Services.AddHeapDumpActuator(); ``` > [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators; +> this enables individually turning them on/off at runtime via configuration. diff --git a/api/v4/management/httpexchanges.md b/api/v4/management/httpexchanges.md index efa337e7..b0b8b4f0 100644 --- a/api/v4/management/httpexchanges.md +++ b/api/v4/management/httpexchanges.md @@ -1,8 +1,8 @@ # HTTP Exchanges -The Steeltoe HTTP Exchanges endpoint provides the ability to view the last several requests made of your application. +The Steeltoe HTTP Exchanges endpoint provides the ability to view the last several requests sent to your application. -When you activate this endpoint, an `IHttpExchangesRepository` implementation is registered that stores HTTP request/response information in memory, that can be retrieved by using the endpoint. +When you activate this endpoint, an `IHttpExchangesRepository` implementation is registered, which stores HTTP request/response information in memory. This endpoint provides access to that information. ## Configure Settings @@ -10,29 +10,30 @@ The following table describes the configuration settings that you can apply to t Each key must be prefixed with `Management:Endpoints:HttpExchanges:`. | Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether the endpoint is enabled. | `true` | -| `ID` | The unique ID of the endpoint. | `httpexchanges` | -| `Path` | The relative path at which the endpoint is exposed. | same as `ID` | -| `RequiredPermissions` | Permissions required to access the endpoint, when running on Cloud Foundry. | `Restricted` | -| `AllowedVerbs` | An array of HTTP verbs the endpoint is exposed at. | `GET` | -| `Capacity` | Size of the circular buffer of exchanges. | 100 | -| `IncludeRequestHeaders` | Whether to return headers from the HTTP request. | `true` | -| `RequestHeaders` | An array of HTTP request headers to return unredacted, in addition to the default set. | | -| `IncludeResponseHeaders` | Whether to return headers from the HTTP response. | `true` | -| `ResponseHeaders` | An array of HTTP response headers to return unredacted, in addition to the default set. | | -| `IncludePathInfo` | Whether to return the path from the HTTP request URL. | `true` | -| `IncludeQueryString` | Whether to return the query string parameters from the request URL. | `true` | -| `IncludeUserPrincipal` | Whether to return the username from [`HttpContext.User`](https://learn.microsoft.com/dotnet/api/system.security.claims.claimsprincipal). | `false` | -| `IncludeRemoteAddress` | Whether to return the IP address from the sender. | `false` | -| `IncludeSessionId` | Whether to return the user's session ID. | `false` | -| `IncludeTimeTaken` | Whether to return the request duration. | `true` | -| `Reverse` | Whether to return exchanges in reverse order (newest first). | `true` | +| --- | ----------- | ------- | +| `Enabled` | Whether the endpoint is enabled | `true` | +| `ID` | The unique ID of the endpoint | `httpexchanges` | +| `Path` | The relative path at which the endpoint is exposed | same as `ID` | +| `RequiredPermissions` | Permissions required to access the endpoint when running on Cloud Foundry | `Restricted` | +| `AllowedVerbs` | An array of HTTP verbs at which the endpoint is exposed | `GET` | +| `Capacity` | Size of the circular buffer of exchanges | 100 | +| `IncludeRequestHeaders` | Whether to return headers from the HTTP request | `true` | +| `RequestHeaders` | An array of HTTP request headers to return unredacted, in addition to the default set | | +| `IncludeResponseHeaders` | Whether to return headers from the HTTP response | `true` | +| `ResponseHeaders` | An array of HTTP response headers to return unredacted, in addition to the default set | | +| `IncludePathInfo` | Whether to return the path from the HTTP request URL | `true` | +| `IncludeQueryString` | Whether to return the query string parameters from the request URL | `true` | +| `IncludeUserPrincipal` | Whether to return the username from [`HttpContext.User`](https://learn.microsoft.com/dotnet/api/system.security.claims.claimsprincipal) | `false` | +| `IncludeRemoteAddress` | Whether to return the IP address from the sender | `false` | +| `IncludeSessionId` | Whether to return the user's session ID | `false` | +| `IncludeTimeTaken` | Whether to return the request duration | `true` | +| `Reverse` | Whether to return exchanges in reverse order (newest first) | `true` | All request and response header values are redacted by default, except for the whitelisted entries below. To return additional headers unredacted, add them to the `RequestHeaders` or `ResponseHeaders` arrays. Whitelist of HTTP request headers: + - Accept - Accept-Charset - Accept-Encoding @@ -61,6 +62,7 @@ Whitelist of HTTP request headers: - X-UA-Compatible Whitelist of HTTP response headers: + - Accept-Ranges - Age - Allow @@ -86,10 +88,10 @@ Whitelist of HTTP response headers: ## Enable HTTP Access -The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. +The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting with the `Path` setting described in the preceding section. The default path is `/actuator/httpexchanges`. -See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. +See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. To add the actuator to the service container and map its route, use the `AddHttpExchangesActuator` extension method. @@ -103,14 +105,14 @@ builder.Services.AddHttpExchangesActuator(); ``` > [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators; +> this enables individually turning them on/off at runtime via configuration. ## Sample Output This endpoint returns an array of exchanges. -The response will always be returned as JSON, like this: +The response is always returned as JSON: ```json { diff --git a/api/v4/management/hypermedia.md b/api/v4/management/hypermedia.md index 11b60d4d..3a251c98 100644 --- a/api/v4/management/hypermedia.md +++ b/api/v4/management/hypermedia.md @@ -9,16 +9,16 @@ The following table describes the configuration settings that you can apply to t Each key must be prefixed with `Management:Endpoints:Actuator:`. Note this key differs from the convention used by other actuators. | Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether the endpoint is enabled. | `true` | -| `ID` | The unique ID of the endpoint. | `""` | -| `Path` | The relative path at which the endpoint is exposed. | same as `ID` | -| `RequiredPermissions` | Permissions required to access the endpoint, when running on Cloud Foundry. | `Restricted` | -| `AllowedVerbs` | An array of HTTP verbs the endpoint is exposed at. | `GET` | +| --- | ----------- | ------- | +| `Enabled` | Whether the endpoint is enabled | `true` | +| `ID` | The unique ID of the endpoint | `""` | +| `Path` | The relative path at which the endpoint is exposed | same as `ID` | +| `RequiredPermissions` | Permissions required to access the endpoint when running on Cloud Foundry | `Restricted` | +| `AllowedVerbs` | An array of HTTP verbs at which the endpoint is exposed | `GET` | > [!NOTE] > This endpoint is exposed automatically because its ID is empty. To reference this actuator in exposure settings, -> first configure a non-empty ID. Because the Path is the same as ID unless specified, set it to empty explicitly: +> start by configuring a non-empty ID. Because the Path is the same as ID unless otherwise specified, set it to empty explicitly: > ```json > { > "Management": { @@ -37,14 +37,14 @@ Each key must be prefixed with `Management:Endpoints:Actuator:`. Note this key d ## Enable HTTP Access -The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. +The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting with the `Path` setting described in the preceding section. The default path is `/actuator`. -> [!NOTE] -> When running on Cloud Foundry, the [Cloud Foundry Actuator](./cloud-foundry.md) should be used instead, -> whose default path is `/cloudfoundryapplication`. +> [!IMPORTANT] +> When running on Cloud Foundry, the [Cloud Foundry Actuator](./cloud-foundry.md) should be used instead. +> Its default path is `/cloudfoundryapplication`. -See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. +See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. To add the actuator to the service container and map its route, use the `AddHypermediaActuator` extension method. @@ -58,14 +58,14 @@ builder.Services.AddHypermediaActuator(); ``` > [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators; +> this enables individually turning them on/off at runtime via configuration. ## Sample Output This endpoint returns a list of management endpoints, including itself. -The response will always be returned as JSON, like this: +The response is always returned as JSON: ```json { diff --git a/api/v4/management/info.md b/api/v4/management/info.md index 81ea051a..70ee9269 100644 --- a/api/v4/management/info.md +++ b/api/v4/management/info.md @@ -1,10 +1,10 @@ # Info -The Steeltoe Info endpoint exposes information about the running application, such as its version and the Steeltoe version in use. +The Steeltoe Info endpoint exposes information about the running application, such as its version and the version of Steeltoe in use. Information is collected from all `IInfoContributor` implementations registered in the application. -Steeltoe includes a couple contributor implementations out of the box that you can use. -Also, and perhaps more importantly, you can write your own. +Steeltoe includes a couple of contributor implementations out of the box that you can use. +You can also write your own implementations. ## Configure Settings @@ -12,19 +12,19 @@ The following table describes the configuration settings that you can apply to t Each key must be prefixed with `Management:Endpoints:Info:`. | Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether the endpoint is enabled. | `true` | -| `ID` | The unique ID of the endpoint. | `info` | -| `Path` | The relative path at which the endpoint is exposed. | same as `ID` | -| `RequiredPermissions` | Permissions required to access the endpoint, when running on Cloud Foundry. | `Restricted` | -| `AllowedVerbs` | An array of HTTP verbs the endpoint is exposed at. | `GET` | +| --- | ----------- | ------- | +| `Enabled` | Whether the endpoint is enabled | `true` | +| `ID` | The unique ID of the endpoint | `info` | +| `Path` | The relative path at which the endpoint is exposed | same as `ID` | +| `RequiredPermissions` | Permissions required to access the endpoint, when running on Cloud Foundry | `Restricted` | +| `AllowedVerbs` | An array of HTTP verbs at which the endpoint is exposed | `GET` | ## Enable HTTP Access -The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. +The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting with the `Path` setting described in the preceding section. The default path is `/actuator/info`. -See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. +See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. To add the actuator to the service container and map its route, use the `AddInfoActuator` extension method. @@ -38,8 +38,8 @@ builder.Services.AddInfoActuator(); ``` > [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators; +> this enables individually turning them on/off at runtime via configuration. ## Built-in Contributors @@ -50,6 +50,7 @@ This contributor exposes file/version info for both the application and the incl ### Configuration This contributor exposes any values below the `Info` configuration key. For example: + ```json { "Info": { @@ -68,15 +69,14 @@ This contributor exposes any values below the `Info` configuration key. For exam ### Git properties -Exposes information from the `git.properties` Spring Boot file, if available. -Shows information from git, such as branch/tag name, commit hash, and remote. +This contributor exposes information from the `git.properties` Spring Boot file, if available. The file contains information from git, such as branch/tag name, commit hash, and remote. > [!TIP] > For an example of how to use this contributor within MSBuild using [GitInfo](https://github.com/devlooped/GitInfo), see the [Steeltoe Management sample](https://github.com/SteeltoeOSS/Samples/tree/main/Management/src). ## Sample Output -Depending on the registered contributors, this endpoint returns JSON such as this: +The response is always returned as JSON: ```json { @@ -125,7 +125,7 @@ Depending on the registered contributors, this endpoint returns JSON such as thi ## Custom Contributors -If you wish to provide custom information for your application, create a class that implements the `IInfoContributor` interface and then add it to the service container. +If you want to provide custom information for your application, create a class that implements the `IInfoContributor` interface and then add it to the service container. The following example contributor adds the local server time: diff --git a/api/v4/management/loggers.md b/api/v4/management/loggers.md index ff1ee6ef..304f24e3 100644 --- a/api/v4/management/loggers.md +++ b/api/v4/management/loggers.md @@ -10,21 +10,21 @@ The following table describes the configuration settings that you can apply to t Each key must be prefixed with `Management:Endpoints:Loggers:`. | Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether the endpoint is enabled. | `true` | -| `ID` | The unique ID of the endpoint. | `loggers` | -| `Path` | The relative path at which the endpoint is exposed. | same as `ID` | -| `RequiredPermissions` | Permissions required to access the endpoint, when running on Cloud Foundry. | `Restricted` | -| `AllowedVerbs` | An array of HTTP verbs the endpoint is exposed at. | `GET`, `POST` | +| --- | ----------- | ------- | +| `Enabled` | Whether the endpoint is enabled | `true` | +| `ID` | The unique ID of the endpoint | `loggers` | +| `Path` | The relative path at which the endpoint is exposed | same as `ID` | +| `RequiredPermissions` | Permissions required to access the endpoint when running on Cloud Foundry | `Restricted` | +| `AllowedVerbs` | An array of HTTP verbs at which the endpoint is exposed | `GET`, `POST` | ## Enable HTTP Access -The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. +The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting with the `Path` setting described in the preceding section. The default path is `/actuator/loggers`. -See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. +See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. -To add the actuator to the service container and map its route, use the `AddInfoActuator` extension method. +To add the actuator to the service container and map its route, use the `AddLoggersActuator` extension method. Add the following code to `Program.cs` to use the actuator endpoint: @@ -36,12 +36,20 @@ builder.Services.AddLoggersActuator(); ``` > [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators; +> this enables individually turning them on/off at runtime via configuration. -> [!TIP] -> When `AddLoggersActuator` is called, it tries to register [Dynamic Console Logging](../logging/dynamic-console-logging.md). -> If you'd like to use Serilog instead, call `AddDynamicSerilog` *before* `AddLoggersActuator`. +> [!NOTE] +> `AddAllActuators()` and `AddLoggingActuator()` automatically configure [Dynamic Console Logging](../logging/dynamic-console-logging.md). If you want to use [Dynamic Serilog Logging](../logging/dynamic-serilog-logging.md) instead, add it *before* adding actuators. For example: +> +> ```csharp +> using Steeltoe.Logging.DynamicSerilog; +> using Steeltoe.Management.Endpoint.Actuators.All; +> +> var builder = WebApplication.CreateBuilder(args); +> builder.Logging.AddDynamicSerilog(); +> builder.Services.AddLoggersActuator(); +> ``` ## Retrieving Minimum Log Levels @@ -60,7 +68,7 @@ The response below shows the loggers and their minimum levels for the following ``` To retrieve the currently active loggers and their minimum log levels, send an HTTP `GET` request to `/actuator/loggers`, -which returns the response below: +which returns the following response: ```json { @@ -102,22 +110,22 @@ which returns the response below: } ``` -The response above shows only effective levels, because there are no runtime overrides yet. +The response shows only effective levels, because there are no runtime overrides yet. ## Modifying Minimum Log Levels -Minimum log levels can be changed at runtime by adding the category to the URL of a `POST` request and the minimum level to assign in the request body. +Minimum log levels can be changed at runtime by adding the category to the URL of a `POST` request, and the minimum level to assign in the request body. The category is the fully-qualified name of the logger, which works like a prefix. -For example, changing the minimum log level of `Microsoft.AspNetCore` will affect all loggers whose category starts with -`Microsoft.AspNetCore`, such as `Microsoft.AspNetCore` and `Microsoft.AspNetCore.Cors` (but not `Microsoft.AspNetCoreExtra`). +For example, changing the minimum log level of `Microsoft.AspNetCore` affects all loggers for which the category starts with +`Microsoft.AspNetCore`; for example, `Microsoft.AspNetCore` and `Microsoft.AspNetCore.Cors` (but not `Microsoft.AspNetCoreExtra`). > [!NOTE] > [Spring Boot Admin](https://www.baeldung.com/spring-boot-changing-log-level-at-runtime) and [Tanzu Apps Manager](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform/tanzu-platform-for-cloud-foundry/4-0/tpcf/using-actuators.html#manage-log-levels) > provide a UI to change the minimum levels at runtime. For compatibility, the level names used by this actuator differ from the names used by .NET. > > | Actuator level | .NET level | -> | --- | --- | +> | -------------- | ------ | > | `OFF` | `LogLevel.None` | > | `FATAL` | `LogLevel.Critical` | > | `ERROR` | `LogLevel.Error` | @@ -126,7 +134,7 @@ For example, changing the minimum log level of `Microsoft.AspNetCore` will affec > | `DEBUG` | `LogLevel.Debug` | > | `TRACE` | `LogLevel.Trace` | -Using the `appsettings.json` from above, change the minimum log level of the `Steeltoe.Management` category to `TRACE` +Using the `appsettings.json` from earlier, change the minimum log level of the `Steeltoe.Management` category to `TRACE` by sending a POST request to `/actuator/loggers/Steeltoe.Management` with the following request body: ```json @@ -135,12 +143,12 @@ by sending a POST request to `/actuator/loggers/Steeltoe.Management` with the fo } ``` -> [!TIP] +> [!CAUTION] > Because the logger category is part of the request URL, avoid using colons in the name to prevent invalid HTTP requests. -To verify the change was applied, send a `GET` request to `/actuator/loggers` to see the updated loggers. +To verify that the change was applied, send a `GET` request to `/actuator/loggers` to see the updated loggers. The response below shows that the `Steeltoe.Management` logger (and its descendants) now use a minimum level of `TRACE`. -Furthermore, the `Steeltoe.Management` entry contains both `configuredLevel` and `effectiveLevel`, which means the level can be reset. +In addition, the `Steeltoe.Management` entry contains both `configuredLevel` and `effectiveLevel`, which means the level can be reset. ```json { @@ -185,7 +193,7 @@ Furthermore, the `Steeltoe.Management` entry contains both `configuredLevel` and ## Resettings Minimum Log Levels -To revert back to the original minimum level, send another `POST` request to `/actuator/loggers/Steeltoe.Management`, but with the following request body: +To change back to the original minimum level, send another `POST` request to `/actuator/loggers/Steeltoe.Management`, with the following request body: ```json { @@ -193,14 +201,14 @@ To revert back to the original minimum level, send another `POST` request to `/a } ``` -To verify the change was applied, send a `GET` request to `/actuator/loggers`, which returns the same JSON response as before overriding the minimum levels. +To verify that the change was applied, send a `GET` request to `/actuator/loggers`, which returns the same JSON response as before overriding the minimum levels. ## Configuration Changes Dynamic log levels in Steeltoe are implemented by wrapping an existing `ILoggerProvider` and intercepting calls to its `CreateLogger` method. -The returned `ILogger` instances are wrapped as well, so that the minimum level can be changed at runtime. +The returned `ILogger` instances are also wrapped so that the minimum level can be changed at runtime. -When changes to `appsettings.json` are saved, existing loggers are updated with the new minimum levels, unless overridden. +When changes to `appsettings.json` are saved, existing loggers are updated with the new minimum levels, unless they are overridden. A reset of an overridden logger reverts to the updated level from `appsettings.json`. > [!TIP] diff --git a/api/v4/management/mappings.md b/api/v4/management/mappings.md index 405dd2b0..50f64293 100644 --- a/api/v4/management/mappings.md +++ b/api/v4/management/mappings.md @@ -1,6 +1,6 @@ # Route Mappings -You can use the Steeltoe Route Mappings actuator to retrieve the HTTP endpoints in your app that originate from ASP.NET Minimal APIs, API/MVC Controllers, Razor Pages and Blazor. +You can use the Steeltoe Route Mappings actuator to retrieve the HTTP endpoints in your app that originate from ASP.NET Minimal APIs, API/MVC Controllers, Razor Pages, and Blazor. ## Configure Settings @@ -8,20 +8,20 @@ The following table describes the configuration settings that you can apply to t Each key must be prefixed with `Management:Endpoints:Mappings:`. | Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether the endpoint is enabled. | `true` | -| `ID` | The unique ID of the endpoint. | `mappings` | -| `Path` | The relative path at which the endpoint is exposed. | same as `ID` | -| `RequiredPermissions` | Permissions required to access the endpoint, when running on Cloud Foundry. | `Restricted` | -| `AllowedVerbs` | An array of HTTP verbs the endpoint is exposed at. | `GET` | -| `IncludeActuators` | Whether to include actuator endpoints in the response. | `true` | +| --- | ----------- | ------- | +| `Enabled` | Whether the endpoint is enabled | `true` | +| `ID` | The unique ID of the endpoint | `mappings` | +| `Path` | The relative path at which the endpoint is exposed | same as `ID` | +| `RequiredPermissions` | Permissions required to access the endpoint when running on Cloud Foundry | `Restricted` | +| `AllowedVerbs` | An array of HTTP verbs at which the endpoint is exposed | `GET` | +| `IncludeActuators` | Whether to include actuator endpoints in the response | `true` | ## Enable HTTP Access -The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. +The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting with the `Path` setting described in the preceding section. The default path is `/actuator/mappings`. -See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. +See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. To add the actuator to the service container and map its route, use the `AddRouteMappingsActuator` extension method. @@ -35,14 +35,14 @@ builder.Services.AddRouteMappingsActuator(); ``` > [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators; +> this enables individually turning them on/off at runtime via configuration. ## Sample Output This endpoint returns a list of route mappings and their parameters. -The response will always be returned as JSON, like this: +The response is always returned as JSON: ```json { diff --git a/api/v4/management/prometheus.md b/api/v4/management/prometheus.md index d44a8475..94d930f6 100644 --- a/api/v4/management/prometheus.md +++ b/api/v4/management/prometheus.md @@ -6,11 +6,11 @@ The Steeltoe Prometheus endpoint configures the [OpenTelemetry Prometheus Export The Prometheus endpoint does not automatically instrument your application, but does make it easy to export metrics in the Prometheus metrics format, which can be used by tools like [Prometheus Server](https://prometheus.io/) and the [Metric Registrar for Tanzu Platform for Cloud Foundry](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform/tanzu-platform-for-cloud-foundry/10-0/tpcf/metric-registrar-index.html). -The [Steeltoe Management samples](https://github.com/SteeltoeOSS/Samples/tree/main/Management/src/ActuatorWeb/README.md) can help you understand how to use this tool. +See the [Steeltoe Management samples](https://github.com/SteeltoeOSS/Samples/tree/main/Management/src/ActuatorWeb/README.md) for more information about using this tool. ## Add NuGet Reference -To use the Prometheus endpoint, you need to add a reference to the `Steeltoe.Management.Prometheus` NuGet package. +To use the Prometheus endpoint, add a reference to the `Steeltoe.Management.Prometheus` NuGet package. ## Configure Settings @@ -18,22 +18,22 @@ The following table describes the configuration settings that you can apply to t Each key must be prefixed with `Management:Endpoints:Prometheus:`. | Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether the endpoint is enabled. | `true` | -| `ID` | The unique ID of the endpoint. | `prometheus` | -| `Path` | The relative path at which the endpoint is exposed. | same as `ID` | -| `RequiredPermissions` | Permissions required to access the endpoint, when running on Cloud Foundry. | `Restricted` | -| `AllowedVerbs` | An array of HTTP verbs the endpoint is exposed at. | `GET` | +| --- | ----------- | ------- | +| `Enabled` | Whether the endpoint is enabled | `true` | +| `ID` | The unique ID of the endpoint | `prometheus` | +| `Path` | The relative path at which the endpoint is exposed | same as `ID` | +| `RequiredPermissions` | Permissions required to access the endpoint when running on Cloud Foundry | `Restricted` | +| `AllowedVerbs` | An array of HTTP verbs at which the endpoint is exposed | `GET` | > [!NOTE] -> The `AllowedVerbs` setting is inherited from Steeltoe's `EndpointOptions`, but is not intended to work for the Prometheus exporter, which is only registered to respond to `GET` requests. +> The `AllowedVerbs` setting is inherited from the Steeltoe `EndpointOptions`, but is not intended to work for the Prometheus exporter, which is only registered to respond to `GET` requests. ## Enable HTTP Access -The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. +The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting with the `Path` setting described in the preceding section. The default path is `/actuator/prometheus`. -See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. +See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. To add the actuator to the service container and map its route, use the `AddPrometheusActuator` extension method. @@ -49,7 +49,7 @@ builder.Services.AddPrometheusActuator(); ### Configuring the request pipeline for Prometheus In addition to the options described in [using endpoints](./using-endpoints.md), `AddPrometheusActuator` exposes an `Action?` that can be used to configure the branched request pipeline that is used in the underlying OpenTelemetry package. -This pipeline would need to be configured if, as an example, you are configuring an authorization policy. +This pipeline must be configured if, as an example, you are configuring an authorization policy. ```csharp builder.Services.AddPrometheusActuator(true, pipeline => pipeline.UseAuthorization()); @@ -57,51 +57,57 @@ builder.Services.AddPrometheusActuator(true, pipeline => pipeline.UseAuthorizati ## Instrumentation -In order for the Prometheus endpoint to return metrics, the application and relevant libraries need to be instrumented. -This page will cover the basics for elements that previous versions of Steeltoe configured automatically. -Please refer to the [OpenTelemetry documentation](https://opentelemetry.io/docs/languages/net/instrumentation/) for more detailed information. +For the Prometheus endpoint to return metrics, the application and relevant libraries must be instrumented. +This topic covers the basics for elements that previous versions of Steeltoe configured automatically. +Refer to the [OpenTelemetry documentation](https://opentelemetry.io/docs/languages/net/instrumentation/) for more detailed information. ### ASP.NET Core -To instrument ASP.NET Core for metrics, start by adding a reference to the `OpenTelemetry.Instrumentation.AspNetCore` NuGet package. +To instrument ASP.NET Core for metrics: -Next, add the instrumentation to the `MeterProviderBuilder`: +1. Add a reference to the `OpenTelemetry.Instrumentation.AspNetCore` NuGet package. -```csharp -using OpenTelemetry.Metrics; +1. Add the instrumentation to the `MeterProviderBuilder`: -builder.Services.AddOpenTelemetry().WithMetrics(metrics => metrics.AddAspNetCoreInstrumentation()); -``` + ```csharp + using OpenTelemetry.Metrics; + + builder.Services.AddOpenTelemetry().WithMetrics(metrics => metrics.AddAspNetCoreInstrumentation()); + ``` -[Learn more about ASP.NET Core instrumentation for OpenTelemetry](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/main/src/OpenTelemetry.Instrumentation.AspNetCore) +For more information about ASP.NET Core instrumentation for OpenTelemetry, see the [OpenTelemetry documentation](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/main/src/OpenTelemetry.Instrumentation.AspNetCore). ### HttpClient -To instrument `HttpClient`s for metrics, start by adding a reference to the `OpenTelemetry.Instrumentation.Http` NuGet package. +To instrument `HttpClient`s for metrics: -Next, add the instrumentation to the `MeterProviderBuilder`: +1. Add a reference to the `OpenTelemetry.Instrumentation.Http` NuGet package. -```csharp -using OpenTelemetry.Metrics; +1. Add the instrumentation to the `MeterProviderBuilder`: -builder.Services.AddOpenTelemetry().WithMetrics(metrics => metrics.AddHttpClientInstrumentation()); -``` + ```csharp + using OpenTelemetry.Metrics; -[Learn more about HttpClient instrumentation for OpenTelemetry](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.Http) + builder.Services.AddOpenTelemetry().WithMetrics(metrics => metrics.AddHttpClientInstrumentation()); + ``` -### .NET Runtime +For more information about HttpClient instrumentation for OpenTelemetry, see the [OpenTelemetry documentation](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.Http). -To instrument the .NET Runtime for metrics, start by adding a reference to the `OpenTelemetry.Instrumentation.Runtime` NuGet package. +### .NET runtime -Next, add the instrumentation to the `MeterProviderBuilder`: +To instrument the .NET runtime for metrics: -```csharp -using OpenTelemetry.Metrics; +1. Add a reference to the `OpenTelemetry.Instrumentation.Runtime` NuGet package. -builder.Services.AddOpenTelemetry().WithMetrics(metrics => metrics.AddRuntimeInstrumentation()); -``` +1. Add the instrumentation to the `MeterProviderBuilder`: + + ```csharp + using OpenTelemetry.Metrics; -[Learn more about Runtime Instrumentation for OpenTelemetry .NET](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.Runtime) + builder.Services.AddOpenTelemetry().WithMetrics(metrics => metrics.AddRuntimeInstrumentation()); + ``` + +For more information about Runtime Instrumentation for OpenTelemetry .NET, see the [OpenTelemetry documentation](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.Runtime). ### Prometheus Server @@ -138,10 +144,10 @@ To emit custom metrics in Cloud Foundry, use [Metric Registrar](https://techdocs > [!CAUTION] > Authenticated endpoints are not supported with Metric Registrar. -> For this scenario, configure actuators to [use an alternate port](./using-endpoints.md#configure-global-settings) and use that private network port to offer the metrics. +> For this scenario, configure actuators to use an [alternate port](./using-endpoints.md#configure-global-settings) and use that private network port to offer the metrics. -The examples below expect that actuators are mapped to an alternate port (8091 in this case). -The specific port that is used is not important to Steeltoe, it only matters that the binding and Steeltoe configurations match. +The following examples assume that actuators are mapped to an alternate port (8091 in this case). +The specific port is not important to Steeltoe, it only matters that the binding and Steeltoe configurations match. #### Metrics Registrar Plugin @@ -152,7 +158,7 @@ cf install-plugin -r CF-Community "metric-registrar" cf register-metrics-endpoint APP-NAME /actuator/prometheus --internal-port 8091 ``` -> [!CAUTION] +> [!IMPORTANT] > Due to an issue with the Cloud Foundry CLI plugin interface, some variations on this command do not work on Windows. > If you are a Windows user, you should either use the metric registrar plugin from WSL or use another method. @@ -169,13 +175,13 @@ cf bind-service APP-NAME SERVICE-NAME This endpoint returns information about the instrumented application metrics and their values. -If no instrumentation has been included, the response will be very short, like this: +If no instrumentation has been included, the response is very short: ```text # EOF ``` -With the addition of [.NET Runtime instrumentation](#net-runtime), the response will be like this: +With the addition of [.NET runtime instrumentation](#net-runtime), the response is similar to the following: ```text # TYPE process_runtime_dotnet_gc_collections_count_total counter diff --git a/api/v4/management/refresh.md b/api/v4/management/refresh.md index d604ec76..bff815d7 100644 --- a/api/v4/management/refresh.md +++ b/api/v4/management/refresh.md @@ -9,24 +9,24 @@ The following table describes the configuration settings that you can apply to t Each key must be prefixed with `Management:Endpoints:Refresh:`. | Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether the endpoint is enabled. | `true` | -| `ID` | The unique ID of the endpoint. | `refresh` | -| `Path` | The relative path at which the endpoint is exposed. | same as `ID` | -| `RequiredPermissions` | Permissions required to access the endpoint, when running on Cloud Foundry. | `Restricted` | -| `AllowedVerbs` | An array of HTTP verbs the endpoint is exposed at. | `POST` | -| `ReturnConfiguration` | Whether to return the configuration after refresh. | `true` | - -> [!NOTE] -> Despite being *possible* to configure this endpoint to respond to `GET` requests, +| --- | ----------- | ------- | +| `Enabled` | Whether the endpoint is enabled | `true` | +| `ID` | The unique ID of the endpoint | `refresh` | +| `Path` | The relative path at which the endpoint is exposed | same as `ID` | +| `RequiredPermissions` | Permissions required to access the endpoint when running on Cloud Foundry | `Restricted` | +| `AllowedVerbs` | An array of HTTP verbs at which the endpoint is exposed | `POST` | +| `ReturnConfiguration` | Whether to return the configuration after refresh | `true` | + +> [!CAUTION] +> Despite it being *possible* to configure this endpoint to respond to `GET` requests, > this is discouraged because it is not a [Safe HTTP Method](https://developer.mozilla.org/en-US/docs/Glossary/Safe/HTTP). ## Enable HTTP Access -The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. +The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting with the `Path` setting described in the preceding section. The default path is `/actuator/refresh`. -See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. +See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. To add the actuator to the service container and map its route, use the `AddRefreshActuator` extension method. @@ -40,14 +40,14 @@ builder.Services.AddRefreshActuator(); ``` > [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators; +> this enables individually turning them on/off at runtime via configuration. ## Sample Output This endpoint returns an array of keys obtained from `IConfiguration`. -The response will always be returned as JSON, like this: +The response is always returned as JSON: ```json [ diff --git a/api/v4/management/services.md b/api/v4/management/services.md index 6807f661..0331e86c 100644 --- a/api/v4/management/services.md +++ b/api/v4/management/services.md @@ -8,22 +8,22 @@ The following table describes the configuration settings that you can apply to t Each key must be prefixed with `Management:Endpoints:Services:`. | Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether the endpoint is enabled. | `true` | -| `ID` | The unique ID of the endpoint. | `beans` | -| `Path` | The relative path at which the endpoint is exposed. | same as `ID` | -| `RequiredPermissions` | Permissions required to access the endpoint, when running on Cloud Foundry. | `Restricted` | -| `AllowedVerbs` | An array of HTTP verbs the endpoint is exposed at. | `GET` | +| --- | ----------- | ------- | +| `Enabled` | Whether the endpoint is enabled | `true` | +| `ID` | The unique ID of the endpoint | `beans` | +| `Path` | The relative path at which the endpoint is exposed | same as `ID` | +| `RequiredPermissions` | Permissions required to access the endpoint when running on Cloud Foundry | `Restricted` | +| `AllowedVerbs` | An array of HTTP verbs at which the endpoint is exposed | `GET` | > [!NOTE] > The `ID` of this endpoint defaults to `beans` for compatibility with the [beans actuator from Spring](https://docs.spring.io/spring-boot/api/rest/actuator/beans.html). ## Enable HTTP Access -The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. +The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting with the `Path` setting described in the preceding section. The default path is `/actuator/beans`. -See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. +See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. To add the actuator to the service container and map its route, use the `AddServicesActuator` extension method. @@ -37,14 +37,14 @@ builder.Services.AddServicesActuator(); ``` > [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators; +> this enables individually turning them on/off at runtime via configuration. ## Sample Output This endpoint returns the contents of `IServiceCollection`. -The response will always be returned as JSON, like this: +The response is always returned as JSON: ```json { diff --git a/api/v4/management/springbootadmin.md b/api/v4/management/springbootadmin.md index 9673347d..4d0c61f3 100644 --- a/api/v4/management/springbootadmin.md +++ b/api/v4/management/springbootadmin.md @@ -22,14 +22,14 @@ builder.Services.AddSpringBootAdminClient(); The following table describes the configuration settings that you can apply to the client. Each key must be prefixed with `Spring:Boot:Admin:Client:`. -| Key | Description | Default | -| --- | --- | --- | -| `Url` | The URL of the Spring Boot Admin server. | | -| `ApplicationName` | The name of the Steeltoe app being registered. | computed | -| `BasePath` | Base path to find endpoints for integration. | computed | -| `ValidateCertificates` | Whether server certificates should be validated. | `true` | -| `ConnectionTimeoutMS` | Connection timeout (in milliseconds). | `100_000` | -| `Metadata` | Dictionary of metadata to use when registering. | | +| Key | Description | Default | +| ----- | ----------- | ------- | +| `Url` | The URL of the Spring Boot Admin server | | +| `ApplicationName` | The name of the Steeltoe app being registered | computed | +| `BasePath` | The base URL to find endpoints for integration | computed | +| `ValidateCertificates` | Whether server certificates should be validated | `true` | +| `ConnectionTimeoutMS` | Connection timeout (in milliseconds) | `100_000` | +| `Metadata` | Dictionary of metadata to use when registering | | ## Connecting to dockerized Spring Boot Admin Server @@ -38,100 +38,102 @@ a few additional steps are needed: - Register your app using `host.docker.internal` - Once your app has registered itself with Spring Boot Admin Server, the server tries to connect to your app + After your app has registered itself with Spring Boot Admin Server, the server tries to connect to your app and send requests to its actuator endpoints. This fails when your app registers itself using `localhost`, because the server runs in a docker container that has its own network. - Instead, you need to register using the special `host.docker.internal` address, which enables the server inside the container + Instead, you must register using the special `host.docker.internal` address, which enables the server inside the container to connect to your app outside the container. - Bind your app to a wildcard address By default, your app listens only on `localhost`, which is not accessible from the Spring Boot Admin Server running in a container. To make the app accessible, bind it to a wildcard address, which allows it to listen on all available network interfaces. - This can be done by updating the `launchSettings.json` file. + To do this, update the `launchSettings.json` file. - Use HTTP instead of HTTPS - The server doesn't trust the self-signed certificate used by your app, so you need to use HTTP instead of HTTPS. + The server doesn't trust the self-signed certificate used by your app, so you must use HTTP instead of HTTPS. This requires removing `app.UseHttpsRedirection()` from your `Program.cs` file. - Register additional actuator endpoints - For the server to report the app as "UP", you need to add at least the hypermedia and health actuators in `Program.cs`. + For the server to report the app as `UP`, you must add at least the hypermedia and health actuators in `Program.cs`. > [!TIP] -> You can use the [Steeltoe docker image for SBA](https://github.com/SteeltoeOSS/Samples/blob/main/CommonTasks.md#spring-boot-admin) for testing purposes. - -Putting it all together, your `appsettings.Development.json` file should look like this: - -```json -{ - "Spring": { - "Application": { - "Name": "ExampleSteeltoeApp" - }, - "Boot": { - "Admin": { - "Client": { - // This is the URL of the Spring Boot Admin Server. - "Url": "http://localhost:9099", - // This is what the Spring Boot Admin Server uses to connect to your app. - "BasePath": "http://host.docker.internal:5258" +> For testing, you can use the [Steeltoe docker image for SBA](https://github.com/SteeltoeOSS/Samples/blob/main/CommonTasks.md#spring-boot-admin). + +Putting it all together, your config files contain the contents shown in the following: + +- In `appsettings.Development.json`: + + ```json + { + "Spring": { + "Application": { + "Name": "ExampleSteeltoeApp" + }, + "Boot": { + "Admin": { + "Client": { + // This is the URL of the Spring Boot Admin Server. + "Url": "http://localhost:9099", + // This is what the Spring Boot Admin Server uses to connect to your app. + "BasePath": "http://host.docker.internal:5258" + } + } } } } - } -} -``` - -With the following contents in `launchsettings.json`: - -```json -{ - "$schema": "http://json.schemastore.org/launchsettings.json", - "profiles": { - "http": { - "commandName": "Project", - "dotnetRunMessages": true, - // Listen on all network interfaces by using a wildcard for the hostname. - "applicationUrl": "http://*:5258", - "environmentVariables": { - "ASPNETCORE_ENVIRONMENT": "Development" + ``` + +- In `launchsettings.json`: + + ```json + { + "$schema": "http://json.schemastore.org/launchsettings.json", + "profiles": { + "http": { + "commandName": "Project", + "dotnetRunMessages": true, + // Listen on all network interfaces by using a wildcard for the hostname. + "applicationUrl": "http://*:5258", + "environmentVariables": { + "ASPNETCORE_ENVIRONMENT": "Development" + } + } } } - } -} -``` + ``` -> [!NOTE] -> If you'd like your app to listen on a different port number, replace `5258` in both files above with the desired port. + > [!NOTE] + > If you want your app to listen on a different port number, replace `5258` in both files above with the desired port. -And the following code in `Program.cs`: +- In `Program.cs`: -```csharp -using Steeltoe.Management.Endpoint.Actuators.Health; -using Steeltoe.Management.Endpoint.Actuators.Hypermedia; -using Steeltoe.Management.Endpoint.SpringBootAdminClient; + ```csharp + using Steeltoe.Management.Endpoint.Actuators.Health; + using Steeltoe.Management.Endpoint.Actuators.Hypermedia; + using Steeltoe.Management.Endpoint.SpringBootAdminClient; -var builder = WebApplication.CreateBuilder(args); + var builder = WebApplication.CreateBuilder(args); -// Add services to the container. + // Add services to the container. -builder.Services.AddSpringBootAdminClient(); -builder.Services.AddHypermediaActuator(); -builder.Services.AddHealthActuator(); + builder.Services.AddSpringBootAdminClient(); + builder.Services.AddHypermediaActuator(); + builder.Services.AddHealthActuator(); -builder.Services.AddControllers(); + builder.Services.AddControllers(); -var app = builder.Build(); + var app = builder.Build(); -// In order to avoid trust issues with self-signed certificates, do not automatically redirect to https. -//app.UseHttpsRedirection(); + // To avoid trust issues with self-signed certificates, do not automatically redirect to https. + //app.UseHttpsRedirection(); -app.MapControllers(); + app.MapControllers(); -app.Run(); -``` + app.Run(); + ``` > [!TIP] -> To see all the Spring Boot Admin features in action, replace the `Add*Actuator()` calls in `Program.cs` with `AddAllActuators()` and [expose all endpoints](./using-endpoints.md#exposing-endpoints). +> To see all the Spring Boot Admin features in action, replace the `Add*Actuator()` calls in `Program.cs` with `AddAllActuators()` and expose all endpoints. See [Exposing endpoints](./using-endpoints.md#exposing-endpoints). diff --git a/api/v4/management/tasks.md b/api/v4/management/tasks.md index 080088e4..c666dd5a 100644 --- a/api/v4/management/tasks.md +++ b/api/v4/management/tasks.md @@ -58,7 +58,7 @@ builder.Services.AddTask("ExampleTaskName"); > [!NOTE] > To register as a singleton or transient service, use the overload that additionally takes a `ServiceLifetime` parameter. -In case task instantiation requires additional logic, a task instance can be specified as well: +If task instantiation requires additional logic, a task instance can be specified as well: ```csharp using Steeltoe.Management.Tasks; @@ -85,7 +85,7 @@ builder.Services.AddTask("ExampleTaskName", (serviceProvider, taskName) => ## Executing a Task -Once your task has been defined and added to the service container, the last step is to enable a means of executing the task. +After your task has been defined and added to the service container, the last step is to enable a means of executing the task. In your `Program.cs` file, replace the call to `app.Run()` with `await app.RunWithTasksAsync()`: ```csharp @@ -100,18 +100,18 @@ await app.RunWithTasksAsync(CancellationToken.None); ## Specify Task to Execute -Once all the setup steps have been completed, any invocation of your application with a configuration value for the `RunTask` key +After all the setup steps have been completed, any invocation of your application with a configuration value for the `RunTask` key runs that task (and shuts down) instead of starting the web application: ``` dotnet run -- RunTask=ExampleTaskName ``` -As a matter of best practice, we encourage you to provide the `RunTask` value only via a command-line parameter. -However, due to the way .NET configuration works, it does not matter which configuration provider is used to provide the task name. +As a matter of best practice, it is recommended that you provide the `RunTask` value only using a command-line parameter. +However, due to the way .NET configuration works, it doesn't matter which configuration provider is used to provide the task name. Invoking the command on Cloud Foundry looks similar to this: -``` +```shell cf run-task YourAppName "dotnet run -- RunTask=ExampleTaskName" --name ExampleTaskName ``` diff --git a/api/v4/management/threaddump.md b/api/v4/management/threaddump.md index 742ff093..201e3965 100644 --- a/api/v4/management/threaddump.md +++ b/api/v4/management/threaddump.md @@ -1,6 +1,6 @@ # Thread Dump -The Steeltoe Thread Dump endpoint can be used to generate a snapshot of information about all the threads in your application. That snapshot includes several bits of information for each thread, including the thread's state, a stack trace, any monitor locks held by the thread, any monitor locks the thread is waiting on, and other details. +The Steeltoe Thread Dump endpoint can be used to generate a snapshot of information about all the threads in your application. That snapshot includes several bits of information for each thread, including the thread state, a stack trace, any monitor locks held by the thread, any monitor locks the thread is waiting for, and other details. ## Configure Settings @@ -8,22 +8,22 @@ The following table describes the configuration settings that you can apply to t Each key must be prefixed with `Management:Endpoints:ThreadDump:`. | Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether the endpoint is enabled. | `true` | -| `ID` | The unique ID of the endpoint. | `threaddump` | -| `Path` | The relative path at which the endpoint is exposed. | same as `ID` | -| `RequiredPermissions` | Permissions required to access the endpoint, when running on Cloud Foundry. | `Restricted` | -| `AllowedVerbs` | An array of HTTP verbs the endpoint is exposed at. | `GET` | +| --- | ----------- | ------- | +| `Enabled` | Whether the endpoint is enabled | `true` | +| `ID` | The unique ID of the endpoint | `threaddump` | +| `Path` | The relative path at which the endpoint is exposed | same as `ID` | +| `RequiredPermissions` | Permissions required to access the endpoint when running on Cloud Foundry | `Restricted` | +| `AllowedVerbs` | An array of HTTP verbs at which the endpoint is exposed | `GET` | -> [!TIP] -> In version 4, the configuration key prefix for this endpoint changed from `Management:Endpoints:Dump:` to `Management:Endpoints:ThreadDump:` +> [!IMPORTANT] +> In version 4, the configuration key prefix for this endpoint changed from `Management:Endpoints:Dump:` to `Management:Endpoints:ThreadDump:`. ## Enable HTTP Access -The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting together with the `Path` setting described in the preceding section. +The URL path to the endpoint is computed by combining the global `Management:Endpoints:Path` setting with the `Path` setting described in the preceding section. The default path is `/actuator/threaddump`. -See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application. +See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the steps required to enable HTTP access to endpoints in an ASP.NET Core application. To add the actuator to the service container and map its route, use the `AddThreadDumpActuator` extension method. @@ -37,14 +37,14 @@ builder.Services.AddThreadDumpActuator(); ``` > [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators; +> this enables individually turning them on/off at runtime via configuration. ## Sample Output This endpoint returns a list of threads with their state and stack trace. -The response will always be returned as JSON, like this: +The response is always returned as JSON: ```json { diff --git a/api/v4/management/using-endpoints.md b/api/v4/management/using-endpoints.md index 91ff220b..0f17f9ff 100644 --- a/api/v4/management/using-endpoints.md +++ b/api/v4/management/using-endpoints.md @@ -6,35 +6,35 @@ Steeltoe provides a basic set of HTTP endpoints (also known as actuators), which In this section, it is helpful to understand the following: -* How the [.NET Configuration System](https://learn.microsoft.com/aspnet/core/fundamentals/configuration) works. -* How the [ASP.NET Core Startup](https://learn.microsoft.com/aspnet/core/fundamentals/startup) is used to register services and middleware. +* How the [.NET Configuration System](https://learn.microsoft.com/aspnet/core/fundamentals/configuration) works +* How the [ASP.NET Core Startup](https://learn.microsoft.com/aspnet/core/fundamentals/startup) is used to register services and middleware ## Endpoint Listing The following table describes the available Steeltoe management endpoints that can be used in an application: -| ID|Description | -| --- | --- | -| [cloudfoundry](./cloud-foundry.md) | Enables the management endpoint integration with Cloud Foundry. | -| [dbmigrations](./dbmigrations.md) | Provides the ability to see current and pending database migrations for an application data source. | -| [env](./env.md) | Reports the keys and values from the application's configuration. | -| [health](./health.md) | Customizable endpoint that gathers application health information. | -| [heapdump](./heapdump.md) | Generates and downloads a mini-dump of the application (Windows and Linux only). | -| [httpexchanges](./httpexchanges.md) | Gathers recently processed HTTP requests. | -| [hypermedia](./hypermedia.md) | Lists the active management endpoints and their links. | -| [info](./info.md) | Customizable endpoint that gathers arbitrary application information (such as app version). | -| [loggers](./loggers.md) | Gathers existing logger categories and allows changing their minimum levels at runtime. | -| [mappings](./mappings.md) | Reports the configured ASP.NET routes and route templates. | -| [prometheus](./prometheus.md) | Exposes metrics collected via built-in instrumentation of various aspects of the application in the Prometheus format. | -| [refresh](./refresh.md) | Triggers a reload of the application configuration. | -| [services](./services.md) | Lists the contents of the .NET dependency injection service container. | -| [threaddump](./threaddump.md) | Generates and reports a snapshot of the application's threads (Windows only). | +| ID |Description | +| --- | ---------- | +| [cloudfoundry](./cloud-foundry.md) | Enables the management endpoint integration with Cloud Foundry | +| [dbmigrations](./dbmigrations.md) | Provides the ability to see current and pending database migrations for an application data source | +| [env](./env.md) | Reports the keys and values from the application configuration | +| [health](./health.md) | Customizable endpoint that gathers application health information | +| [heapdump](./heapdump.md) | Generates and downloads a mini-dump of the application (Windows and Linux only) | +| [httpexchanges](./httpexchanges.md) | Gathers recently processed HTTP requests | +| [hypermedia](./hypermedia.md) | Lists the active management endpoints and their links | +| [info](./info.md) | Customizable endpoint that gathers arbitrary application information (such as app version) | +| [loggers](./loggers.md) | Gathers existing logger categories and allows changing their minimum levels at runtime | +| [mappings](./mappings.md) | Reports the configured ASP.NET routes and route templates | +| [prometheus](./prometheus.md) | Exposes metrics collected using built-in instrumentation of various aspects of the application in the Prometheus format | +| [refresh](./refresh.md) | Triggers a reload of the application configuration | +| [services](./services.md) | Lists the contents of the .NET dependency injection service container | +| [threaddump](./threaddump.md) | Generates and reports a snapshot of the application's threads (Windows only) | Each endpoint has an associated ID. When you want to expose an endpoint over HTTP, its ID is used in the mapped URL that exposes the endpoint. For example, the `health` endpoint is mapped to `/actuator/health`. ## Add NuGet Reference -To use the management endpoints, you need to add a reference to the `Steeltoe.Management.Endpoints` NuGet package. +To use the management endpoints, add a reference to the `Steeltoe.Management.Endpoints` NuGet package. ## Configure Global Settings @@ -47,37 +47,37 @@ Settings that you want to apply to specific endpoints should be placed under the The following table describes the configuration settings that you can apply globally: | Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether to enable management endpoints. | `true` | -| `Path` | The HTTP route prefix applied to all endpoints. | `/actuator` | -| `Port` | Expose management endpoints on an alternate HTTP port. [^1] | | -| `SslEnabled` | Whether `Port` applies to HTTP or HTTPS requests. [^1] | `false` | -| `UseStatusCodeFromResponse` | Reflect the actuator outcome in the HTTP response status code. | `true` | -| `SerializerOptions` | Customize JSON serialization options. | use camelCase properties | -| `CustomJsonConverters` | Additional [`JsonConverter`](https://learn.microsoft.com/dotnet/standard/serialization/system-text-json/converters-how-to)s to use (see below). | | +| --- | ----------- | ------- | +| `Enabled` | Whether to enable management endpoints | `true` | +| `Path` | The HTTP route prefix applied to all endpoints | `/actuator` | +| `Port` | Expose management endpoints on an alternate HTTP port [^1] | | +| `SslEnabled` | Whether `Port` applies to HTTP or HTTPS requests [^1] | `false` | +| `UseStatusCodeFromResponse` | Reflect the actuator outcome in the HTTP response status code | `true` | +| `SerializerOptions` | Customize JSON serialization options | use camelCase properties | +| `CustomJsonConverters` | Additional [`JsonConverter`](https://learn.microsoft.com/dotnet/standard/serialization/system-text-json/converters-how-to)s to use (see below) | | [^1]: Using an alternate port does not apply to `/cloudfoundryapplication` endpoints. > [!NOTE] -> When running an application in IIS or with the HWC buildpack, response body content is automatically filtered out when the HTTP response code is 503. Some actuator responses intentionally return a code of 503 in failure scenarios. Setting `UseStatusCodeFromResponse` to `false` will return status code 200 instead. This switch does not affect the status code of responses outside of Steeltoe. +> When running an application in IIS or with the HWC buildpack, response body content is automatically filtered out when the HTTP response code is 503. Some actuator responses intentionally return a code of 503 in failure scenarios. Setting `UseStatusCodeFromResponse` to `false` returns status code 200 instead. This switch does not affect the status code of responses outside of Steeltoe. ## Configure Endpoint-specific Settings The following table describes the configuration settings that are common to all endpoint-specific settings: | Key | Description | Default | -| --- | --- | --- | -| `Enabled` | Whether the endpoint is enabled. | `true` | -| `ID` | The unique ID of the endpoint. | | -| `Path` | The relative path at which the endpoint is exposed. | same as `ID` | -| `RequiredPermissions` | Permissions required to access the endpoint, when running on Cloud Foundry. | `Restricted` | -| `AllowedVerbs` | An array of HTTP verbs the endpoint is exposed at. | | +| --- | ----------- | ------- | +| `Enabled` | Whether the endpoint is enabled | `true` | +| `ID` | The unique ID of the endpoint | | +| `Path` | The relative path at which the endpoint is exposed | same as `ID` | +| `RequiredPermissions` | Permissions required to access the endpoint when running on Cloud Foundry | `Restricted` | +| `AllowedVerbs` | An array of HTTP verbs at which the endpoint is exposed | | ### Custom JSON Serialization Options -The `JsonSerializerOptions` used to serialize actuator responses are configurable, and custom `JsonConverter`s can be used by adding the [assembly-qualified type](https://learn.microsoft.com/dotnet/api/system.type.assemblyqualifiedname"). +The `JsonSerializerOptions` used to serialize actuator responses are configurable, and custom `JsonConverter`s can be used by adding the [assembly-qualified type](https://learn.microsoft.com/dotnet/api/system.type.assemblyqualifiedname). -For example, to pretty-print all JSON and serialize `DateTime` values as epoch times: +For example, to pretty-print all JSON, and serialize `DateTime` values as epoch times: ```json { @@ -99,12 +99,12 @@ For example, to pretty-print all JSON and serialize `DateTime` values as epoch t Since endpoints may contain sensitive information, only health and info are exposed by default. To change which endpoints are exposed, use the `Include` and `Exclude` properties. | Property | Default | -| --- | --- | +| -------- | ------- | | `Exposure:Include` | [`info`, `health`] | | `Exposure:Exclude` | | -Each key in the table above must be prefixed with `Management:Endpoints:Actuator`. Use the actuator ID to specify the endpoint. -To expose all endpoints, `*` can be used. For example, to expose everything except `env` and `refresh`, use the following: +Each key in the table must be prefixed with `Management:Endpoints:Actuator`. Use the actuator ID to specify the endpoint. +To expose all endpoints, you can use `*`. For example, to expose everything except `env` and `refresh`, use the following: ```json "Management": { @@ -119,8 +119,8 @@ To expose all endpoints, `*` can be used. For example, to expose everything exce } ``` -> [!NOTE] -> When running on Cloud Foundry, exposure settings *only* have an effect on requests starting with `/actuator`. +> [!IMPORTANT] +> When running on Cloud Foundry, exposure settings affect *only* requests starting with `/actuator`. > They are ignored for requests starting with `/cloudfoundryapplication`, where access control is [handled differently](./cloud-foundry.md#security). > Individual endpoints can be turned off by setting `Enabled` to `false`, which applies to both URLs. @@ -133,14 +133,15 @@ To expose any of the management endpoints over HTTP in an ASP.NET Core applicati 1. Add the actuator endpoint(s) to the service container. 1. Optional: Add any additional health/info contributors to the service container. 1. Optional: Customize the CORS policy. -1. Optional: Secure endpoints. +1. Optional: Secure the endpoints. 1. Optional: Override the middleware pipeline setup. > [!CAUTION] -> By default, actuator endpoints are exposed on the same host(s) and port(s) as the application (which can be configured as described [here](https://learn.microsoft.com/aspnet/core/fundamentals/servers/kestrel/endpoints) and [here](https://andrewlock.net/8-ways-to-set-the-urls-for-an-aspnetcore-app/)). -> Use the `Port` and `SslEnabled` settings described above to isolate management endpoints from regular application endpoints. +> By default, actuator endpoints are exposed on the same host(s) and port(s) as the application (which can be configured as described in the [ASP.NET documentation](https://learn.microsoft.com/aspnet/core/fundamentals/servers/kestrel/endpoints) and in +> [8 ways to set the URLs for an ASP.NET Core app](https://andrewlock.net/8-ways-to-set-the-urls-for-an-aspnetcore-app/)). +> Use the `Port` and `SslEnabled` settings described earlier to isolate management endpoints from regular application endpoints. -The example below adds all actuators: +The following example adds all actuators: ```csharp using Steeltoe.Management.Endpoint.Actuators.All; @@ -150,8 +151,8 @@ builder.Services.AddAllActuators(); ``` > [!TIP] -> It's recommended to use `AddAllActuators()` instead of adding individual actuators, -> which enables individually turning them on/off at runtime via configuration. +> It is recommended that you use `AddAllActuators()` instead of adding individual actuators; +> this enables individually turning them on/off at runtime using configuration. Alternatively, individual actuators can be added: @@ -165,7 +166,7 @@ builder.Services.AddHypermediaActuator().AddLoggersActuator().AddRefreshActuator ``` > [!NOTE] -> `AddAllActuators()` and `AddLoggingActuator()` automatically configure [Dynamic Console Logging](../logging/dynamic-console-logging.md). To use [Dynamic Serilog Logging](../logging/dynamic-serilog-logging.md), be sure to do so *before* adding actuators. For example: +> `AddAllActuators()` and `AddLoggingActuator()` automatically configure [Dynamic Console Logging](../logging/dynamic-console-logging.md). If you want to use [Dynamic Serilog Logging](../logging/dynamic-serilog-logging.md) instead, add it *before* adding actuators. For example: > > ```csharp > using Steeltoe.Logging.DynamicSerilog; @@ -176,7 +177,7 @@ builder.Services.AddHypermediaActuator().AddLoggersActuator().AddRefreshActuator > builder.Services.AddAllActuators(); > ``` -## Adding additional contributors +## Adding contributors The `health` and `info` endpoints can be extended with custom contributors. For example: @@ -221,7 +222,7 @@ When `RequireAuthorization()` is called without arguments, the default profile i ## Overriding the middleware pipeline setup -All `Add*Actuator` methods provide an overload that takes a boolean `configureMiddleware`, which enables to skip adding middleware to the ASP.NET Core pipeline. +All `Add*Actuator` methods provide an overload that takes a boolean `configureMiddleware`, which enables skipping adding middleware to the ASP.NET Core pipeline. While this provides full control over the pipeline contents and order, it requires manual addition of the appropriate middleware for actuators to work correctly. ```csharp @@ -242,7 +243,13 @@ app.UseActuatorEndpoints(); // maps the actuator endpoints await app.StartAsync(); ``` -While the order above must not be changed (and it's not recommended to leave out entries), additional middleware can be inserted as appropriate. +### Rules for use + +Follow these rules when overriding the middleware pipeline setup: + +* Do not change the order shown in the sample. +* Leaving out entries is not recommended. +* Additional middleware can be inserted as appropriate. ### Conventional routing diff --git a/api/v4/security/certificate.md b/api/v4/security/certificate.md index d563d67a..112887a7 100644 --- a/api/v4/security/certificate.md +++ b/api/v4/security/certificate.md @@ -5,31 +5,31 @@ Certificate Authentication, also known as Mutual TLS, is a way for a client and This library is a supplement to [ASP.NET Core Certificate Authentication](https://learn.microsoft.com/aspnet/core/security/authentication/certauth), adding functionality that helps you use [Cloud Foundry Instance Identity certificates](https://docs.cloudfoundry.org/devguide/deploy-apps/instance-identity.html) and authorization policies based on certificate data. Additionally, resources are included for automatically generating certificates for local development that resemble what is found on the platform. -## Usage +## Using Mutual TLS in ASP.NET Core -In order to use this provider, the following steps are required: +To use this provider, the following steps are required: -1. Add NuGet package reference -1. Add identity certificates to the configuration -1. Add and use the security provider in the application -1. Secure your endpoints -1. Attach certificate to requests to secured endpoints +1. Add NuGet package reference. +1. Add identity certificates to the configuration. +1. Add and use the security provider in the application. +1. Secure your endpoints. +1. Attach certificate to requests to secured endpoints. ### Add NuGet Reference > [!NOTE] -> This step is required on all applications that are sending or receiving certificate-authorized requests. +> This step is required for all applications that are sending or receiving certificate-authorized requests. -To use Certificate Authorization, you need to add a reference to the `Steeltoe.Security.Authorization.Certificate` NuGet package. +To use Certificate Authorization, add a reference to the `Steeltoe.Security.Authorization.Certificate` NuGet package. ### Add Identity Certificates to Configuration > [!NOTE] -> This step is required on all applications that are sending or receiving certificate-authorized requests. +> This step is required for all applications that are sending or receiving certificate-authorized requests. In a Cloud Foundry environment, instance identity certificates are automatically provisioned (and rotated on a regular basis) for each application instance. Steeltoe provides the extension method `AddAppInstanceIdentityCertificate` to find the location of the certificate files from the environment variables `CF_INSTANCE_CERT` and `CF_INSTANCE_KEY`. -When running outside of Cloud Foundry, this method will automatically generate similar certificates. +When running outside of Cloud Foundry, this method automatically generates similar certificates. Use the optional parameters to coordinate `orgId` and/or `spaceId` between your applications to facilitate communication when running outside of Cloud Foundry. This code adds the certificate paths to the configuration for use later (and generates the instance identity certificate when running outside Cloud Foundry): @@ -44,25 +44,25 @@ var builder = WebApplication.CreateBuilder(args); builder.Configuration.AddAppInstanceIdentityCertificate(new Guid(orgId), new Guid(spaceId)); ``` -When running locally, the code shown above will create a chain of self-signed certificates and the application instance identity certificate will have a subject containing an OrgId of `a8fef16f-94c0-49e3-aa0b-ced7c3da6229` and a SpaceId of `122b942a-d7b9-4839-b26e-836654b9785f`. +When running locally, the preceding code sample creates a chain of self-signed certificates. The application instance identity certificate is created with a subject containing an OrgId of `a8fef16f-94c0-49e3-aa0b-ced7c3da6229` and a SpaceId of `122b942a-d7b9-4839-b26e-836654b9785f`. A root certificate and intermediate certificate are created on disk one level above the current project in a directory named `GeneratedCertificates`. -The root and intermediate certificates will automatically be shared between applications housed within the same solution, so that the applications will be able to trust each other. +The root and intermediate certificates are automatically shared between applications housed within the same solution, so that the applications can trust each other. ### Add and use Certificate Authentication > [!NOTE] -> This section is only required on applications that are receiving certificate-authorized requests. +> This section is required only for applications that are receiving certificate-authorized requests. Several steps need to happen before certificate authorization policies can be used to secure resources: -1. Configuration values need to be bound into named `CertificateOptions` -1. Certificate files need to be monitored for changes (to stay up to date when certificates are rotated) -1. Certificate forwarding needs to be configured (so that ASP.NET reads the certificate out of an HTTP Header) -1. Authentication services need to be added -1. Authorization services and policies need to be added -1. Middleware needs to be activated +1. Bind configuration values into named `CertificateOptions`. +1. Monitor certificate files for changes (to stay up to date when certificates are rotated). +1. Configure certificate forwarding (so that ASP.NET reads the certificate from an HTTP Header). +1. Add authentication services. +1. Add authorization services and policies. +1. Activate middleware. -Fortunately, all of the requirements can be satisfied with a handful of extension methods: +Fortunately, all of these requirements can be satisfied with a handful of extension methods: ```csharp using Steeltoe.Security.Authorization.Certificate; @@ -108,12 +108,12 @@ app.UseCertificateAuthorization(); ### Securing Endpoints > [!NOTE] -> This step is only required on applications that are receiving certificate-authorized requests. +> This step is required only for applications that are receiving certificate-authorized requests. -As implied by the name of the extension method `AddOrgAndSpacePolicies` from the previous section on this page, Steeltoe provides policies for validating that a request came from an application in the same org and/or the same space. You can secure endpoints by using the standard ASP.NET Core `Authorize` attribute with these security policies. +As implied by the name of the extension method `AddOrgAndSpacePolicies` (from the previous section in this topic), Steeltoe provides policies for validating that a request came from an application in the same org and/or the same space. You can secure endpoints using the standard ASP.NET Core `Authorize` attribute with these security policies. > [!TIP] -> If needed, see the Microsoft documentation on [authorization in ASP.NET Core](https://learn.microsoft.com/aspnet/core/security/authorization/introduction) for a better understanding of how to use these attributes. +> For more information about authorization in ASP.NET Core, see the [Microsoft documentation](https://learn.microsoft.com/aspnet/core/security/authorization/introduction). The following example shows a controller using the security attributes with the included policies: @@ -153,18 +153,18 @@ In the preceding example, when an incoming request is made to the `SameOrgCheck` ### Communicating with Secured Services -In order to use app instance identity certificates in a client application, services need to be configured, but nothing needs to be activated in the ASP.NET Core request pipeline. +To use app instance identity certificates in a client application, services must be configured, but nothing needs to be activated in the ASP.NET Core request pipeline. #### IHttpClientFactory integration > [!NOTE] -> This step is only required on applications that are sending certificate-authorized requests. +> This step is required only for applications that are sending certificate-authorized requests. -For applications that need to send identity certificates in outgoing requests, Steeltoe provides a smooth experience through an extension method on `IHttpClientBuilder` named `AddAppInstanceIdentityCertificate`. +For applications that need to send identity certificates in outgoing requests, Steeltoe provides a smooth experience through an extension method on `IHttpClientBuilder` called `AddAppInstanceIdentityCertificate`. This method invokes code that handles loading certificates from paths defined in the application's configuration, monitors those file paths and their content for changes, and places the certificate in an HTTP header named `X-Client-Cert` on all outbound requests. > [!TIP] -> If needed, see the Microsoft documentation on [IHttpClientFactory documentation](https://learn.microsoft.com/aspnet/core/fundamentals/http-requests) for details. +> For more information about `IHttpClientFactory`, see the [Microsoft documentation](https://learn.microsoft.com/aspnet/core/fundamentals/http-requests). ```csharp using Steeltoe.Security.Authorization.Certificate; diff --git a/api/v4/security/index.md b/api/v4/security/index.md index 32ba3f60..b83cc89d 100644 --- a/api/v4/security/index.md +++ b/api/v4/security/index.md @@ -10,4 +10,4 @@ Choose from the following options when using Cloud Foundry security integration: In addition to authentication and authorization providers, Steeltoe security offers: -* [A security provider for using Redis on Cloud Foundry with ASP.NET Core Data Protection Key Ring storage](redis-key-storage-provider.md) +* [A security provider for using Redis/Valkey on Cloud Foundry with ASP.NET Core Data Protection Key Ring storage](redis-key-storage-provider.md) diff --git a/api/v4/security/jwt-bearer.md b/api/v4/security/jwt-bearer.md index 228cfd50..16f621b2 100644 --- a/api/v4/security/jwt-bearer.md +++ b/api/v4/security/jwt-bearer.md @@ -2,15 +2,18 @@ This library is a supplement to ASP.NET Core Security, adding functionality that helps you use Cloud Foundry Security services such as [Single Sign-On for VMware Tanzu](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/index.html) or a [UAA Server](https://github.com/cloudfoundry/uaa) for authentication and authorization using JSON Web Tokens (JWT) in ASP.NET Core web applications. -The [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md) can help you understand how to use this tool. +For more information, see also the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md). -General guidance on JWT is beyond the scope of this document and can be found in many other sources (for example, see [Wikipedia](https://en.wikipedia.org/wiki/JSON_Web_Token) or [JWT IO](https://jwt.io/)). +General guidance for use of JWT is beyond the scope of this document. For information, see: -For the documentation of the underlying Microsoft Jwt Bearer Authentication library, visit the [official documentation](https://learn.microsoft.com/aspnet/core/security/authentication/configure-jwt-bearer-authentication). +* [JWT IO](https://jwt.io/) +* [Wikipedia](https://en.wikipedia.org/wiki/JSON_Web_Token) -## Usage +For information about the underlying Microsoft JWT Bearer Authentication library, see the [Microsoft documentation](https://learn.microsoft.com/aspnet/core/security/authentication/configure-jwt-bearer-authentication). -Steps involved in using this library: +## Using JWT in ASP.NET Core + +To use this library: 1. Add NuGet references. 1. Configure settings for the security provider. @@ -20,15 +23,16 @@ Steps involved in using this library: ### Add NuGet References -To use the provider, you need to add a reference to the `Steeltoe.Security.Authentication.JwtBearer` NuGet package. +To use this package, add NuGet package references to: -Also add a reference to `Steeltoe.Configuration.CloudFoundry`, so that Cloud Foundry service bindings can be read by Steeltoe. +* `Steeltoe.Security.Authentication.JwtBearer` +* `Steeltoe.Configuration.CloudFoundry` (so that Cloud Foundry service bindings can be read by Steeltoe) ### Configure Settings -Since Steeltoe's JWT Bearer library configures Microsoft's JWT Bearer implementation, all available settings can be found in [`Microsoft.AspNetCore.Authentication.JwtBearer.JwtBearerOptions`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.authentication.jwtbearer.jwtbeareroptions). +The Steeltoe JWT Bearer library configures the Microsoft JWT Bearer implementation, so all supported settings are available in [`Microsoft.AspNetCore.Authentication.JwtBearer.JwtBearerOptions`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.authentication.jwtbearer.jwtbeareroptions). -`JwtBearerOptions` is bound to configuration values found under `Authentication:Schemes:Bearer`. The following example `appsettings.json` shows how to declare the audience for which tokens should be considered valid (such as when a token is issued to a specific web application and then passed to backend services to perform actions on behalf of a user): +`JwtBearerOptions` is bound to configuration values at the key `Authentication:Schemes:Bearer`. The following example `appsettings.json` shows how to declare the audience for which tokens should be considered valid (such as when a token is issued to a specific web application and then passed to backend services to perform actions on behalf of a user): ```json { @@ -59,7 +63,7 @@ builder.Configuration.AddCloudFoundryServiceBindings(); #### Local UAA -A UAA server (such as [UAA Server for Steeltoe samples](https://github.com/SteeltoeOSS/Dockerfiles/tree/main/uaa-server)), can be used for local development of applications that will be deployed to Cloud Foundry. Configuration of UAA itself is beyond the scope of this documentation, but configuring your `appsettings.Development.json` to work with a local UAA server is possible with the addition of settings like these: +A UAA server, such as [UAA Server for Steeltoe](https://github.com/SteeltoeOSS/Dockerfiles/tree/main/uaa-server), can be used for local development of applications that will be deployed to Cloud Foundry. Configuration of UAA itself is beyond the scope of this topic, but configuring your `appsettings.Development.json` to work with a local UAA server is possible with the addition of settings like these: ```json { @@ -78,12 +82,12 @@ A UAA server (such as [UAA Server for Steeltoe samples](https://github.com/Steel ``` > [!IMPORTANT] -> If you wish to use the Steeltoe UAA server without modification, some application configuration options will be limited. -> The Steeltoe UAA Server configuration can be found in [uaa.yml](https://github.com/SteeltoeOSS/Dockerfiles/blob/main/uaa-server/uaa.yml#L111). +> If you want to use the Steeltoe UAA server without modification, some application configuration options will be limited. +> The Steeltoe UAA Server configuration is available in [uaa.yml](https://github.com/SteeltoeOSS/Dockerfiles/blob/main/uaa-server/uaa.yml#L111). ### Add and use JWT Bearer Authentication -Since the majority of the JWT Bearer functionality is provided by Microsoft's libraries, the only difference when using Steeltoe will be the addition of calling `ConfigureJwtBearerForCloudFoundry` on the `AuthenticationBuilder`, as shown in the following example: +Most of the JWT Bearer functionality is provided by the Microsoft libraries, so the only difference when using Steeltoe is the addition of calling `ConfigureJwtBearerForCloudFoundry` on the `AuthenticationBuilder`, as shown in the following example: ```csharp using Microsoft.AspNetCore.Authentication.JwtBearer; @@ -102,7 +106,8 @@ builder.Services.AddAuthorizationBuilder() .AddPolicy("sampleapi.read", policy => policy.RequireClaim("scope", "sampleapi.read")); ``` -Activate authentication and authorization services _after_ routing services, but _before_ controller route registrations, with the following code: +The middleware pipeline order is important: +Activate authentication and authorization services _after_ routing services, but _before_ controller route registrations, as shown in the following example. ```csharp var app = builder.Build(); @@ -119,12 +124,12 @@ app.MapDefaultControllerRoute(); app.Run(); ``` -> [!TIP] -> In the sample code above, `app.UseForwardedHeaders` is used so that any links generated within the application will be compatible with reverse-proxy scenarios, such as when running in Cloud Foundry. +> [!NOTE] +> In this sample code, `app.UseForwardedHeaders` is used so that any links generated within the application are compatible with reverse-proxy scenarios, such as when running in Cloud Foundry. ### Securing Endpoints -Once the services and middleware have been configured, you can secure endpoints with the standard ASP.NET Core `Authorize` attribute, as follows: +After the services and middleware have been configured, you can secure endpoints with the standard ASP.NET Core `Authorize` attribute, as follows: ```csharp using Microsoft.AspNetCore.Authorization; @@ -146,19 +151,19 @@ public class SampleController : ControllerBase In the preceding example, if an incoming GET request is made to the `/api/sample` endpoint and the request does not contain a valid JWT bearer token for a user with a `scope` claim equal to `sampleapi.read`, the request is rejected. -Review the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md) for a demonstration of using a user's access token to interact with downstream APIs, focusing on these locations: +See the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md) for examples using a user's access token to interact with downstream APIs, focusing on these locations: -- [Configure ASP.NET Core to save the user's token](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/appsettings.json#L15) -- [Get the user's token](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/Controllers/HomeController.cs#L60) -- [Include the token in a downstream request](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/ApiClients/JwtAuthorizationApiClient.cs#L24) +* [Configure ASP.NET Core to save the user's token](https://github.com/SteeltoeOSS/Samples/blob/4c0b222a8ea201240bb6b99aae46434864cf4dd1/Security/src/AuthWeb/appsettings.json#L15) +* [Get the user's token](https://github.com/SteeltoeOSS/Samples/blob/4c0b222a8ea201240bb6b99aae46434864cf4dd1/Security/src/AuthWeb/Controllers/HomeController.cs#L60) +* [Include the token in a downstream request](https://github.com/SteeltoeOSS/Samples/blob/4c0b222a8ea201240bb6b99aae46434864cf4dd1/Security/src/AuthWeb/ApiClients/JwtAuthorizationApiClient.cs#L24) ### Single Sign-On for VMware Tanzu -When using Single Sign-On for VMware Tanzu, you will need to identify the service plan to be used before creating a service instance of that plan. -If you do not have an existing service plan, a platform operator may need to create a new plan for you. -The operator should refer to the [Single Sign-On for Tanzu operator guide](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/operator-index.html) for information on how to configure plans for developer use. +When using Single Sign-On for VMware Tanzu, you must choose a service plan before you create a service instance. +If you do not have an existing service plan, a platform operator might need to create a new plan for you. +For information about configuring service plans for use by developers, a platform operator should follow the steps in the [Single Sign-On for Tanzu operator guide](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/operator-index.html). -Once you have identified the service plan that will be used, create a service instance: +After you have identified the service plan to use, create a service instance: ```shell cf create-service p-identity SERVICE_PLAN_NAME MY_SERVICE_INSTANCE @@ -166,9 +171,10 @@ cf create-service p-identity SERVICE_PLAN_NAME MY_SERVICE_INSTANCE #### Bind and configure with app manifest -Using a manifest file when you deploy to Cloud Foundry is recommended, and can save some work with the SSO configuration. Review the Single Sign-On documentation for [configuring an app manifest](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/config-apps.html#configure-app-manifest). +Using a manifest file when you deploy to Cloud Foundry is recommended, and can save some work with the SSO configuration. +For information about configuring an app manifest, see the [Single Sign-On documentation](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/config-apps.html#configure-app-manifest). -Consider this example manifest that names the application, buildpack and configures several properties for the SSO binding: +Consider this example manifest that names the application and buildpack, and configures properties for the SSO binding: ```yml applications: @@ -186,7 +192,8 @@ applications: #### Bind and configure manually -Alternatively, you can manually bind the instance, restage the app with the Cloud Foundry CLI and later configure the SSO binding yourself with the web interface: +Alternatively, you can bind the instance manually and restage the app with the Cloud Foundry CLI. +Then you can configure the SSO binding with the web interface: ```shell # Bind service to your app @@ -196,24 +203,27 @@ cf bind-service MY_APPLICATION MY_SERVICE_INSTANCE cf restage MY_APPLICATION ``` -For further information, refer to the [Single Sign-On for Tanzu developer guide](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/developer-index.html) or follow the instructions included in the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md). +For more information, see: + +* the [Single Sign-On for Tanzu developer guide](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/developer-index.html) +* the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md) ### UAA Server -If Single Sign-On for Tanzu is not available or desired for your application, you can use UAA as an alternative. +If Single Sign-On for Tanzu is not available or desired for your application, you can use UAA. -There is no service broker available to manage service instances or bindings for UAA, so a [user provided service instance](https://docs.cloudfoundry.org/devguide/services/user-provided.html) must be used to hold the credentials. +There is no service broker available to manage service instances or bindings for UAA, so you must have a [user provided service instance](https://docs.cloudfoundry.org/devguide/services/user-provided.html) to hold the credentials. -The following command is an example of how the binding could be created: +This command is an example of how the service instance can be created: ```shell cf cups MY_SERVICE_INSTANCE -p '{"auth_domain": "https://uaa.login.sys.cf-app.com","grant_types": [ "authorization_code", "client_credentials" ],"client_secret": "SOME_CLIENT_SECRET","client_id": "SOME_CLIENT_ID"}' ``` -And the command below is an example of how to bind the service instance to the app: +And to bind the service instance to the app: ```shell cf bind-service MY_APPLICATION MY_SERVICE_INSTANCE ``` -For additional information, refer to the [UAA documentation](https://docs.cloudfoundry.org/concepts/architecture/uaa.html). +For additional information, see the [UAA documentation](https://docs.cloudfoundry.org/concepts/architecture/uaa.html). diff --git a/api/v4/security/redis-key-storage-provider.md b/api/v4/security/redis-key-storage-provider.md index c442e6cb..05bbae74 100644 --- a/api/v4/security/redis-key-storage-provider.md +++ b/api/v4/security/redis-key-storage-provider.md @@ -2,14 +2,17 @@ The Redis Key Storage Provider is commonly used when secured data needs to be shared between two or more instances of the same application. +> [!NOTE] +> The Key Storage Provider can be used with [Redis](https://redis.io/) and [Valkey](https://valkey.io/) databases. + By default, the [data protection system in ASP.NET Core](https://learn.microsoft.com/aspnet/core/security/data-protection/introduction) stores cryptographic keys on the local file system. Even when not used by the application directly, these cryptographic keys are used for systems like [session state](https://learn.microsoft.com/aspnet/core/fundamentals/app-state#session-state) storage. -By using the Steeltoe Redis key storage provider, you can easily reconfigure the data protection service to store these keys in Redis instances that are accessible through the [Steeltoe Redis Connector](../connectors/redis.md). +By using the Steeltoe Redis Key Storage Provider, you can easily reconfigure the data protection service to store these keys in Redis/Valkey instances that are accessible through the [Steeltoe Redis Connector](../connectors/redis.md). -The [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/RedisDataProtection/README.md) can help you understand how and why to use this tool. +For more information, see the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/RedisDataProtection/README.md). -## Usage +## Using the Redis Key Storage Provider To use this provider: @@ -18,17 +21,17 @@ To use this provider: 1. Initialize the Steeltoe Connector at startup. 1. Configure the data protection system to persist keys in the Redis database. 1. Add the Cloud Foundry configuration provider. -1. Create a Redis service instance and bind it to your application. +1. Create a Redis/Valkey service instance and bind it to your application. ### Add NuGet References -To use the provider, you need to add a reference to the `Steeltoe.Security.DataProtection.Redis` NuGet package. +To use the provider, add a reference to the `Steeltoe.Security.DataProtection.Redis` NuGet package. -If you are using Cloud Foundry service bindings, you will also need to add a reference to `Steeltoe.Configuration.CloudFoundry`. +If you are using Cloud Foundry service bindings, you must also add a reference to `Steeltoe.Configuration.CloudFoundry`. ### Configure connection string -You must configure a connection string in order to use Redis. +You must configure a connection string to use Redis/Valkey. The following example `appsettings.Development.json` uses a local Redis server listening on the default Redis port: ```json @@ -47,7 +50,7 @@ The following example `appsettings.Development.json` uses a local Redis server l ### Initialize Steeltoe Connector -Update your `Program.cs` as below to initialize the Connector: +Update your `Program.cs` to initialize the Connector: ```csharp using Steeltoe.Connectors.Redis; @@ -60,11 +63,11 @@ builder.AddRedis(); There are several steps required to configure key storage in Redis: -- Add data protection (while the services are added automatically, this step is required in order to access the builder). +- Add data protection (while the services are added automatically, this step is required for accessing the builder). - Set the key persistence location to Redis. - Set an application name so all instances of the application can see the same data. -These steps can be performed by chaining the method calls together: +These steps can be performed by chaining the method calls: ```csharp using Microsoft.AspNetCore.DataProtection; @@ -75,7 +78,7 @@ builder.Services.AddDataProtection().PersistKeysToRedis().SetApplicationName("re > [!NOTE] > At this point, the keys used by the `DataProtection` framework are stored in the bound Redis service. -> No additional steps are _required_, but you can also [use data protection in your application](https://learn.microsoft.com/aspnet/core/security/data-protection/consumer-apis/overview). +> No additional steps are _required_, but you can also use [data protection](https://learn.microsoft.com/aspnet/core/security/data-protection/consumer-apis/overview) in your application. ### Add Cloud Foundry Configuration @@ -91,11 +94,11 @@ builder.AddCloudFoundryConfiguration(); ### Cloud Foundry -To use the Redis data protection key ring provider on Cloud Foundry, [use a supported Redis service](../connectors/redis.md#cloud-foundry) to create and bind an instance of Redis to your application. +To store data protection keys in a Redis/Valkey cache on Cloud Foundry, use a supported [Redis service](../connectors/redis.md#cloud-foundry) to create and bind an instance of Redis/Valkey to your application. You can complete these steps using the Cloud Foundry command line, as follows: -```bash +```shell # Push your app cf push sampleApp --buildpack dotnet_core_buildpack @@ -109,11 +112,11 @@ cf bind-service sampleApp sampleRedisService cf restage sampleApp ``` +After the service is bound to your application, the configuration settings are available in `VCAP_SERVICES`. + > [!NOTE] > The preceding commands are for the Redis service provided by Tanzu Platform for Cloud Foundry. -> If you use a different service, you have to adjust the `create-service` command. - -Once the service is bound to your application, the configuration settings are available in `VCAP_SERVICES`. +> If you use a different service, adjust the `create-service` command accordingly. > [!TIP] -> Explore the [Steeltoe sample application](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/RedisDataProtection/README.md) for a demonstration on why this provider is useful. +> For more information, see the [Steeltoe sample application](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/RedisDataProtection/README.md). diff --git a/api/v4/security/sso-open-id.md b/api/v4/security/sso-open-id.md index a8970d80..195e2bb4 100644 --- a/api/v4/security/sso-open-id.md +++ b/api/v4/security/sso-open-id.md @@ -1,17 +1,19 @@ # Single Sign-On with OpenID Connect -OpenID Connect is commonly used when users should be able to interact with a collection of applications using a single set of credentials for authentication and authorization. +OpenID Connect is commonly used when users need to be able to interact with a collection of applications using a single set of credentials for authentication and authorization. This library is a supplement to ASP.NET Core Security's OpenID Connect library (`Microsoft.AspNetCore.Authentication.OpenIdConnect`), adding functionality that helps you use Cloud Foundry Security services such as [Single Sign-On for VMware Tanzu](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/index.html) or [User Account and Authentication (UAA) Server](https://github.com/cloudfoundry/uaa). -General guidance on OpenID Connect is beyond the scope of this document and can be found in many other sources (for example, see [OpenID](https://openid.net/developers/how-connect-works/)). -For the documentation of the underlying Microsoft OpenID Connect library, visit the [official documentation](https://learn.microsoft.com/aspnet/core/security/authentication/configure-oidc-web-authentication). +General guidance on the use of OpenID Connect is beyond the scope of this document; these resources are recommended: -The [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md) can help you understand how to use this library. +* [OpenID](https://openid.net/developers/how-connect-works/) +* [Microsoft OpenID Connect library](https://learn.microsoft.com/aspnet/core/security/authentication/configure-oidc-web-authentication) -## Usage +For more information about how to use this library, see the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md). -Steps involved in using this library: +## Using the OpenID Connect Library + +To use the OpenID Connect library: 1. Add NuGet references. 1. Configure settings for the security provider. @@ -21,15 +23,16 @@ Steps involved in using this library: ### Add NuGet References -To use this package, you will need to add a reference to the NuGet package `Steeltoe.Security.Authentication.OpenIdConnect`. +To use this package, add NuGet package references to: -Also add a reference to `Steeltoe.Configuration.CloudFoundry`, so that Cloud Foundry service bindings can be read by Steeltoe. +* `Steeltoe.Security.Authentication.OpenIdConnect` +* `Steeltoe.Configuration.CloudFoundry` (so that Cloud Foundry service bindings can be read by Steeltoe) ### Configure Settings -Since Steeltoe's OpenID Connect library configures Microsoft's OpenID Connect implementation, all available settings can be found in [`Microsoft.AspNetCore.Authentication.OpenIdConnect.OpenIdConnectOptions`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.authentication.openidconnect.openidconnectoptions) +The Steeltoe OpenID Connect library configures the Microsoft OpenID Connect implementation, so all supported settings are available in [`Microsoft.AspNetCore.Authentication.OpenIdConnect.OpenIdConnectOptions`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.authentication.openidconnect.openidconnectoptions). -`OpenIdConnectOptions` is bound to configuration values found under `Authentication:Schemes:OpenIdConnect`. The following example `appsettings.json` shows how to declare a list of permissions that should be requested for users: +`OpenIdConnectOptions` is bound to configuration values found at the key `Authentication:Schemes:OpenIdConnect`. The following example `appsettings.json` shows how to declare a list of permissions that should be requested for users. ```json { @@ -46,7 +49,7 @@ Since Steeltoe's OpenID Connect library configures Microsoft's OpenID Connect im #### Cloud Foundry Service Bindings -The Steeltoe package `Steeltoe.Configuration.CloudFoundry` reads Single Sign-On credentials from Cloud Foundry service bindings (`VCAP_SERVICES`) and re-maps them for Microsoft's OpenID Connect to read. Add the configuration provider to your application with this code: +The Steeltoe package `Steeltoe.Configuration.CloudFoundry` reads Single Sign-On credentials from Cloud Foundry service bindings (`VCAP_SERVICES`) and re-maps them for Microsoft OpenID Connect to read. Add the configuration provider to your application as shown in the following example. ```csharp using Steeltoe.Configuration.CloudFoundry; @@ -61,7 +64,7 @@ builder.Configuration.AddCloudFoundryServiceBindings(); #### Local UAA -A UAA server (such as [UAA Server for Steeltoe samples](https://github.com/SteeltoeOSS/Dockerfiles/tree/main/uaa-server)) can be used for local development of applications that will be deployed to Cloud Foundry. Configuration of UAA itself is beyond the scope of this documentation, but configuring your `appsettings.Development.json` to work with a local UAA server is possible with the addition of settings like these: +A UAA server (such as [UAA Server for Steeltoe samples](https://github.com/SteeltoeOSS/Dockerfiles/tree/main/uaa-server)) can be used for local development of applications that will be deployed to Cloud Foundry. Configuration of UAA itself is beyond the scope of this documentation, but after it is set up, you can configure your `appsettings.Development.json` to work with a local UAA server using code similar to the following example: ```json { @@ -80,13 +83,13 @@ A UAA server (such as [UAA Server for Steeltoe samples](https://github.com/Steel ``` > [!IMPORTANT] -> If you wish to use the Steeltoe UAA server without modification, some application configuration options will be very limited. -> Because the OpenID Connect authentication flow requires user redirection to known locations, the client `steeltoesamplesclient` is expected to listen at , so you will need to update launchSettings.json accordingly. -> The Steeltoe UAA Server configuration can be found in [uaa.yml](https://github.com/SteeltoeOSS/Dockerfiles/blob/main/uaa-server/uaa.yml#L116). +> If you want to use the Steeltoe UAA server without modification, some application configuration options will be very limited. +> Because the OpenID Connect authentication flow requires user redirection to known locations, the client `steeltoesamplesclient` is expected to listen at https://localhost:7072, so you must update `launchSettings.json` accordingly. +> The Steeltoe UAA Server configuration is located in [uaa.yml](https://github.com/SteeltoeOSS/Dockerfiles/blob/main/uaa-server/uaa.yml#L116). ### Add and use OpenID Connect -Since the majority of the OpenID Connect functionality is provided by Microsoft's libraries, the only difference when using Steeltoe will be the addition of calling `ConfigureOpenIdConnectForCloudFoundry` on the `AuthenticationBuilder`, as shown in the following example: +Most of the OpenID Connect functionality is provided by the Microsoft libraries, so the only difference when using Steeltoe is that you must also call `ConfigureOpenIdConnectForCloudFoundry` on the `AuthenticationBuilder`, as shown in the following example: ```csharp using Microsoft.AspNetCore.Authentication.Cookies; @@ -115,7 +118,8 @@ builder.Services.AddAuthorizationBuilder() .AddPolicy("sampleapi.read", policy => policy.RequireClaim("scope", "sampleapi.read")); ``` -Activate authentication and authorization services _after_ routing services, but _before_ controller route registrations, with the following code: +The middleware pipeline order is important: +Activate authentication and authorization services _after_ routing services, but _before_ controller route registrations, as shown in the following example. ```csharp using Microsoft.AspNetCore.HttpOverrides; @@ -134,12 +138,12 @@ app.MapDefaultControllerRoute(); app.Run(); ``` -> [!TIP] -> In the sample code above, `app.UseForwardedHeaders` is used so that any links generated within the application will be compatible with reverse-proxy scenarios, such as when running in Cloud Foundry. +> [!NOTE] +> In the sample code above, `app.UseForwardedHeaders` is used so that any links generated within the application are compatible with reverse-proxy scenarios, such as when running in Cloud Foundry. ### Securing Endpoints -Once the services and middleware have been configured, you can secure endpoints with the standard ASP.NET Core `Authorize` attribute, as follows: +After the services and middleware have been configured, you can secure endpoints with the standard ASP.NET Core `Authorize` attribute, as follows: ```csharp using Microsoft.AspNetCore.Authorization; @@ -166,19 +170,19 @@ The preceding example establishes the following security rules: * If a user attempts to access the `Privacy` action and the user is not authenticated, the user is redirected to the OAuth server (such as a UAA Server) to log in. * If an authenticated user attempts to access the `TestGroup` action but does not meet the restrictions established by the referenced policy, the user is denied access. -> [!TIP] +> [!NOTE] > The Steeltoe UAA server has several pre-provisioned user accounts. Sign in with `testuser` and password `password` to access resources secured with `sampleapi.read` > To test with a user that does not have the permission `sampleapi.read`, sign in with the user `customer` and password `password`. > -> You may want to explore the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md) for examples of additional basic functionality such as signing out of the application. +> See the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md) for examples of additional basic functionality, such as signing out of the application. ### Single Sign-On for VMware Tanzu -When using Single Sign-On for VMware Tanzu, you will need to identify the service plan to be used before creating a service instance of that plan. +When using Single Sign-On for VMware Tanzu, you must choose a service plan before you create a service instance. If you do not have an existing service plan, a platform operator may need to create a new plan for you. -The operator should refer to the [Single Sign-On for Tanzu operator guide](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/operator-index.html) for information on how to configure plans for developer use. +For information about configuring service plans for use by developers, a platform operator should follow the steps in the [Single Sign-On for Tanzu operator guide](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/operator-index.html). -Once you have identified the service plan that will be used, create a service instance: +After you have identified the service plan to use, create a service instance: ```shell cf create-service p-identity SERVICE_PLAN_NAME MY_SERVICE_INSTANCE @@ -186,9 +190,10 @@ cf create-service p-identity SERVICE_PLAN_NAME MY_SERVICE_INSTANCE #### Bind and configure with app manifest -Using a manifest file when you deploy to Cloud Foundry is recommended, and can save some work with the SSO configuration. Review the Single Sign-On documentation for [configuring an app manifest](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/config-apps.html#configure-app-manifest). +Using a manifest file when you deploy to Cloud Foundry is recommended, and can save some work with the SSO configuration. +For information about configuring an app manifest, see the [Single Sign-On documentation](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/config-apps.html#configure-app-manifest). -Consider this example manifest that names the application, buildpack and configures several properties for the SSO binding: +Consider this example manifest that names the application and buildpack, and configures properties for the SSO binding: ```yml applications: @@ -207,7 +212,8 @@ applications: #### Bind and configure manually -Alternatively, you can manually bind the instance, restage the app with the Cloud Foundry CLI and later configure the SSO binding yourself with the web interface: +Alternatively, you can bind the instance manually and restage the app with the Cloud Foundry CLI. +Then you can configure the SSO binding with the web interface: ```shell # Bind service to your app @@ -217,24 +223,27 @@ cf bind-service MY_APPLICATION MY_SERVICE_INSTANCE cf restage MY_APPLICATION ``` -For further information, such as instructions on using the web interface, refer to the [Single Sign-On for Tanzu developer guide](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/developer-index.html) or follow the instructions included in the [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md). +For more information, see: + +* [Single Sign-On for Tanzu developer guide](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform-services/single-sign-on-for-tanzu/1-16/sso-tanzu/developer-index.html) +* [Steeltoe Security samples](https://github.com/SteeltoeOSS/Samples/blob/main/Security/src/AuthWeb/README.md). ### UAA Server -If Single Sign-On for Tanzu is not available or desired for your application, you can use UAA as an alternative. +If Single Sign-On for Tanzu is not available or desired for your application, you can use UAA. -There is no service broker available to manage service instances or bindings for UAA, so a [user provided service instance](https://docs.cloudfoundry.org/devguide/services/user-provided.html) should be used to hold the credentials. +There is no service broker available to manage service instances or bindings for UAA, so you must have a [user provided service instance](https://docs.cloudfoundry.org/devguide/services/user-provided.html) to hold the credentials. -This command is an example of how the binding could be created: +This command is an example of how the service instance can be created: ```shell cf cups MY_SERVICE_INSTANCE -p '{"auth_domain": "https://uaa.login.sys.cf-app.com","grant_types": [ "authorization_code", "client_credentials" ],"client_secret": "SOME_CLIENT_SECRET","client_id": "SOME_CLIENT_ID"}' ``` -And this command is an example of how to bind the service instance to the app: +And to bind the service instance to the app: ```shell cf bind-service MY_APPLICATION MY_SERVICE_INSTANCE ``` -For additional information, refer to the [UAA documentation](https://docs.cloudfoundry.org/concepts/architecture/uaa.html). +For additional information, see the [UAA documentation](https://docs.cloudfoundry.org/concepts/architecture/uaa.html). diff --git a/api/v4/toc.yml b/api/v4/toc.yml index dc5e8416..8102f25e 100644 --- a/api/v4/toc.yml +++ b/api/v4/toc.yml @@ -92,7 +92,7 @@ topicHref: fileshares/ items: - topicHref: fileshares/usage.md - name: Usage + name: Using Network File Shares - name: Security topicHref: security/ items: @@ -108,7 +108,7 @@ topicHref: connectors/ items: - topicHref: connectors/usage.md - name: Usage + name: Overview - topicHref: connectors/extensibility.md name: Extensibility - topicHref: connectors/mysql.md @@ -124,7 +124,7 @@ - topicHref: connectors/cosmosdb.md name: CosmosDB - topicHref: connectors/redis.md - name: Redis + name: Redis/Valkey - name: Service Discovery topicHref: discovery/ items: diff --git a/api/v4/tracing/index.md b/api/v4/tracing/index.md index dd9535b8..f8945356 100644 --- a/api/v4/tracing/index.md +++ b/api/v4/tracing/index.md @@ -1,26 +1,28 @@ # Distributed Tracing -On the subject of distributed tracing for .NET applications, previous versions of Steeltoe offered either an implementation of OpenCensus or shortcuts for enabling distributed tracing with [OpenTelemetry](https://opentelemetry.io/) to integrate with the Tanzu platform. We painted ourselves into a corner with Steeltoe 3, which has a strong dependency on OpenTelemetry packages. New versions of OpenTelemetry contained breaking changes, which we couldn't adapt to without resorting to reflection. While we do that in other places, reflection is slow, and instrumentation is performance-sensitive. +This topic describes distributed tracing for .NET applications. -By now, OpenTelemetry has evolved to the point that only a few lines of code are needed. So instead of providing a Steeltoe component, the guidance below is offered to accomplish the same. The benefit of that is greater flexibility: when OpenTelemetry changes, there's no need to wait for a new Steeltoe version first. +Previous versions of Steeltoe offered either an implementation of OpenCensus or shortcuts for enabling distributed tracing with [OpenTelemetry](https://opentelemetry.io/) to integrate with the Tanzu platform. Steeltoe 3 has a strong dependency on OpenTelemetry packages, but with the breaking changes in the latest versions of OpenTelemetry, Steeltoe couldn't adapt without resorting to reflection. While we do that in other places, reflection is slow, and instrumentation is performance-sensitive. -Steeltoe continues to directly offer an option for [log correlation](#log-correlation). This page also provides direction for developers looking to achieve the same outcomes Steeltoe has previously provided more directly. +OpenTelemetry has evolved to the point that only a few lines of code are needed. So instead of providing a Steeltoe component, the guidance below is offered to accomplish the same. The benefit of this approach is greater flexibility: when OpenTelemetry changes, there's no need to wait for a new Steeltoe version before using it. -## Introduction +Steeltoe continues to directly offer an option for [log correlation](#log-correlation). The remainder of this topic provides direction for developers looking to achieve the same outcomes Steeltoe has previously provided more directly. + +## About distributed tracing As the name implies, distributed tracing is a way of tracing requests through distributed systems. -Distributed tracing is typically accomplished by instrumenting components of the system to recognize and pass along metadata that is specific to a particular action or user request, and using another backend system to reconstruct the flow of the request through that metadata. +Distributed tracing is typically accomplished by instrumenting components of the system to allow recognizing and passing along metadata that is specific to a particular action or user request, and using another backend system to reconstruct the flow of the request through that metadata. In the parlance of distributed tracing, a "span" is the basic unit of work. For example, sending an HTTP request creates a new span, as does sending a response. -Spans are identified by a unique ID and contain the ID for the "trace" it is part of. +Each span is identified by a unique ID and contains the ID for the "trace" it is part of. Spans also have other data like descriptions, key-value annotations, the ID of the span that initiated the execution flow, and process IDs. -Spans are started and stopped, and they keep track of their timing information. Once you create a span, you must stop it at some point in the future. -A set of spans form a tree-like structure called a "trace". For example, a trace might be formed by a POST request that adds an item to a shopping cart, which results in calling several backend services. +Spans are started and stopped, and they keep track of their timing information. After you create a span, you must stop it at some point in the future. +A set of spans form a tree-like structure called a "trace." For example, a trace might be formed by a POST request that adds an item to a shopping cart, which results in calling several backend services. ## Log correlation -Log correlation is all about taking log entries from disparate systems and bringing them together using some matching criteria (such as a distributed trace ID). -The process can be easier when important pieces of data are logged in the same format across different systems (such as .NET and Java apps communicating with each other). +Log correlation refers to the process of taking log entries from disparate systems and bringing them together using some matching criteria (such as a distributed trace ID). +The process is easier when important pieces of data are logged in the same format across different systems (such as .NET and Java apps communicating with each other). Steeltoe provides the class `TracingLogProcessor`, which is an `IDynamicMessageProcessor` for correlating logs. The processor is built for use with a [Steeltoe Dynamic Logging provider](../logging/index.md). It enriches log entries with correlation data using the same trace format popularized by [Spring Cloud Sleuth](https://cloud.spring.io/spring-cloud-sleuth/reference/html/#log-correlation), @@ -36,32 +38,36 @@ dbug: Microsoft.EntityFrameworkCore.Database.Command[20104] [ActuatorApi,44ed2fe24a051bda2d1a56815448e9fb,c32846ff227bed40,f315823f4c554816,true] Created DbCommand for 'ExecuteReader' (1ms). ``` -Log correlation is easiest with a tool such as [Splunk](https://www.splunk.com/en_us/solutions/isolate-cloud-native-problems.html), [SumoLogic](https://www.sumologic.com/lp/log-analytics/) or [DataDog](https://www.datadoghq.com/dg/enterprise/log-management-analytics-security) (this is not an endorsement of any tool, only a pointer to some popular options). +Log correlation is easiest with a tool such as [Splunk](https://www.splunk.com/en_us/solutions/isolate-cloud-native-problems.html), [SumoLogic](https://www.sumologic.com/lp/log-analytics/), or [DataDog](https://www.datadoghq.com/dg/enterprise/log-management-analytics-security). (This is not an endorsement of any tool, only a pointer to some popular options.) ### Using TracingLogProcessor -To use the processor, first add a reference to the `Steeltoe.Management.Tracing` NuGet package. +To use the processor: -The only remaining step is to register the processor: +1. Add a reference to the `Steeltoe.Management.Tracing` NuGet package. -```csharp -using Steeltoe.Management.Tracing; +1. Register the processor from `Program.cs`: -var builder = WebApplication.CreateBuilder(args); -builder.Services.AddTracingLogProcessor(); -``` + ```csharp + using Steeltoe.Management.Tracing; + + var builder = WebApplication.CreateBuilder(args); + builder.Services.AddTracingLogProcessor(); + ``` > [!NOTE] -> This extension method also ensures that implementations of `IApplicationInstanceInfo` and `IDynamicLoggerProvider` have been registered. -> If you wish to customize either of those or use non-default implementations, do so before calling `AddTracingLogProcessor`. +> The `AddTracingLogProcessor()` extension method also ensures that implementations of `IApplicationInstanceInfo` and `IDynamicLoggerProvider` have been registered. +> If you want to customize either of these or use non-default implementations, call their extension methods *before* calling `AddTracingLogProcessor`. ## OpenTelemetry To use OpenTelemetry, start by adding a reference to the `OpenTelemetry.Extensions.Hosting` NuGet package. -Other package references will likely be necessary, but depend on your specific application needs. +Depending on your specific application needs, other package references will probably be necessary. This package provides access to `OpenTelemetryBuilder`, which is the main entrypoint to OpenTelemetry. -### Add Open Telemetry Tracing +### Add OpenTelemetry Tracing + +To use tracing with OpenTelemetry, add the following to your `Program.cs`: ```csharp var builder = WebApplication.CreateBuilder(args); @@ -69,80 +75,85 @@ builder.Services.AddOpenTelemetry().WithTracing(); ``` > [!NOTE] -> At this point, not much has changed for the application - you will need changes to this line to add [instrumentation](#instrumenting-applications) and [exporting of traces](#exporting-distributed-traces). +> At this point, not much has changed for the application. The following sections will expand this line to add [instrumentation](#instrumenting-applications) and [exporting of traces](#exporting-distributed-traces). ### Sampler configuration OpenTelemetry Provides the `Sampler` abstraction for configuring when traces should be recorded. The simplest options are `AlwaysOnSampler` and `AlwaysOffSampler`, with their names describing exactly which traces will be recorded. -As a replacement for what Steeltoe used to provide for using these samplers, set the environment variable `OTEL_TRACES_SAMPLER` to `always_on` or `always_off`. +As a replacement for what Steeltoe used to provide for using these samplers, set the environment variable `OTEL_TRACES_SAMPLER` to: + +* `always_on` +* `always_off` > [!TIP] > OpenTelemetry is generally built to follow the [options pattern](https://learn.microsoft.com/dotnet/core/extensions/options). -> There are more ways to configure options than demonstrated on this page, these are just examples to get started. +> There are more ways to configure options than demonstrated in this topic; these are just examples to help you get started. ### Set Application Name -In order to use the Steeltoe name for your application with OpenTelemetry, call `SetResourceBuilder` and pass in a value from the registered `IApplicationInstanceInfo`: +To use the Steeltoe name for your application with OpenTelemetry, call `SetResourceBuilder` and pass in a value from the registered `IApplicationInstanceInfo`: ```csharp using OpenTelemetry.Resources; using OpenTelemetry.Trace; using Steeltoe.Common; -builder.Services.ConfigureOpenTelemetryTracerProvider((serviceProvider, tracerProviderBuilder) => +builder.Services.ConfigureOpenTelemetryTracerProvider((serviceProvider, tracing) => { var appInfo = serviceProvider.GetRequiredService(); - tracerProviderBuilder.SetResourceBuilder(ResourceBuilder.CreateDefault().AddService(appInfo.ApplicationName!)); + tracing.SetResourceBuilder(ResourceBuilder.CreateDefault().AddService(appInfo.ApplicationName!)); }); ``` -The above example assumes you are already using some other Steeltoe component which adds `IApplicationInstanceInfo` to the IoC container. If that is not the case, there are two steps to take to register the default implementation: +The above example assumes you are already using some other Steeltoe component that adds `IApplicationInstanceInfo` to the IoC container. If that is not the case, follow these steps to register the default implementation: -1. Add a NuGet package reference to `Steeltoe.Common` -1. Call `AddApplicationInstanceInfo` +1. Add a NuGet package reference to `Steeltoe.Common`. +1. Call `AddApplicationInstanceInfo`. -```csharp -using Steeltoe.Common.Extensions; + ```csharp + using Steeltoe.Common.Extensions; -var builder = WebApplication.CreateBuilder(args); -builder.Services.AddApplicationInstanceInfo(); -``` + var builder = WebApplication.CreateBuilder(args); + builder.Services.AddApplicationInstanceInfo(); + ``` ### Instrumenting applications -In order to maximize the benefit of collecting distributed traces, you'll want participation from the core components and frameworks of your application and some 3rd party components. -Some packages in the .NET ecosystem automatically support OpenTelemetry, others can be supported by the [collection of instrumentation libraries](https://opentelemetry.io/ecosystem/registry/?language=dotnet&component=instrumentation). -Steeltoe previously configured the instrumentation libraries for [HttpClient](#httpclient) and [ASP.NET Core](#aspnet-core). +To maximize the benefit of collecting distributed traces, ideally, you will have participation from the core components and frameworks of your application and some third-party components. +Some packages in the .NET ecosystem automatically support OpenTelemetry; others can be supported by the [collection of instrumentation libraries](https://opentelemetry.io/ecosystem/registry/?language=dotnet&component=instrumentation). +Steeltoe previously configured the instrumentation libraries for [ASP.NET Core](#aspnet-core) and [HttpClient](#httpclient). #### ASP.NET Core -To instrument requests coming into the application through ASP.NET Core, start by adding a reference to the `OpenTelemetry.Instrumentation.AspNetCore` NuGet package. +To instrument requests coming into the application through ASP.NET Core: -Next, add the instrumentation to the `TracerProviderBuilder` by updating the existing call from above to: +1. Add a reference to the `OpenTelemetry.Instrumentation.AspNetCore` NuGet package. -```csharp -using OpenTelemetry.Trace; +1. Add the instrumentation to the `TracerProviderBuilder` by updating the existing call from the earlier example to: -builder.Services.AddOpenTelemetry().WithTracing(tracerProviderBuilder => tracerProviderBuilder.AddAspNetCoreInstrumentation()); -``` + ```csharp + using OpenTelemetry.Trace; -In order to replicate the Steeltoe setting `IngressIgnorePattern` (a Regex pattern describing which incoming requests to ignore), configure the `AspNetCoreTraceInstrumentationOptions`: + builder.Services.AddOpenTelemetry().WithTracing(tracing => tracing.AddAspNetCoreInstrumentation()); + ``` -```csharp -using System.Text.RegularExpressions; -using OpenTelemetry.Instrumentation.AspNetCore; +1. To replicate the Steeltoe setting `IngressIgnorePattern` (a Regex pattern describing which incoming requests to ignore), configure the `AspNetCoreTraceInstrumentationOptions`: -builder.Services.Configure(options => -{ - const string defaultIngressIgnorePattern = @"/actuator/.*|/cloudfoundryapplication/.*|.*\.png|.*\.css|.*\.js|.*\.html|/favicon.ico|.*\.gif"; - Regex ingressPathMatcher = new(defaultIngressIgnorePattern, RegexOptions.Compiled | RegexOptions.CultureInvariant, TimeSpan.FromSeconds(1)); - options.Filter += httpContext => !ingressPathMatcher.IsMatch(httpContext.Request.Path); -}); -``` + ```csharp + using System.Text.RegularExpressions; + using OpenTelemetry.Instrumentation.AspNetCore; -As an alternative to using a regular expression, you can list out the paths to ignore in the Filter property (`Filter` is a `Func?`): + builder.Services.Configure(options => + { + const string defaultIngressIgnorePattern = @"/actuator/.*|/cloudfoundryapplication/.*|.*\.png|.*\.css|.*\.js|.*\.html|/favicon.ico|.*\.gif"; + Regex ingressPathMatcher = new(defaultIngressIgnorePattern, RegexOptions.Compiled | RegexOptions.CultureInvariant, TimeSpan.FromSeconds(1)); + options.Filter += httpContext => !ingressPathMatcher.IsMatch(httpContext.Request.Path); + }); + ``` + +Alternatively, rather than using a regular expression, you can list the paths to ignore in the Filter property (`Filter` is a `Func?`): ```csharp using OpenTelemetry.Instrumentation.AspNetCore; @@ -155,86 +166,95 @@ builder.Services.Configure(options => }); ``` -> [!TIP] +> [!NOTE] > By default, the ASP.NET Core instrumentation does not filter out any requests. -> The latter approach above may quickly prove unwieldy if there are many patterns to ignore, such as when listing many file types. +> The alternative approach described can quickly prove unwieldy if there are many patterns to ignore, such as when listing many file types. -To learn more about ASP.NET Core instrumentation for OpenTelemetry see [the documentation](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/main/src/OpenTelemetry.Instrumentation.AspNetCore). +To learn more about ASP.NET Core instrumentation for OpenTelemetry see the [OpenTelemetry documentation](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/main/src/OpenTelemetry.Instrumentation.AspNetCore). #### HttpClient -To instrument requests leaving the application through `HttpClient`, start by adding a reference to the `OpenTelemetry.Instrumentation.Http` NuGet package. +To instrument requests leaving the application through `HttpClient`: -Next, add the instrumentation to the `TracerProviderBuilder` by updating the existing call from above to: +1. Add a reference to the `OpenTelemetry.Instrumentation.Http` NuGet package. -```csharp -using OpenTelemetry.Trace; +1. Add the instrumentation to the `TracerProviderBuilder` by updating the existing call from above to: -builder.Services.AddOpenTelemetry().WithTracing(tracerProviderBuilder => tracerProviderBuilder.AddHttpClientInstrumentation()); -``` + ```csharp + using OpenTelemetry.Trace; -In order to replicate the Steeltoe setting `EgressIgnorePattern` (a Regex pattern describing which outgoing HTTP requests to ignore), configure the `HttpClientTraceInstrumentationOptions`: + builder.Services.AddOpenTelemetry().WithTracing(tracing => tracing.AddHttpClientInstrumentation()); + ``` -```csharp -using OpenTelemetry.Instrumentation.Http; -using System.Text.RegularExpressions; +1. To replicate the Steeltoe setting `EgressIgnorePattern` (a Regex pattern describing which outgoing HTTP requests to ignore), configure the `HttpClientTraceInstrumentationOptions`: -builder.Services.Configure(options => -{ - const string defaultEgressIgnorePattern = "/api/v2/spans|/v2/apps/.*/permissions"; - Regex egressPathMatcher = new(defaultEgressIgnorePattern, RegexOptions.Compiled | RegexOptions.CultureInvariant, TimeSpan.FromSeconds(1)); - options.FilterHttpRequestMessage += httpRequestMessage => !egressPathMatcher.IsMatch(httpRequestMessage.RequestUri?.PathAndQuery ?? string.Empty); -}); -``` + ```csharp + using OpenTelemetry.Instrumentation.Http; + using System.Text.RegularExpressions; + + builder.Services.Configure(options => + { + const string defaultEgressIgnorePattern = "/api/v2/spans|/v2/apps/.*/permissions"; + Regex egressPathMatcher = new(defaultEgressIgnorePattern, RegexOptions.Compiled | RegexOptions.CultureInvariant, TimeSpan.FromSeconds(1)); + options.FilterHttpRequestMessage += httpRequestMessage => !egressPathMatcher.IsMatch(httpRequestMessage.RequestUri?.PathAndQuery ?? string.Empty); + }); + ``` -To learn more about HttpClient instrumentation for OpenTelemetry see [the documentation](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/main/src/OpenTelemetry.Instrumentation.Http). +To learn more about HttpClient instrumentation for OpenTelemetry see the [OpenTelemetry documentation](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/main/src/OpenTelemetry.Instrumentation.Http). ### Propagating Trace Context By default, OpenTelemetry uses the [W3C trace context](https://github.com/w3c/trace-context) for propagating traces. Some systems like Cloud Foundry may still be configured for the Zipkin standard of [B3 propagation](https://github.com/openzipkin/b3-propagation). -In order to use B3 propagation, add a reference to the `OpenTelemetry.Extensions.Propagators` NuGet package. +To use B3 propagation: -Next, let the compiler know that the `B3Propagator` should come from the package reference you just added (rather than the deprecated class found in `OpenTelemetry.Context.Propagation`): +1. Add a reference to the `OpenTelemetry.Extensions.Propagators` NuGet package. -```csharp -using B3Propagator = OpenTelemetry.Extensions.Propagators.B3Propagator; -``` +1. Let the compiler know that the `B3Propagator` should come from the package reference you just added (rather than the deprecated class found in `OpenTelemetry.Context.Propagation`): -Finally, register a `CompositeTextMapPropagator` that includes the `B3Propagator` and `BaggagePropagator`: + ```csharp + using B3Propagator = OpenTelemetry.Extensions.Propagators.B3Propagator; + ``` -```csharp -using OpenTelemetry; -using OpenTelemetry.Context.Propagation; -using OpenTelemetry.Trace; +1. Register a `CompositeTextMapPropagator` that includes the `B3Propagator` and `BaggagePropagator`: -builder.Services.ConfigureOpenTelemetryTracerProvider((_, _) => -{ - List propagators = - [ - new B3Propagator(), - new BaggagePropagator() - ]; + ```csharp + using OpenTelemetry; + using OpenTelemetry.Context.Propagation; + using OpenTelemetry.Trace; - Sdk.SetDefaultTextMapPropagator(new CompositeTextMapPropagator(propagators)); -}); -``` + builder.Services.ConfigureOpenTelemetryTracerProvider((_, _) => + { + List propagators = + [ + new B3Propagator(), + new BaggagePropagator() + ]; + + Sdk.SetDefaultTextMapPropagator(new CompositeTextMapPropagator(propagators)); + }); + ``` ### Exporting Distributed Traces -Previous versions of Steeltoe could automatically configure several different trace exporters, including [Zipkin](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry.Exporter.Zipkin), [OpenTelemetryProtocol (OTLP)](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry.Exporter.OpenTelemetryProtocol) and Jaeger. -The Jaeger exporter has been deprecated in favor of OTLP, which was only minimally configured by Steeltoe and is better described by [the official OTLP exporter documentation](https://opentelemetry.io/docs/languages/net/exporters/#otlp). +Previous versions of Steeltoe could automatically configure several different trace exporters, including: + +* [Zipkin](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry.Exporter.Zipkin) +* [OpenTelemetryProtocol (OTLP)](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry.Exporter.OpenTelemetryProtocol) +* Jaeger. The Jaeger exporter has been deprecated in favor of OTLP, which was only minimally configured by Steeltoe. For more information, see the [OTLP exporter documentation](https://opentelemetry.io/docs/languages/net/exporters/#otlp). #### Zipkin Server -To use the Zipkin Exporter, add a reference to the `OpenTelemetry.Exporter.Zipkin` NuGet package. +To use the Zipkin Exporter: -Next, use the extension method `AddZipkinExporter` by updating the existing call from above to: +1. Add a reference to the `OpenTelemetry.Exporter.Zipkin` NuGet package. -```csharp -builder.Services.AddOpenTelemetry().WithTracing(tracerProviderBuilder => tracerProviderBuilder.AddZipkinExporter()); -``` +1. Use the extension method `AddZipkinExporter` by updating the existing call from above to: + + ```csharp + builder.Services.AddOpenTelemetry().WithTracing(tracing => tracing.AddZipkinExporter()); + ``` The Zipkin options class `ZipkinExporterOptions` works nearly the same as Steeltoe settings with the same names in previous releases: @@ -250,4 +270,4 @@ builder.Services.Configure(options => ``` > [!TIP] -> The Zipkin endpoint can also be set with the environment variable "OTEL_EXPORTER_ZIPKIN_ENDPOINT". +> The Zipkin endpoint can also be set with the environment variable `OTEL_EXPORTER_ZIPKIN_ENDPOINT`. diff --git a/api/v4/welcome/common-steps.md b/api/v4/welcome/common-steps.md index 015a7276..26a58297 100644 --- a/api/v4/welcome/common-steps.md +++ b/api/v4/welcome/common-steps.md @@ -17,31 +17,31 @@ You can use the `dotnet` CLI to [build and locally publish](https://learn.micros * Linux: `dotnet publish --framework net8.0 --runtime linux-x64` * macOS: `dotnet publish --framework net8.0 --runtime osx-x64` -> [!TIP] -> Since .NET Core 2.0, the `dotnet publish` command automatically runs NuGet package restore for you. Running `dotnet restore` explicitly is no longer required. +> [!NOTE] +> Since .NET Core 2.0, the `dotnet publish` command automatically runs the NuGet package restore for you. Running `dotnet restore` explicitly is no longer required. ## Cloud Foundry Push Sample -This section describes how to use the [Cloud Foundry CLI](https://docs.cloudfoundry.org/cf-cli/install-go-cli.html) to push the published application to Cloud Foundry by using the parameters that match what you selected for framework and runtime: +This section describes how to use the [Cloud Foundry CLI](https://docs.cloudfoundry.org/cf-cli/install-go-cli.html) to push the published application to Cloud Foundry using the parameters that match what you selected for framework and runtime: -```bash +```shell # Push to Linux cell cf push -f manifest.yml -p bin/Debug/net8.0/linux-x64/publish -# Push to Windows cell, .NET Core +# Push to Windows cell cf push -f manifest-windows.yml -p bin/Debug/net8.0/win-x64/publish ``` > [!NOTE] -> All sample manifests have been defined to bind their application to the services as created earlier. +> All samples contain manifest files to bind to the services they depend on. ### Observe the Logs To see the logs as you start the application, use `cf logs your-app-name`. -On a Linux cell, you should see output that resembles the following during startup: +On a Linux cell, you should see output similar to the following during startup: -```bash +```shell 2016-06-01T09:14:14.38-0600 [CELL/0] OUT Creating container 2016-06-01T09:14:15.93-0600 [CELL/0] OUT Successfully created container 2016-06-01T09:14:17.14-0600 [CELL/0] OUT Starting health monitoring of container @@ -52,7 +52,7 @@ On a Linux cell, you should see output that resembles the following during start 2016-06-01T09:14:21.41-0600 [CELL/0] OUT Container became healthy ``` -On Windows cells, you should see something slightly different with similar information. +On Windows cells, you see similar information in a slightly different format. ### Reading Configuration Values diff --git a/api/v4/welcome/index.md b/api/v4/welcome/index.md index 5246ed53..53b65b81 100644 --- a/api/v4/welcome/index.md +++ b/api/v4/welcome/index.md @@ -22,7 +22,7 @@ List the active loggers and change their minimum log levels at runtime. ## [Management](../management/index.md) -Monitor and manage your application while it runs in production via various HTTP endpoints. +Monitor and manage your application while it runs in production through various HTTP endpoints. ## [Network File Sharing](../fileshares/index.md) diff --git a/api/v4/welcome/prerequisites.md b/api/v4/welcome/prerequisites.md index cc5dce2d..3de42a15 100644 --- a/api/v4/welcome/prerequisites.md +++ b/api/v4/welcome/prerequisites.md @@ -2,14 +2,14 @@ While not required, we recommend installing one of the development tools ([Visual Studio](https://www.visualstudio.com/) or [Visual Studio Code](https://code.visualstudio.com/)) provided by Microsoft. -If you plan to develop with [.NET](https://learn.microsoft.com/dotnet/fundamentals) or [ASP.NET Core](https://learn.microsoft.com/aspnet/core), you will need to download and install the latest [.NET SDK](https://dotnet.microsoft.com/download). Additionally, if you do not already know the language and framework well, we recommend you first spend time working through some of the following tutorials from Microsoft: +If you plan to develop with [.NET](https://learn.microsoft.com/dotnet/fundamentals) or [ASP.NET Core](https://learn.microsoft.com/aspnet/core), you must download and install the latest [.NET SDK](https://dotnet.microsoft.com/download). Additionally, if you do not already know the language and framework well, we recommend you first spend time working through some of the following tutorials from Microsoft: * [Getting Started with C#](https://learn.microsoft.com/dotnet/csharp) * [Getting Started with ASP.NET Core](https://learn.microsoft.com/aspnet/core/getting-started) ## NuGet Feeds -When developing applications with Steeltoe, you need to pull the Steeltoe NuGet packages into your project. +When developing applications with Steeltoe, you must pull the Steeltoe NuGet packages into your project. To use the latest *unstable* packages from the developer feed, create a `Nuget.config` file with the contents below. diff --git a/api/v4/welcome/whats-new.md b/api/v4/welcome/whats-new.md index 2d60260f..8b2aa294 100644 --- a/api/v4/welcome/whats-new.md +++ b/api/v4/welcome/whats-new.md @@ -29,7 +29,7 @@ Steeltoe 4 requires .NET 8 or higher. - Compatible with recent versions of Tanzu Platform (Cloud Foundry and Kubernetes) and Spring Boot - Changes to align with .NET conventions and patterns, extensive review of the public API surface - Performance and scalability improvements -- Numerous bugfixes +- Numerous bug fixes - Cleanup of logging output - Substantially improved documentation - Improved test coverage, including interaction between different Steeltoe components @@ -39,11 +39,11 @@ Steeltoe 4 requires .NET 8 or higher. ### General - NuGet Packages - - Dropped the Core/Base suffix from package names, which was used to distinguish between NET Standard and .NET Core + - Dropped the Core/Base suffix from package names, which was used to distinguish between .NET Standard and .NET Core - Removed ".Extensions" from NuGet package names - Extension methods - Removed host builder extension methods that could be substituted with a single extension method on - `IServiceCollection`, `IConfiguration`, `IConfigurationBuilder`, `ILoggingBuilder` etc. + `IServiceCollection`, `IConfiguration`, `IConfigurationBuilder`, `ILoggingBuilder`, etc. Their redundancy led to confusion, and required Steeltoe to adapt each time a new host builder is introduced. - Added support for the new `IHostApplicationBuilder` (which `WebApplicationBuilder` and `HostApplicationBuilder` implement) to the remaining host builder extension methods - Moved extension methods to the appropriate Steeltoe namespaces to avoid clashes with other libraries @@ -52,14 +52,14 @@ Steeltoe 4 requires .NET 8 or higher. - Removed various interfaces that weren't general-purpose, types not designed for inheritance/reuse made internal - Changed methods containing optional parameters with default values to overloaded methods - Made more methods async and expanded usage of `CancellationToken`, both as a parameter and internally - - Enhanced method input validation to prevent downstream `NullReferenceException`s + - Enhanced method input validation to prevent downstream `NullReferenceException` exceptions - Applied C#/.NET naming conventions, for example: renamed `HealthStatus.OUT_OF_SERVICE` to `HealthStatus.OutOfService` - Configuration - Added support in Steeltoe packages for auto-completion in `appsettings.json` (without needing a schema reference, which currently only works in Visual Studio for SDK-style web projects), updated global Steeltoe JSON schema - Changed nearly all configuration settings to be reloadable without app restart, now more consistently exposed via ASP.NET Options pattern - Up-to-date - Extensively tested with the latest versions of dependent packages, database drivers and third-party products - (including Tanzu, Cloud Foundry, Config Server, Consul, Eureka, RabbitMQ, Redis, OpenTelemetry, Grafana, Prometheus, Zipkin, Spring Boot Admin) + (including Tanzu, Cloud Foundry, Config Server, Consul, Eureka, RabbitMQ, Redis/Valkey, OpenTelemetry, Grafana, Prometheus, Zipkin, Spring Boot Admin) - Refreshed dev-local Docker images for Config Server, Eureka, UAA and Spring Boot Admin - Steeltoe no longer depends on legacy technologies, such as binary serialization and Newtonsoft.Json @@ -141,9 +141,9 @@ The following sections provide details on the changes per Steeltoe component, as - Unified handling for all host builder types (there were omissions in some cases, due to duplicate code not kept in sync) - Added wire-up of Steeltoe.Configuration.SpringBoot, Steeltoe.Configuration.Encryption and Steeltoe.Logging.DynamicConsole -- Removed wire-up of client certificate authentication, which was done only partly +- Removed wire-up of client certificate authentication, which was only partly done - When no `ILoggerFactory` is specified, `BootstrapLoggerFactory` is used by default (pass `NullLoggerFactory.Instance` to disable) -- Ignore casing when comparing assembly names (bugfix) +- Ignore casing when comparing assembly names (bug fix) ### NuGet Package changes @@ -177,7 +177,7 @@ For more information, see the updated [Bootstrap documentation](../bootstrap/ind - Dynamically loading custom types for connectors and service discovery is no longer possible - Removed Spring Expression Language (SpEL) support - Removed `UseCloudHosting` (impossible to reliably detect bound ports in all cases, while Cloud Foundry usually [^1] sets the port automatically) -- Greater flexibility in using Bootstrap logger, bugfixes +- Greater flexibility in using Bootstrap logger, bug fixes - Certificates are no longer read from OS-specific store, which proved to not work reliably (store paths in configuration instead) ### NuGet Package changes @@ -185,8 +185,8 @@ For more information, see the updated [Bootstrap documentation](../bootstrap/ind | Source | Change | Replacement | Notes | | ---------------------------- | ------- | ---------------------------- | ---------------------------------------------------------- | | Steeltoe.Common.Abstractions | Moved | Steeltoe.Common package | | -| Steeltoe.Common.Certificates | Added | | Support for handling X509 certificates | -| Steeltoe.Common.Expression | Removed | None | Existed for SpEL support, which has been removed | +| Steeltoe.Common.Certificates | Added | | Support for handling X.509 certificates | +| Steeltoe.Common.Expression | Removed | None | Existed for Spring Extension Language (SpEL) support, which has been removed | | Steeltoe.Common.Kubernetes | Removed | None | | | Steeltoe.Common.Logging | Added | | Provides `BootstrapLoggerFactory` | | Steeltoe.Common.Retry | Removed | None | Existed for Messaging support, which has been removed | @@ -206,7 +206,7 @@ For more information, see the updated [Bootstrap documentation](../bootstrap/ind | `Steeltoe.Common.Availability.ReadinessHealthContributor` | Type | Steeltoe.Common [Abstractions] | Removed | None | Made internal | | `Steeltoe.Common.CasingConventions.EnumExtensions.ToSnakeCaseString` | Extension method | Steeltoe.Common | Added | | Use to convert between .NET and Java enum member naming styles | | `Steeltoe.Common.CasingConventions.SnakeCaseAllCapsEnumMemberJsonConverter` | Type | Steeltoe.Common | Added | | Use to convert between .NET and Java enum member naming styles | -| `Steeltoe.Common.ConcurrentDictionaryExtensions.GetOrAddEx` | Extension method | Steeltoe.Common [Abstractions] | Removed | None | Existed to support components which have been removed | +| `Steeltoe.Common.ConcurrentDictionaryExtensions.GetOrAddEx` | Extension method | Steeltoe.Common [Abstractions] | Removed | None | Existed to support components that have been removed | | `Steeltoe.Common.Configuration.ConfigurationValuesHelper` | Type | Steeltoe.Common [Abstractions] | Removed | None | Refactored to use ASP.NET Options pattern instead | | `Steeltoe.Common.Configuration.PropertyPlaceholderHelper` | Type | Steeltoe.Common [Abstractions] | Made internal | None | Placeholder substitution is handled in Steeltoe.Configuration.Placeholder package | | `Steeltoe.Common.Contexts` | Namespace | Steeltoe.Common [Abstractions] | Removed | None | Existed for SpEL support, which has been removed | @@ -236,16 +236,16 @@ For more information, see the updated [Bootstrap documentation](../bootstrap/ind | `Steeltoe.Common.Net.InetUtils` | Type | Steeltoe.Common [Abstractions] | Made internal | None | Internally used to resolve host names and IP addresses | | `Steeltoe.Common.Options.AbstractOptions` | Type | Steeltoe.Common [Abstractions] | Removed | None | Refactored to use ASP.NET Options pattern instead | | `Steeltoe.Common.Options.CertificateOptions` | Type | Steeltoe.Common [Abstractions] | Moved | Steeltoe.Common.Certificates package | | -| `Steeltoe.Common.Order` | Namespace | Steeltoe.Common [Abstractions] | Removed | None | Existed to support components which have been removed | +| `Steeltoe.Common.Order` | Namespace | Steeltoe.Common [Abstractions] | Removed | None | Existed to support components that have been removed | | `Steeltoe.Common.Platform.IsFullFramework` | Property | Steeltoe.Common [Abstractions] | Removed | None | Support for .NET Framework is no longer available | | `Steeltoe.Common.Platform.IsNetCore` | Property | Steeltoe.Common [Abstractions] | Removed | None | This enum member is no longer needed | | `Steeltoe.Common.Reflection` | Namespace | Steeltoe.Common [Abstractions] | Removed | None | Existed to support Type Locators, which have been replaced with internal-only shims | | `Steeltoe.Common.Retry` | Namespace | Steeltoe.Common [Abstractions] | Removed | None | Existed for Messaging support, which has been removed | | `Steeltoe.Common.SecurityUtilities` | Type | Steeltoe.Common [Abstractions] | Removed | None | Internally used to sanitize line breaks in logs | -| `Steeltoe.Common.Services` | Namespace | Steeltoe.Common [Abstractions] | Removed | None | Existed to support components which have been removed | +| `Steeltoe.Common.Services` | Namespace | Steeltoe.Common [Abstractions] | Removed | None | Existed to support components that have been removed | | `Steeltoe.Common.SteeltoeComponent` | Type | Steeltoe.Common [Abstractions] | Removed | None | This enum is no longer needed | | `Steeltoe.Common.Transaction` | Namespace | Steeltoe.Common [Abstractions] | Removed | None | Existed for Messaging support, which has been removed | -| `Steeltoe.Common.Util` | Namespace | Steeltoe.Common [Abstractions] | Removed | None | Existed to support components which have been removed | +| `Steeltoe.Common.Util` | Namespace | Steeltoe.Common [Abstractions] | Removed | None | Existed to support components that have been removed | | `Steeltoe.Common.Certificates.CertificateConfigurationExtensions.AddAppInstanceIdentityCertificate` | Extension method | Steeltoe.Common.Certificates | Added | | Register/generate identity certificate for Cloud Foundry authentication | | `Steeltoe.Common.Certificates.CertificateOptions` | Type | Steeltoe.Common.Certificates | Added | | Provides access to loaded certificate using ASP.NET Options pattern | | `Steeltoe.Common.Certificates.CertificateServiceCollectionExtensions.ConfigureCertificateOptions` | Extension method | Steeltoe.Common.Certificates | Added | | Bind named certificate from `IConfiguration` and monitor for changes | @@ -267,7 +267,7 @@ For more information, see the updated [Bootstrap documentation](../bootstrap/ind | `Steeltoe.Common.Http.Serialization.BoolStringJsonConverter` | Type | Steeltoe.Common.Http | Removed | None | Made internal, moved to Steeltoe.Discovery.Eureka package | | `Steeltoe.Common.Http.Serialization.LongStringJsonConverter` | Type | Steeltoe.Common.Http | Removed | None | Made internal, moved to Steeltoe.Discovery.Eureka package | | `Steeltoe.Common.Logging.BootstrapLoggerFactory` | Type | Steeltoe.Common.Logging | Added | | Writes startup logs to console before logging has initialized | -| `Steeltoe.Common.Logging.BootstrapLoggerServiceCollectionExtensions.UpgradeBootstrapLoggerFactory` | Extension method | Steeltoe.Common.Logging | Added | | Upgrades existing loggers once app has started | +| `Steeltoe.Common.Logging.BootstrapLoggerServiceCollectionExtensions.UpgradeBootstrapLoggerFactory` | Extension method | Steeltoe.Common.Logging | Added | | Upgrades existing loggers after app has started | | `Steeltoe.Common.Net.IMPR` | Type | Steeltoe.Common.Net | Removed | None | Renamed to internal type `IMultipleProviderRouter` (existed for testing only) | | `Steeltoe.Common.Net.WindowsNetworkFileShare.GetLastError` | Method | Steeltoe.Common.Net | Removed | None | Now throws `IOException` on error | | `Steeltoe.Common.Net.WindowsNetworkFileShare.NetResource` | Type | Steeltoe.Common.Net | Removed | None | Nested type used internally for P/Invoke, should not be public | @@ -454,9 +454,9 @@ For more information, see the updated [Configuration documentation](../configura - ADO.NET API: `builder.Add*()`, inject `ConnectorFactory` (driver-specific connection/client instances are no longer registered) - EF Core API: must call `builder.Add*()` first. Example: `builder.AddMySql(); builder.Services.AddDbContext((serviceProvider, options) => options.UseMySql(serviceProvider));` - The structure of configuration has changed severely to accommodate multiple named service bindings in a unified way -- Compatible with the latest versions of Tanzu, Cloud Foundry and .NET database drivers -- Added [Cloud Native Binding](https://github.com/servicebinding/spec) support (used by Tanzu Platform for Kubernetes, formerly TAP) for MongoDB, MySQL, PostgreSQL, RabbitMQ and Redis -- Leverage .NET connection strings (agnostic to the driver-specific parameters) via +- Compatible with the latest versions of Tanzu, Cloud Foundry, and .NET database drivers +- Added [Cloud Native Binding](https://github.com/servicebinding/spec) support (used by Tanzu Application Platform and Tanzu Platform for Kubernetes) for MongoDB, MySQL, PostgreSQL, RabbitMQ, and Redis/Valkey +- Leverage .NET connection strings (agnostic to the driver-specific parameters) using [ASP.NET Options pattern](https://learn.microsoft.com/aspnet/core/fundamentals/configuration/options) - Connection string from appsettings.json is preserved, replacing parameters from cloud bindings - No more defaults for missing connection parameters that are required by drivers @@ -577,7 +577,7 @@ For more information, see the updated [Configuration documentation](../configura | `Steeltoe.Connectors.RabbitMQ.RabbitMQOptions` | Type | Steeltoe.Connectors | Added | | Provides connection string | | `Steeltoe.Connectors.RabbitMQ.RabbitMQServiceCollectionExtensions.AddRabbitMQ` | Extension method | Steeltoe.Connectors | Added | | To support legacy host builders | | `Steeltoe.Connectors.Redis.RedisConfigurationBuilderExtensions.ConfigureRedis` | Extension method | Steeltoe.Connectors | Added | | To support legacy host builders | -| `Steeltoe.Connectors.Redis.RedisHostApplicationBuilderExtensions.AddRedis` | Extension method | Steeltoe.Connectors | Added | | Activates the Redis connector | +| `Steeltoe.Connectors.Redis.RedisHostApplicationBuilderExtensions.AddRedis` | Extension method | Steeltoe.Connectors | Added | | Activates the Redis/Valkey connector | | `Steeltoe.Connectors.Redis.RedisOptions` | Type | Steeltoe.Connectors | Added | | Provides connection string | | `Steeltoe.Connectors.Redis.RedisServiceCollectionExtensions.AddRedis` | Extension method | Steeltoe.Connectors | Added | | To support legacy host builders | | `Steeltoe.Connectors.SqlServer.SqlServerConfigurationBuilderExtensions.ConfigureSqlServer` | Extension method | Steeltoe.Connectors | Added | | To support legacy host builders | @@ -622,12 +622,12 @@ For more information, see the updated [Connectors documentation](../configuratio ### Behavior changes - Multiple discovery clients (one per type) can be active -- Simplified API: Use `IServiceCollection.Add*DiscoveryClient()` to register, `IHttpClientBuilder.AddServiceDiscovery()` to consume +- Simplified API: Use `IServiceCollection.Add*DiscoveryClient()` to register; `IHttpClientBuilder.AddServiceDiscovery()` to consume - Refactored configuration to use ASP.NET Options pattern, responding to changes at runtime nearly everywhere - Async all-the-way where possible - More reliable cross-platform detection of local hostname and IP address - Now supports global service discovery: `services.ConfigureHttpClientDefaults(builder => builder.AddServiceDiscovery())` -- Config Server discovery-first can now query Consul, Eureka and Configuration-based +- Config Server discovery-first can now query Consul, Eureka, and Configuration-based - Improved detection of port bindings, including support for new ASP.NET [environment variables](https://learn.microsoft.com/aspnet/core/release-notes/aspnetcore-8.0#http_ports-and-https_ports-config-keys) - HTTP handlers now depend on a load balancer, which delegates to multiple discovery clients - Major improvements in documentation, samples cover more use cases @@ -788,8 +788,8 @@ For more information, see the updated [Connectors documentation](../configuratio | `Steeltoe.Discovery.Eureka.EurekaApplicationInfoManager.UpdateInstance` | Method | Steeltoe.Discovery.Eureka | Added | | Enables to change local instance from code (synced with configuration) | | `Steeltoe.Discovery.Eureka.EurekaClientConfig` | Type | Steeltoe.Discovery.Eureka | Removed | `Steeltoe.Discovery.Eureka.Configuration.EurekaClientOptions` | | | `Steeltoe.Discovery.Eureka.EurekaClientConfig.EurekaServerConnectTimeoutSeconds` | Property | Steeltoe.Discovery.Eureka | Removed | `EurekaClientOptions.Server.ConnectTimeoutSeconds` | | -| `Steeltoe.Discovery.Eureka.EurekaClientConfig.EurekaServerRetryCount` | Property | Steeltoe.Discovery.Eureka | Removed | `EurekaClientOptions.Server.RetryCount` | Default changed from 3 attempts to 2 retries (bugfix) | -| `Steeltoe.Discovery.Eureka.EurekaClientConfig.EurekaServerServiceUrls` | Property | Steeltoe.Discovery.Eureka | Removed | `EurekaClientOptions.EurekaServerServiceUrls` | Now supports comma-delimited list of URLs | +| `Steeltoe.Discovery.Eureka.EurekaClientConfig.EurekaServerRetryCount` | Property | Steeltoe.Discovery.Eureka | Removed | `EurekaClientOptions.Server.RetryCount` | Default changed from 3 attempts to 2 retries (bug fix) | +| `Steeltoe.Discovery.Eureka.EurekaClientConfig.EurekaServerServiceUrls` | Property | Steeltoe.Discovery.Eureka | Removed | `EurekaClientOptions.EurekaServerServiceUrls` | Now supports comma-separated list of URLs | | `Steeltoe.Discovery.Eureka.EurekaClientConfig.HealthCheckEnabled` | Property | Steeltoe.Discovery.Eureka | Removed | `EurekaClientOptions.Health.CheckEnabled` | | | `Steeltoe.Discovery.Eureka.EurekaClientConfig.HealthContribEnabled` | Property | Steeltoe.Discovery.Eureka | Removed | `EurekaClientOptions.Health.ContributorEnabled` | | | `Steeltoe.Discovery.Eureka.EurekaClientConfig.HealthMonitoredApps` | Property | Steeltoe.Discovery.Eureka | Removed | `EurekaClientOptions.Health.MonitoredApps` | | @@ -976,16 +976,16 @@ For more information, see the updated [Logging documentation](../logging/index.m - Cleaner extensibility model for third-party actuators - Fail at startup when actuators are used on Cloud Foundry without security - Improved security and redaction of sensitive data in responses and logs -- Actuators can be turned on/off or bound to different verbs at runtime via configuration -- Simplified content negotiation, updated all actuators to support latest Spring media type +- Actuators can be turned on/off or bound to different verbs at runtime using configuration +- Simplified content negotiation; updated all actuators to support latest Spring media type - New actuator `/beans` that lists the contents of the .NET dependency container, including support for keyed services -- Update health checks and actuator to align with latest Spring, hide details by default, contributors can be turned on/off at runtime via configuration -- Update `/mappings` actuator to include endpoints from Minimal APIs, Razor Pages and Blazor, with richer metadata and improved compatibility with Spring +- Update health checks and actuator to align with latest Spring; hide details by default; contributors can be turned on/off at runtime using configuration +- Update `/mappings` actuator to include endpoints from Minimal APIs, Razor Pages, and Blazor, with richer metadata and improved compatibility with Spring - Heap dumps are enabled by default in Cloud Foundry on Linux - Improved Prometheus exporter that works with latest OpenTelemetry - Various fixes for interoperability with latest Spring Boot Admin -- Unified `/traces` and `/httptraces` actuators to `/httpexchanges` to align with latest Spring -- WaveFront, Zipkin and Jaeger support was removed (use OpenTelemetry directly) +- Unified `/traces` and `/httptraces` actuators to `/httpexchanges`, to align with latest Spring +- WaveFront, Zipkin, and Jaeger support was removed (use OpenTelemetry directly) - Metrics endpoint was removed (use OpenTelemetry directly) - Kubernetes actuator was removed @@ -1009,7 +1009,7 @@ For more information, see the updated [Logging documentation](../logging/index.m | Source | Kind | Package | Change | Replacement | Notes | | ---------------------------------------------------------------------------------------------------------------------------- | ---------------- | ---------------------------------------- | ------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | | `Microsoft.Diagnostics.Runtime.Interop.IMAGE_FILE_MACHINE` | Type | Steeltoe.Management.Diagnostics | Removed | None | | -| `Microsoft.Extensions.DependencyInjection.ServiceCollectionExtensions.AddActuatorEndpointMapping` | Extension method | Steeltoe.Management.Endpoint [Base/Core] | Removed | `Steeltoe.Management.Endpoint.ApplicationBuilderExtensions.UseActuatorEndpoints` | Only needed when setting up middleware manually | +| `Microsoft.Extensions.DependencyInjection.ServiceCollectionExtensions.AddActuatorEndpointMapping` | Extension method | Steeltoe.Management.Endpoint [Base/Core] | Removed | `Steeltoe.Management.Endpoint.ApplicationBuilderExtensions.UseActuatorEndpoints` | Needed only when setting up middleware manually | | `Microsoft.Extensions.DependencyInjection.ServiceCollectionExtensions.AddCloudFoundryActuatorServices` | Extension method | Steeltoe.Management.Endpoint [Base/Core] | Moved | `builder.Services.AddCloudFoundryActuator()` | | | `Microsoft.Extensions.DependencyInjection.ServiceCollectionExtensions.AddDbMigrationsActuatorServices` | Extension method | Steeltoe.Management.Endpoint [Base/Core] | Moved | `builder.Services.AddDbMigrationsActuator()` | | | `Microsoft.Extensions.DependencyInjection.ServiceCollectionExtensions.AddEnvActuatorServices` | Extension method | Steeltoe.Management.Endpoint [Base/Core] | Moved | `builder.Services.AddEnvironmentActuator()` | | @@ -1066,10 +1066,10 @@ For more information, see the updated [Logging documentation](../logging/index.m | `Steeltoe.Management.Endpoint.Actuators.Health.Availability.AvailabilityEventArgs` | Type | Steeltoe.Management.Endpoint | Added | | Moved from Steeltoe.Common package | | `Steeltoe.Management.Endpoint.Actuators.Health.Availability.AvailabilityState` | Type | Steeltoe.Management.Endpoint | Added | | Moved from Steeltoe.Common package | | `Steeltoe.Management.Endpoint.Actuators.Health.Availability.LivenessState` | Type | Steeltoe.Management.Endpoint | Added | | Moved from Steeltoe.Common package | -| `Steeltoe.Management.Endpoint.Actuators.Health.Availability.LivenessStateContributorOptions.Enabled` | Property | Steeltoe.Management.Endpoint | Added | | Enables to turn off via configuration | +| `Steeltoe.Management.Endpoint.Actuators.Health.Availability.LivenessStateContributorOptions.Enabled` | Property | Steeltoe.Management.Endpoint | Added | | Enables turning off via configuration | | `Steeltoe.Management.Endpoint.Actuators.Health.Availability.ReadinessState` | Type | Steeltoe.Management.Endpoint | Added | | Moved from Steeltoe.Common package | -| `Steeltoe.Management.Endpoint.Actuators.Health.Availability.ReadinessStateContributorOptions.Enabled` | Property | Steeltoe.Management.Endpoint | Added | | Enables to turn off via configuration | -| `Steeltoe.Management.Endpoint.Actuators.Health.Contributors.DiskSpaceContributorOptions.Enabled` | Property | Steeltoe.Management.Endpoint | Added | | Enables to turn off via configuration | +| `Steeltoe.Management.Endpoint.Actuators.Health.Availability.ReadinessStateContributorOptions.Enabled` | Property | Steeltoe.Management.Endpoint | Added | | Enables turning off via configuration | +| `Steeltoe.Management.Endpoint.Actuators.Health.Contributors.DiskSpaceContributorOptions.Enabled` | Property | Steeltoe.Management.Endpoint | Added | | Enables turning off via configuration | | `Steeltoe.Management.Endpoint.Actuators.Health.HealthEndpointOptions.ShowComponents` | Property | Steeltoe.Management.Endpoint | Added | | Whether to show/hide contributors in response | | `Steeltoe.Management.Endpoint.Actuators.Health.HealthEndpointRequest` | Type | Steeltoe.Management.Endpoint | Added | | Data about incoming actuator request | | `Steeltoe.Management.Endpoint.Actuators.Health.HealthEndpointResponse.Components` | Property | Steeltoe.Management.Endpoint | Added | | List of health contributors in response | @@ -1113,8 +1113,8 @@ For more information, see the updated [Logging documentation](../logging/index.m | `Steeltoe.Management.Endpoint.ActuatorServiceCollectionExtensions.AddAllActuators` | Extension method | Steeltoe.Management.Endpoint [Base/Core] | Moved | `Steeltoe.Management.Endpoint.Actuators.All.EndpointServiceCollectionExtensions.AddAllActuators` | For custom CORS, call `services.ConfigureActuatorsCorsPolicy()` | | `Steeltoe.Management.Endpoint.ActuatorServiceCollectionExtensions.RegisterEndpointOptions` | Extension method | Steeltoe.Management.Endpoint [Base/Core] | Removed | None | Redundant | | `Steeltoe.Management.Endpoint.AllActuatorsStartupFilter` | Type | Steeltoe.Management.Endpoint [Base/Core] | Removed | None | Moved to internal type `ConfigureActuatorsMiddlewareStartupFilter` | -| `Steeltoe.Management.Endpoint.ApplicationBuilderExtensions.UseActuatorsCorsPolicy` | Extension method | Steeltoe.Management.Endpoint | Added | | Only needed when setting up middleware manually | -| `Steeltoe.Management.Endpoint.ApplicationBuilderExtensions.UseManagementPort` | Extension method | Steeltoe.Management.Endpoint | Added | | Only needed when setting up middleware manually | +| `Steeltoe.Management.Endpoint.ApplicationBuilderExtensions.UseActuatorsCorsPolicy` | Extension method | Steeltoe.Management.Endpoint | Added | | Needed only when setting up middleware manually | +| `Steeltoe.Management.Endpoint.ApplicationBuilderExtensions.UseManagementPort` | Extension method | Steeltoe.Management.Endpoint | Added | | Needed only when setting up middleware manually | | `Steeltoe.Management.Endpoint.CloudFoundry` | Namespace | Steeltoe.Management.Endpoint [Base/Core] | Moved | `Steeltoe.Management.Endpoint.Actuators.CloudFoundry` | | | `Steeltoe.Management.Endpoint.CloudFoundry.CloudFoundryActuatorStartupFilter` | Type | Steeltoe.Management.Endpoint [Base/Core] | Removed | `builder.Services.AddCloudFoundryActuator()` | Redundant | | `Steeltoe.Management.Endpoint.CloudFoundry.CloudFoundryEndpoint` | Type | Steeltoe.Management.Endpoint [Base/Core] | Removed | `ICloudFoundryEndpointHandler` | Moved to internal type `CloudFoundryEndpointHandler` | diff --git a/examples.md b/examples.md index 204b516c..0d0d9f73 100644 --- a/examples.md +++ b/examples.md @@ -5,13 +5,19 @@ title: Example markdown # These are example markdown items > [!NOTE] -> This is a note - -> [!WARNING] -> This is a warning +> Information the user should notice even if skimming. > [!TIP] -> This is a tip +> Optional information to help a user be more successful. + +> [!IMPORTANT] +> Essential information required for user success. + +> [!CAUTION] +> Negative potential consequences of an action. + +> [!WARNING] +> Dangerous certain consequences of an action. ## Sectioned code