Skip to content

Commit

Permalink
Update Learning Paths (#6754)
Browse files Browse the repository at this point in the history
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
  • Loading branch information
github-actions[bot] authored Jun 7, 2024
1 parent 834c5e9 commit 7e3f9d7
Show file tree
Hide file tree
Showing 7 changed files with 69 additions and 69 deletions.
2 changes: 1 addition & 1 deletion .github/learning-path-sha.txt
Original file line number Diff line number Diff line change
@@ -1 +1 @@
8e99fe93461686b50ea276b406c5046b252b05e4
3c31273c42196ec0813b7b5b947ab8e1bd1801ac
2 changes: 1 addition & 1 deletion documentation/learningPath/aks.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ In addition to its availability as a .NET CLI tool, the `dotnet monitor` tool is

This workflow takes your local development copy of `dotnet-monitor`, patches it with a local development copy of the [.NET Core Diagnostics Repo](https://github.com/dotnet/diagnostics#net-core-diagnostics-repo), and makes it available as an image for you to consume in an ACR (Azure Container Registry). Note that there are many other ways to do this - this is meant to serve as a basic template that can be adapted to match your needs.

1. Open `pwsh` and run the [generate-dev-sln script](https://github.com/dotnet/dotnet-monitor/blob/8e99fe93461686b50ea276b406c5046b252b05e4/generate-dev-sln.ps1), providing a path to your local copy of the diagnostics repo.
1. Open `pwsh` and run the [generate-dev-sln script](https://github.com/dotnet/dotnet-monitor/blob/3c31273c42196ec0813b7b5b947ab8e1bd1801ac/generate-dev-sln.ps1), providing a path to your local copy of the diagnostics repo.

> [!NOTE]
> If your changes do not involve the [.NET Core Diagnostics Repo](https://github.com/dotnet/diagnostics#net-core-diagnostics-repo), you don't need to complete this step.
Expand Down
10 changes: 5 additions & 5 deletions documentation/learningPath/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,15 +7,15 @@ dotnet-monitor exposes functionality through both [collection rules](./collectio

## Adding New APIs

The web API surface is defined by a series of controllers [here](https://github.com/dotnet/dotnet-monitor/blob/8e99fe93461686b50ea276b406c5046b252b05e4/src/Microsoft.Diagnostics.Monitoring.WebApi/Controllers/). It's common for an API to expose functionality also available via [Actions](./collectionrules.md#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](#notable-controller-attributes).
The web API surface is defined by a series of controllers [here](https://github.com/dotnet/dotnet-monitor/blob/3c31273c42196ec0813b7b5b947ab8e1bd1801ac/src/Microsoft.Diagnostics.Monitoring.WebApi/Controllers/). It's common for an API to expose functionality also available via [Actions](./collectionrules.md#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](#notable-controller-attributes).

If the new API needs to either accept or return structured data, a dedicated model should be used. Models are defined [here](https://github.com/dotnet/dotnet-monitor/blob/8e99fe93461686b50ea276b406c5046b252b05e4/src/Microsoft.Diagnostics.Monitoring.WebApi/Models/).
If the new API needs to either accept or return structured data, a dedicated model should be used. Models are defined [here](https://github.com/dotnet/dotnet-monitor/blob/3c31273c42196ec0813b7b5b947ab8e1bd1801ac/src/Microsoft.Diagnostics.Monitoring.WebApi/Models/).

When adding a new API, it's important to also update the [`openapi.json`](../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](./testing.md#openapi-generation).

### Adding Tests

Web APIs in dotnet-monitor are typically tested using functional tests that leverage the [ApiClient](https://github.com/dotnet/dotnet-monitor/blob/8e99fe93461686b50ea276b406c5046b252b05e4/src/Tests/Microsoft.Diagnostics.Monitoring.Tool.FunctionalTests/HttpApi/ApiClient.cs) to call a specific API. Learn more about how the functional tests are defined and operate [here](./testing.md#functional-tests).
Web APIs in dotnet-monitor are typically tested using functional tests that leverage the [ApiClient](https://github.com/dotnet/dotnet-monitor/blob/3c31273c42196ec0813b7b5b947ab8e1bd1801ac/src/Tests/Microsoft.Diagnostics.Monitoring.Tool.FunctionalTests/HttpApi/ApiClient.cs) to call a specific API. Learn more about how the functional tests are defined and operate [here](./testing.md#functional-tests).

## Notable Controller Attributes

Expand All @@ -35,6 +35,6 @@ dotnet-monitor supports multiple different [authentication modes](../authenticat

### Determining Authentication Mode

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](https://github.com/dotnet/dotnet-monitor/blob/8e99fe93461686b50ea276b406c5046b252b05e4/src/Tools/dotnet-monitor/Commands/CollectCommandHandler.cs#L28). 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.
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](https://github.com/dotnet/dotnet-monitor/blob/3c31273c42196ec0813b7b5b947ab8e1bd1801ac/src/Tools/dotnet-monitor/Commands/CollectCommandHandler.cs#L28). 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](https://github.com/dotnet/dotnet-monitor/blob/8e99fe93461686b50ea276b406c5046b252b05e4/src/Tools/dotnet-monitor/Auth/IAuthenticationConfigurator.cs) is created by the [AuthConfiguratorFactory](https://github.com/dotnet/dotnet-monitor/blob/8e99fe93461686b50ea276b406c5046b252b05e4/src/Tools/dotnet-monitor/Auth/AuthConfiguratorFactory.cs). 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.
After determining the `StartupAuthenticationMode` mode, the relevant [IAuthenticationConfigurator](https://github.com/dotnet/dotnet-monitor/blob/3c31273c42196ec0813b7b5b947ab8e1bd1801ac/src/Tools/dotnet-monitor/Auth/IAuthenticationConfigurator.cs) is created by the [AuthConfiguratorFactory](https://github.com/dotnet/dotnet-monitor/blob/3c31273c42196ec0813b7b5b947ab8e1bd1801ac/src/Tools/dotnet-monitor/Auth/AuthConfiguratorFactory.cs). 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.
Loading

0 comments on commit 7e3f9d7

Please sign in to comment.