Was this documentation helpful? Share feedback
dotnet-monitor exposes functionality through both collection rules and a web API surface. The web api is built using ASP.NET Core and enables on-demand extraction of diagnostic information and artifacts from discoverable processes.
The web API surface is defined by a series of controllers here. It's common for an API to expose functionality also available via Actions and so methods in these controllers are often wrappers around a shared implementation. Each controller may have one or more attributes that configure how and where it is exposed, you can learn more about the notable controller attributes here.
If the new API needs to either accept or return structured data, a dedicated model should be used. Models are defined here.
When adding a new API, it's important to also update the openapi.json spec which describes the API surface. There are CI tests that will ensure this file has been updated to reflect any API changes. Learn more about updating openapi.json here.
Web APIs in dotnet-monitor are typically tested using functional tests that leverage the ApiClient to call a specific API. Learn more about how the functional tests are defined and operate here.
Controllers with [Authorize(Policy = AuthConstants.PolicyName)] class attribute will require authentication on all routes defined within. Learn more about how Authentication is handled here.
In addition to the default URLs that dotnet-monitor will accept API requests on, there are also metrics urls which do not require any authentication and are generally considered safe to expose as they don't serve any sensitive data (unless explicitly configured so by the user). Learn more about the metrics urls here.
If an API may potentially serve sensitive data, such as logs or dumps, then it must be in a controller with the [HostRestriction] attribute to avoid exposing it on the unauthenticated metrics urls.
dotnet-monitor supports multiple different authentication modes that can be configured by the user. Authentication will be required on any route belonging to a controller with the [Authorize(Policy = AuthConstants.PolicyName)] class attribute.
When dotnet-monitor starts, the command line arguments are first inspected to see if a specific authentication mode was set (such as --no-auth), referred to as the StartupAuthenticationMode, this is calculated here. If no modes were explicitly set via a command line argument, dotnet-monitor will select Deferred as the StartupAuthenticationMode. This indicates that the user configuration should be looked at to determine the authentication mode later on in the startup process.
After determining the StartupAuthenticationMode mode, the relevant IAuthenticationConfigurator is created by the AuthConfiguratorFactory. This factory also handles deciding what authentication mode to use when StartupAuthenticationMode is Deferred. The selected configurator is used to configure various parts of dotnet-monitor that are specific to authentication, such as protecting the web APIs and adding authentication-mode specific logging.