RouteCheck 0.3.1
dotnet tool install --global RouteCheck --version 0.3.1
dotnet new tool-manifest
dotnet tool install --local RouteCheck --version 0.3.1
#tool dotnet:?package=RouteCheck&version=0.3.1
nuke :add-package RouteCheck --version 0.3.1
RouteCheck
Check your API routes in your Terminal.
RouteCheck is a dotnet tool for checking/viewing the routes of your ASP.NET Core app in your terminal, like php artisan route:list or mix phx.routes. The check command (default) shows you all routes in a nice table: minimal APIs, controllers, Razor Pages and everything else that is mapped as an endpoint, together with the handler of each route.
RouteCheck works with ASP.NET Core apps on .NET 8 or later. No OpenAPI package or other changes to your app are needed.
Installation
You can install RouteCheck as a dotnet tool via NuGet:
# Install
dotnet tool install --global RouteCheck
# Update
dotnet tool update --global RouteCheck
Usage
In your terminal cd into a ASP.NET project and run:
routecheck
This should give you something like this:
Method Path Handler Auth
ANY / Page /Index Anonymous
GET /api/orders OrdersController.List Authenticated
GET /api/orders/{id:int} OrdersController.Get Authenticated
PUT /api/orders/{id:int} OrdersController.Update Roles: admin, editor
GET /health Health.Check Anonymous
ANY /Orders/Details/{id:int} Page /Orders/Details Policy: Customer
GET /pets Program (lambda) Authenticated (fallback)
ANYmeans the route accepts every HTTP method, like Razor Pages do.- Auth shows who may request the route:
Anonymous(anyone), or what is required, e.g.Authenticated,Policy: Customer,Roles: admin, editororClaim: scope=pets:write.(fallback)means the route has no authorization of its own, so the fallback policy applies. Global MVC filters (AuthorizeFilter) are included. The column is left out if anyone may request every route. Note that authorization is only enforced if your app callsUseAuthorization(). - For minimal APIs, the handler is the method passed to
MapGetetc. A lambda is shown as(lambda)with the class it is declared in. - Controllers with conventional routes (
MapControllerRoute) are shown with one row per action and their controller and action filled in, e.g./Home/About/{id?}. Shorter URLs from route defaults, like/forHomeController.Index, are not listed separately.
To see more about each route, use --verbose. It adds the route's name (e.g. of WithName), its tags, the content types of the request body it accepts and its responses (status codes and content types), as far as the app declares them:
routecheck --verbose
RouteCheck looks for a project file (*.csproj, *.fsproj or *.vbproj) in the current directory. If there is none, but a solution (*.sln or *.slnx), it uses the solution's web project (Microsoft.NET.Sdk.Web), so you can run it from the root of your repository too.
You can also provide a path to the web app's directory, project file or solution via the path option:
routecheck --path /absolute/path/to/webapp
# or
routecheck -p relative/path/to/webapp/WebApp.csproj
RouteCheck waits 20 seconds for your app to start (after building it). If your app needs longer, e.g. because it runs migrations on startup, set the timeout option:
routecheck --timeout 60
If your app targets multiple frameworks, choose the one to build and run with the framework option:
routecheck --framework net9.0
Routes can differ by environment, so you can choose it, as well as the build configuration and the launch profile:
# Development, unless set by the launch profile or ASPNETCORE_ENVIRONMENT
routecheck -e Staging
# Debug by default
routecheck -c Release
# The first profile in Properties/launchSettings.json by default
routecheck --launch-profile https
The environment option wins over the launch profile. It is passed to the app as --environment too, which WebApplication.CreateBuilder(args) reads.
In a CI job that built the app already, skip the build with --no-build (with the same configuration and framework).
Filter routes
The routes are sorted by path, and routes with the same path by method. To show only routes with certain HTTP methods, use the method option. It can be used multiple times or with comma-separated values:
routecheck --method GET -m post
# or
routecheck -m get,post
To show only routes whose path contains a text, use the filter option. With a wildcard (* or %), the pattern has to match the whole path. It can be used multiple times, a route has to match one of them:
# /pets, /pets/{id}, /users/{id}/pets, ...
routecheck --filter pets
# /pets, /pets/{id}, but not /users/{id}/pets
routecheck -f "/pets*"
To show only routes of certain handlers, use the handler option. To leave out routes, e.g. of the framework, use the exclude option. Both match like filter, exclude against the path:
# The routes of OrdersController
routecheck --handler "OrdersController.*"
# Without Blazor's routes
routecheck -x "/_framework/*" -x "/_blazor*"
Matching is case-insensitive, like ASP.NET Core routing. All filters can be combined. Routes accepting any method (ANY) are shown for every method.
To review which routes are public, show only the routes anyone may request with --anonymous:
routecheck --anonymous
Problems
Below the routes, RouteCheck lists problems with them. For now, these are ambiguous routes: routes with the same method that match the same requests, e.g. GET /pets/{id} and GET /pets/{name}. ASP.NET Core can't choose between them, so requesting them fails with an AmbiguousMatchException, but only at runtime. Routes whose parameters have different constraints (/pets/{id:int}), hosts, accepted content types or orders don't clash.
To fail a CI job on problems, use --strict. The exit code is then 2 if there are problems, while errors still exit with 1:
routecheck --strict
Compare with a baseline
To see how a change affects your routes, e.g. in a pull request, save the routes as a baseline and compare with it later:
routecheck --output json > routes.json
# Later: shows the added, removed and changed routes (handler or auth)
routecheck --baseline routes.json
Routes are compared by method and path. method, filter and the other filters apply to the baseline too. With --strict, the exit code is 2 if routes of the baseline were removed, as requesting them now fails. You can commit the baseline and update it together with your routes.
Output for scripts and LLM agents
With --output json or --output markdown, RouteCheck prints only the result, as one document: no status lines and no update notice.
routecheck --output json
{
"command": "check",
"project": "src/Api/Api.csproj",
"routes": [
{
"method": "GET",
"path": "/pets",
"handler": "PetsController.List",
"auth": "Anonymous"
}
],
"problems": [],
"error": null
}
projectis the project file relative to the current directory.handlerisnullif RouteCheck can't tell what handles the route.- With
--verbose, routes also havename,tags,acceptsandproduces, if the app declares them. problemslists the problems, each with atype(e.g.ambiguous-routes), amessageand itsroutes.- With
--baseline,baselinecontains theadded,removedandchangedroutes (each change withbefore,afterand adescription). Otherwise it isnull. - On an error,
errorcontains the message and the exit code is1. Otherwiseerrorisnulland the exit code is0. --output markdownprints the same as a Markdown table, e.g. for pull request comments or job summaries.
How it works
RouteCheck builds your app and starts it with dotnet run, adding a startup hook that replaces the web server. Once the app has mapped its endpoints, the hook reads them from ASP.NET Core's routing and stops the app again. So your app never listens on a port, and nothing has to be added to it.
- Hosted services (e.g. a
BackgroundServiceconsuming a queue) are not started, so they can't do any work while RouteCheck reads the routes. - The rest of your app's startup code runs as usual, e.g. database migrations before
app.Run(). - The app is started with the environment
Development, unless your launch profile or theASPNETCORE_ENVIRONMENTenvironment variable sets another one. - Startup hooks your app already uses (
DOTNET_STARTUP_HOOKS) are kept.
For help run:
routecheck -h
LICENSE
MIT
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 is compatible. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. net11.0 is compatible. |
This package has no dependencies.