Cross-Host Route Ownership Analysis
In a side-by-side migration two hosts are live at once. The new ASP.NET Core host takes
the request first, serves what it has already migrated, and forwards the rest through YARP
to the still-running .NET Framework app. The question that governs every wave is which
URLs are on which side — and it cannot be answered by reading either project alone,
because the answer lives in the relationship between three things: the Framework route
table, the Core endpoint table, and the proxy configuration.
This skill covers reading that answer. It does not migrate routes
(migrating-mvc-routing) and does not create the proxy
(scaffolding-yarp-proxy-project).
This adds a machine-readable inventory and ownership/conflict analysis to the prose
baseline in migrating-aspnet-framework-to-core/side-by-side.md. Keep that baseline
for runtime comparison; the report does not replace it.
The analyzer supports C# projects only. Both inputs must be .csproj files. Visual Basic
and other project languages are not supported; do not interpret an unsupported project
as having no routes. Projects must be loadable through the current workspace. An unloaded
proxy is reported as unreadable, not scanned by guessing which files belong to it.
Get the answer from the tool, not by reading route files
analyze_route_ownership(
projectPath="{full path to the .NET Framework .csproj}",
proxyProjectPath="{full path to the ASP.NET Core .csproj}"
)
Both paths must be absolute. proxyProjectPath is optional and omitting it changes the
question being asked: without it you get an inventory of the Framework routes with every
answer that depends on Core coverage reported as unknown — useful before the Core host
exists and misleading afterwards. Supply it whenever the Core host exists.
Do not answer ownership questions by reading RouteConfig.cs and Program.cs yourself.
Route templates that look equivalent frequently are not, and the differences are not
visible in the strings:
- A Framework route with
defaults: new { action = "Index" } serves the bare prefix
/packages. A Core route written packages/{action}/{id?} does not. The templates read
almost identically and cover different URL sets.
IgnoreRoute installs a StopRoutingHandler. It looks like a registered route, but it means
Framework routing serves nothing there — not that nothing does: an IIS handler (*.axd) may.
- A route registered inside
if (config.EnableFeature) may or may not exist at runtime,
and the source does not say which.
- MVC and Web API/OData use separate ordering domains; OData shares the Web API collection.
Core endpoint routing is another domain. There is no comparable global registration index.
The tool models these. A reading of the two files does not.
The seven ownership states, and what each one licenses
Every route in the report carries exactly one ownership value. They are not degrees of
confidence — they are different findings, and they call for different actions.
| State |
Meaning |
What it licenses |
Terminated |
Static evidence covers this route's paths and methods on Core. |
A deletion candidate, subject to every prerequisite in "Deleting a Framework route"; not unconditional permission. |
Forwarded |
The proxy forwards this route's URL space to the Framework app, or a Core handler for it forwards at least some requests (kind: "Forwarder"; read the handler before saying what it serves). |
It is still live on the old host. Migrating it is a unit of work; deleting it is an outage. |
Partial |
Local coverage is incomplete or symbolic, or the proxy forwards only a slice. |
Not proven complete. Inspect candidates and remaining traffic; this need not mean anything has migrated. |
Unclaimed |
The proxy was read, but no eligible local coverage or proven forwarding was found. |
Investigate a possible routing gap; a Core fallback may still answer. This is not proof of a 404. |
Ignored |
An IgnoreRoute that provably registers, or a route an earlier one provably swallows. Framework routing does not serve the URL; residualForwarded records whether a forwarder relates to it. |
A swallowed route never matches inbound and can go, subject to the preconditions in "Deleting a Framework route". The IgnoreRoute itself cannot — it is working, not redundant. When residualForwarded is true, a forwarder relates to these URLs: before treating them, or the Framework host, as retired, check that forwarder's methods, match conditions and destination, and whether an IIS handler (*.axd) or a static file answers them on Framework. |
Unknown |
Ownership could not be determined. |
Read unknownReason and resolve it before acting. |
NotApplicable |
The route is on the Core host, so there is no Framework space for it to take over. |
Nothing. Ownership is a question about Framework routes; filter these out before reasoning about coverage. |
Partial is the state that matters most, because it is the ordinary shape of a migration
in progress and the one that collapses if you only have "migrated" and "not migrated". A
broad Framework default route stays Partial for the whole middle of a migration: each
wave takes another slice of it, and it is not finished until the last one lands.
Partial arises two ways, and the difference is visible in terminatedBy:
terminatedBy is populated. Core endpoints overlap this space but were not shown to
cover all of it. Establish what they actually serve before deciding which traffic
remains.
terminatedBy is empty. No eligible local coverage was found; the proxy forwards only
a slice. This proves neither migration nor that the remainder is unreachable: a Core
fallback may still answer. Inspect the remaining paths and methods.
residualForwarded records whether a forwarder relates to this space. It does not prove
that every remaining URL or verb reaches Framework. Terminated clears it even when a forwarder
overlaps. For other verdicts, false means no related forwarding was found; inspect unresolved
gaps before deciding whether any remainder is unreachable.
Unknown is a question, not a failure. The unknownReason says what is missing:
NoProxySupplied — re-run with proxyProjectPath.
ProxyUnreadable — the Core project could not be read. Usually it does not build.
Fix that first; the answer is not unavailable, it was never gathered.
ConditionalCoverage — a registration that decides this route's coverage is gated on
configuration or sits in a loop, so whether it registers is a deployment fact. This
record's predicate gates only this route's own registration, so it answers the
question in the first case below and not the second:
- This route is itself a gated
IgnoreRoute (kind: "Ignore") — its own predicate
holds the condition, and that is the whole finding about whether it registers. Act on
residualForwarded as the Ignored row says.
- Otherwise a gated Core endpoint or YARP forwarder decides the space, and nothing
here points at it: it is deliberately left out of
terminatedBy, because an unproven
registration is not a coverage candidate. A predicate on this record does not fill
that gap — a Framework route can be gated itself and still report this reason for a
gated counterpart, so reading it answers the wrong question. Find the deciding
registration in routes: the entries carrying conditional: true or
mayRegisterMultipleTimes: true whose template reaches this route's URL space. A
gate is in predicate there, but a non-null predicate is not a readable one: a
loop records mayRegisterMultipleTimes beside an atom reading "loop at line N may
not execute", and an activation path the tool could not follow records one of its
own. Read isOpaque on the atoms — an opaque atom is the tool saying it could not
evaluate the condition, not the condition itself. Where the gate is opaque or
absent, the route stays undeletable — do not infer coverage from template shape.
Then decide per environment and re-run.
UnevaluableConstraint — match data on one side could not be evaluated, including
constraints, defaults, endpoint conventions, or selection metadata. Inspect the evidence and any linked unresolved entries.
OpaqueRegistrar — something claims part of this space through an API the tool cannot
see into. When routes holds a Middleware or MiddlewareBranch record, load ref/pipeline-code.md.
UnresolvedSymbol — a required value could not be read: a template, default, reference,
package version, or other dependency or restore evidence. See the fuller entry below.
ProxyPrecedence — Core endpoints do cover this space, but a forwarder overlapping it is not known to lose
endpoint selection to them, so the request may still reach Framework. Core orders endpoints by Order before
template specificity, so a forwarder whose Order is lower than the local endpoint's wins however specific that
endpoint is. A local that lists acceptedContentTypes without a */* that is bare or has q as its first
parameter is dropped for every other Content-Type, and none, whatever the Order; the forwarder takes that
request only if no other local that accepts it outranks or ties with the forwarder. Where evidence says that list
was read from a body a registration may make a service, the endpoint may accept any content type instead. For a
request both accept, at an equal Order and precedence, Core prefers the one that alone declares HTTP methods,
failing that the one that alone declares content types; the analysis never counts either as the local's win.
evidence names the types. Load ref/endpoint-order.md before interpreting conflicts or
changing order. It distinguishes readable conventions, opaque overrides, and conflicts that disagree.
ProxyPathTransform — Core endpoints cover this space, but a forwarder in reachedThrough may deliver to it from another
URL or method, so it is unconfirmed, not moved; load ref/proxy-destinations.md. An earlier
reason such as ProxyPrecedence or OpaqueRegistrar is reported in its place, so load it for an Unknown route at any
reason while a forwarder in routes carries destinationTemplate or hasOpaqueDestination.
terminatedBy names covering endpoints on Terminated, but on Partial it can name symbolic overlaps rather than a
slice proven to have moved. On Unknown it names overlapping candidates whose coverage could not be proven — the
shortlist to check, not a set of proven replacements. ProxyPrecedence and ProxyPathTransform are exceptions where
coverage was proven and what answers first, or where a forwarder delivers, is in doubt. OpaqueRegistrar from
pipeline code may mean that or unproven candidates, and the reason alone does not say which, so verify the list.
Either way, an Unknown's terminatedBy never licenses a deletion.
How coverage is decided, and what basis tells you
Two fields describe the quality of a route's answer, and they answer different questions.
precision is about reading the route: how much of what the tool knows about this
registration came from bound symbols. It is set when the route is scanned, and it says
nothing about how its ownership was later decided.
Enumerated — the scanner read a direct registration, or a conventional one whose
controller and action are both fixed. On a conventional route controller and action
are null whenever the template carries that token; the token's default is in
defaultController/defaultAction, which is only the value an omitted segment falls back
to. Read expansion and basis, not these fields, for the actions a route reaches.
Subsumption — the scanner represents the registration by its template, including
a conventional route with a controller or action token. This does not determine its eventual coverage basis.
SyntaxOnly — symbols did not bind at all and a bounded set of known registration
shapes was matched textually. Treat findings at this precision as leads.
basis is about deciding ownership, and it is the field to read before acting on a verdict.
Enumerated — conventional routes were expanded against the actions that actually exist, and
coverage was settled over the URLs they really serve. A conventional route such as
{controller}/{action}/{id?} is expanded by pairing each controller/action reachable
through it with the URL the route builds for it, carrying the verbs both the route's own
method constraint and the action admit; where they share none, the row keeps the route's
verbs and isCertain: false. This is the strongest answer the tool produces, and the only one
under which a conventional Core route can contribute proven coverage. A directly mapped
Core endpoint can cover a Framework template without conventional Core expansion.
Symbolic — coverage was decided by comparing template shapes. A shape containing
another shape is real evidence but weaker: it says the Core template could serve these
URLs, not that any action behind it does.
The two can disagree, and a route with precision: "Enumerated" and basis: "Symbolic"
is the ordinary case: the registration was read exactly, and the other host's was not.
Expansion is read two ways on purpose, and the difference is what keeps a destructive
verdict honest. Deciding a route's own URL space takes every action it might dispatch
to; deciding whether Core covers it takes only the actions Core certainly dispatches to.
A pairing the expander is unsure of therefore widens the space to be covered and never
counts towards covering it. An action is uncertain when it carries host metadata the tool
cannot evaluate, when configuration can rename it, when overloads on one route value share a
verb, or when a Core constraint, a convention or an unbound attribute can decline or re-route it.
Enumeration can also settle an overlap in the negative, and this is the one case where a
route reports less than the templates suggest. Where both sides were enumerated and not
one URL this route really serves is answered on Core, the overlap the templates implied is
known to be illusory — nothing/here fits the shape of {controller}/{action} without
being a URL any controller behind it produces. The Core route is then dropped from
terminatedBy rather than reported as partial coverage, because sending someone to
reconcile a slice that never moved costs them the same afternoon a real one would. This
retraction is withheld unless every Core registration that could reach the space stated
its URLs; where one did not, absence of evidence is not read as evidence of absence.
Enumeration is skipped — leaving basis: "Symbolic" — for any of these reasons:
- The inventory is incomplete (unbound project, custom or unbound name selector, actions chosen
outside the references), or an unresolved Framework reference could supply the route's controller.
- The route is not conventional. An attribute route already states a literal URL and needs
no expansion; a fallback, an ignore rule or a middleware branch has no action set.
- Its
{controller} token carries a constraint, or shares a segment with literal text
({controller}-legacy), so the values it admits are not the controller names.
- Its match data contains something the tool cannot read.
- The expansion would exceed the tool's endpoint ceiling. A route on a large project can
pair with thousands of actions, and past that point the expansion is abandoned rather
than truncated — a truncated one would look like a complete, smaller route.
Nothing is lost when enumeration is skipped except sharpness: the template comparison still
runs, and a route it cannot settle lands in Partial or Unknown rather than being claimed.
Matching and residual coverage
Framework defaults make the named parameters optional, so {id} with
id = UrlParameter.Optional is compared with Core {id?}. Inline defaults also confer
optionality, while controller/action/area default values determine which shorter aliases
exist. Literal path comparisons ignore case; constraint arguments, including regex text,
retain their case. Opaque constraints and ambiguous mixed segments cannot prove inclusion.
Where enumeration is available, residual coverage excludes endpoints fully claimed by
provably earlier registrations on the same Framework surface. A provably earlier ignore
covering the entire route yields Ignored. Partial or undecidable overlaps are not
generally subtracted. Conditional registrations, loops, and registrations in different
method bodies can leave ordering uncertain. Registration indices are stable inventory
order, not unconditional proof of runtime order.
An intersection supplies a coverage candidate, not a Terminated verdict. That verdict
requires inclusion of the whole relevant space, including shorter aliases and HTTP methods.
On Core, lower Order is compared before template precedence; for equal order, literals
outrank parameters and catch-alls. Authorization runs after endpoint selection: a local
401/403 does not fall through to YARP. Middleware runs earlier: see OpaqueRegistrar.
Read unresolved before you trust routes
The report has a second array. unresolved lists registrations the tool could see but
could not interpret, and each entry names a place where the inventory is incomplete.
A report with entries here is not a clean bill of health, and the states above are
only as complete as this list is empty.
The reasons that change what you should do:
ConfigDrivenGating — the proxy calls MapReverseProxy() but its configured route table is empty, or nothing here
proves that table is what the proxy loads, or a route's registration depends on runtime configuration. The third case
is the one that looks wired up: a ReverseProxy section and a MapReverseProxy() call are both present, but no
LoadFromConfig(...) was shown to bind that section, so the running proxy may take its routes from somewhere else
entirely. Those routes are reported as conditional rather than dead — the proxy is live and may well forward them.
What it forwards is a deployment fact that is not in the repository. Ask, or read the deployed configuration. A
forwarder whose id has Transforms in the other kind of settings file carries hasOpaqueDestination: load
ref/proxy-destinations.md.
MalformedSource — a project could not be loaded, a proxy directory could not be listed, a configuration file could
not be read, a route template or configuration file could not be parsed, or a configuration file sets a field YARP refuses. Read the entry's source, description,
and proxyStatus. If the Framework project did not load, proxyStatus is NotEvaluated: neither host was
inventoried, even if a proxy path was supplied. Do not infer unaffected scope from the reason alone. Affected routes
remain unsettled; unreadable proxy configuration leaves every proxy finding incomplete. A forwarder whose Transforms
could not be parsed carries hasOpaqueDestination: load ref/proxy-destinations.md.
UnsupportedRegistrationApi — a registration form the tool does not model, or code it
cannot read (a registrar in a referenced package, say) being handed the route collection.
Read it yourself. A URL the call site spells out is in routes with hasOpaqueMatchData,
but the entry still names no route — the unread code may rewrite it or register more — so
treat the whole URL space as undetermined.
AttributeRoutingNotEnabled — controllers carry route attributes but nothing calls
MapMvcAttributeRoutes() or MapHttpAttributeRoutes(), or on the Core side none of
MapControllers(), MapControllerRoute(), MapDefaultControllerRoute() or
MapAreaControllerRoute(). Those attributes are inert; a plan that migrates them as
live routes is migrating nothing.
UnresolvedSymbol — a template, default, reference, or other required value could not be
read. A registration may be missing entirely or retained with incomplete match data; inspect
its affected IDs rather than assuming every such entry describes a dropped route. Empty
affected IDs mean an unscoped gap that can reach any route. A source naming an assembly at
line 0 points to dependency evidence, not to a line you can open. An entry saying an import
path depends on properties "which no build file sets" means verdicts describe the build
evaluated on this machine; confirm the shipping build (CI, say) imports the same files.
UnevaluableConstraint — match data on a registration could not be evaluated. For a
route constraint that only rejects, the URL space in routes is an upper bound on what the
registration really matches; a constraint or builder hand-off the tool cannot read
can also reorder, re-route or re-host the affected routes, and then their templates bound nothing.
For selection metadata — a content-type or host attribute,
a metadata provider, a selector policy, or an MVC filter added through options.Filters —
it is which requests the endpoint is selected for that is unknown, and
acceptedContentTypes lists only what could be read, not necessarily what it accepts.
The same holds for any use of options.Filters outside the few plain forms the analysis
follows, a safe one included: a helper that returns the collection, or an extension
member called on it, is enough. What the analysis reads is C# source as compiled: a filter
added through reflection, IL rewriting, runtime patching, a generated proxy, or a library
handed MVC's options is outside its claim. The URL check in "Deleting a Framework
route" is the runtime backstop for it, not a guarantee: it only exercises representative
requests, so a passing check does not prove no such filter exists.
A MatcherPolicy declared in the project's source doubts every endpoint in the project,
so none of them proves migrated coverage. An endpoint convention can change the
endpoint's order, metadata or pattern. Core action/controller conventions can instead affect
action certainty or opaque match data without a separate unresolved row. Open the
registration the entry names and read what it does; until then the Framework route it
overlaps stays undeletable.
UnresolvedRedirectTarget — a Redirect(...) was found but what it redirects to could
not be proved. Retiring the destination silently breaks the redirect, so find it before
planning either one. Where the target was proved there is no unresolved entry at
all: the redirect route carries targetResolution: "Single" and names its destination
in redirectTargetIds, which is how you check whether a route you are about to delete
is something else's destination.
IndeterminateLoop — a registration sits inside a loop, so how many routes it adds and
where they sit in a first-match-wins collection are not knowable from the source.
Ordering for that surface is approximate, which weakens every shadowing claim in it.
OpaqueDestination — the path or method a forwarder delivers could not be read, so every Framework route Core covers, whatever that forwarder matches,
stays Unknown, at ProxyPathTransform unless an earlier reason applies; load ref/proxy-destinations.md.
OpaqueRegistrar — part of the URL space is claimed through an API the tool cannot see
into, such as Core pipeline code (load ref/pipeline-code.md). On the
Framework side it also names your own helper that takes the template and route collection
as parameters and branches, writes more than once, or is used other than by a direct call.
Helpers that provably pass the caller's URL to MapRoute, MapPageRoute, IgnoreRoute or
MapHttpRoute, or whose template is a compile-time constant, are read whatever their name; one
reaching the collection some other way lands in UnresolvedSymbol, naming the invoked API. Open
the named method and treat the URLs it adds as undetermined.
conflicts is the third array, and it is not optional reading
Two registrations can both be live and still disagree about who answers a URL.
conflicts names those pairs in participantIds, alongside the orderScope the
disagreement lives in and evidence in plain words.
class |
What it means |
LocalVersusCatchAll |
Three shapes, told apart by who is named in participantIds. Two Core routes — a local catch-all and the proxy catch-all cover the same space. Registration order does not decide this: Core compares lower numeric Order first, and where Order, precedence and selection metadata all tie there is no winner at all — the request fails with AmbiguousMatchException. Read evidence for which of the two this is. A non-catch-all Core endpoint and the proxy catch-all — reported whenever the local endpoint does not provably win, and also where it does if the catch-all names a CorsPolicy and lists Methods and the local admits OPTIONS, because the tool does not let Order settle the CORS preflight (see ref/endpoint-order.md). Core compares lower numeric Order before template precedence, so a more specific local template does not automatically beat the catch-all: it wins only at a lower Order, or at an equal Order where its precedence is higher (a template without a catch-all never ties a catch-all on precedence, so the declared-method and content-type rungs of ref/endpoint-order.md never decide this shape) — and, if it lists acceptedContentTypes without a */* that is bare or has q as its first parameter, never for a request whose Content-Type falls outside them, or that carries none; the catch-all takes that request only if no other local that accepts it outranks or ties with the catch-all. Where the relative Order cannot be established, the conflict is reported rather than assumed away. A Framework route and a Core fallback (MapFallbackToFile and friends) — informational. A fallback sits at the lowest precedence and answers only what matches nothing else, so it never displaces a real endpoint and is not evidence of migration. |
LocalVersusLocal |
Two registrations on one host may compete, and the two hosts fail differently. Two Framework registrations — source order, a shared HTTP method and containing templates are not proof of runtime shadowing: inspect activation, execution order and full method coverage, since the first match wins and the later route is simply never reached. Two Core endpoints — everything this analysis can read ties. Both serve a URL named in evidence at the same Order for a shared method, with equal precedence and equal constraints, and Core requires a unique winner, so the request throws AmbiguousMatchException rather than falling through to either. What decides it is endpoint selection. This analysis reads methods, route constraints and the content types each endpoint accepts (acceptedContentTypes on the route). Absent means any only on a route whose selection is read — a minimal API (MapGet, MapMethods and the like), a bare Map, a MapFallback with a handler, or an attribute-routed action — and not where the route has hasOpaqueMatchData or an unresolved entry names it. A conventional route (MapControllerRoute, MapAreaControllerRoute, MapDefaultControllerRoute) never carries the field, whatever its actions declare; an action it reaches that declares content types is counted as uncertain instead. Core prefers an endpoint that declares HTTP methods over one that declares none, so a pair where only one of the two declares methods is not reported. Content types can then separate a pair, or confine its tie to requests carrying no Content-Type; evidence says which. An endpoint whose host restriction or other selection metadata could not be read is left out rather than tied. A selector policy declared outside this project, whether compiled into a reference or in a sibling project, is invisible wherever it is registered, and may separate the pair at runtime. Check the two registrations for one before treating the pair as broken — but treat it as a live failure until you have found one that does, because the tie is real everywhere this analysis can see. It is reported only where the shared URL was enumerated. |
ProxyVersusLocal |
An explicit proxy route and a local Core endpoint both claim the space. Check content types first: a local that lists acceptedContentTypes without a */* that is bare or has q as its first parameter is dropped for every request carrying another Content-Type, or none, whatever the Order, and the proxy route takes it only if no other local that accepts it outranks or ties with the proxy route. For a request both accept, compare Order, then template precedence for equal order, then, for equal precedence, declared HTTP methods before declared content types (ref/endpoint-order.md); the analysis never counts those last two as the local's win. Do not assume the local endpoint wins: requests may still forward to Framework, or a tie may fail as ambiguous. Read the conflict evidence before treating the local endpoint as the one serving the URL. |
A LocalVersusLocal entry deserves investigation, not automatic exclusion from a wave. Its evidence
distinguishes a proven swallowing IgnoreRoute, a possible Framework overlap, and a Core tie that
nothing readable separates — the last of which is a bug in the destination unless a selector policy
this analysis cannot see tells the two apart, and worth fixing before more traffic is pointed at it.
An empty conflicts array is only evidence if the proxy was read. Check proxyStatus
on the report before drawing any conclusion from it, and before trusting an ownership
verdict that depends on proxy coverage:
proxyStatus |
What it means |
Read |
The proxy was parsed. An empty conflicts array means no modeled conflict was found, not that runtime ambiguity is impossible. |
NotSupplied |
No proxy project was named, so nothing proxy-related was evaluated. Routes that depend on proxy coverage will be Unknown (NoProxySupplied); Ignored verdicts are decided on the Framework side alone and still stand. Re-run with proxyProjectPath to get real answers. |
Unreadable |
A proxy project was named but would not load. Fix that before reading the report — this is not the same as there being no conflicts. |
NotEvaluated |
The scan stopped before the proxy was opened, because the Framework project itself would not load. Read unresolved for the reason; supplying a different proxy path will not help. |
An empty routes array does not mean the project has no routes. It means none were
read. When proxyStatus is NotEvaluated, the Framework project itself did not load and
nothing was inventoried at all. When unresolved carries MalformedSource,
UnsupportedRegistrationApi, or UnresolvedSymbol, registrations exist that are missing
from routes. In either case the report is silent about routes that are still serving
traffic, so it cannot support retiring RouteConfig.cs or calling a migration finished.
Environment-specific proxy configuration
Routes read from appsettings.Development.json (or any other environment file) are reported with the file they
came from in source.filePath; a CorsPolicy, Match.Methods or Order merged in from the file a run loads beside
it is named, with that file, in a ConfigDrivenGating entry. Which file wins is a deployment fact the repository does
not record — a route that only exists in Development is not one production serves. Check the file before planning.
Using the report to plan a wave
- Run the tool against both projects.
- If
unresolved is non-empty, resolve what you can and state the rest as known gaps.
Do not plan around an inventory you know is partial without saying so.
- Take the
Forwarded routes and every Partial route as the candidate pool.
Investigate LocalVersusLocal entries before excluding anything: a conditional earlier
registration or one sharing only GET can leave the later route live for other traffic.
Exclude a candidate only after independently confirming it is unreachable.
- Group candidates by controller or area, not by route count. Routes that share a
controller move together or break each other. Group a Framework route by its
expansion
rows (template, httpMethods, area where present, controller, action, isCertain), not by its defaults. A
route's own httpMethods is its method constraint (never read for kind: "Ignore", whose
[] says nothing about verbs); a request with another verb falls through to the next
route, so two same-template routes with disjoint verbs are separate slices. A row with
isCertain: false is one the route may reach (an area it cannot rule out, a shorter
URL dropping a constrained optional segment, or an action whose selection is uncertain:
ambiguous same-verb actions or overloads, host metadata, a custom or unbound verb
provider; a custom MVC method selector stays certain, since the route already
dispatched when it declines) or one it matches and then dispatches nothing (its verbs
are the route's, shared with no action verb): keep it in the space a deletion must
cover, but never read it as that action serving those verbs. Only Framework routes
carry expansion; expansion: [] means the route was expanded and reaches no action.
A missing expansion (with or without expansionOmitted: true, meaning its rows
exceeded the report's budget) leaves no rows: treat the whole template as one slice.
- For each
Partial route in the pool, identify the remaining slice specifically. This
is where a wave silently leaves URLs behind.
- After the wave, re-run and exercise the changed URLs and verbs. When conventional
action enumeration is available and coverage and forwarder precedence are readable, a
fully moved route can return
Terminated at basis: "Enumerated". Core pipeline code can
instead withhold it as Unknown at OpaqueRegistrar; load
ref/pipeline-code.md, since re-running alone will not clear it. The scaffold's
MapForwarder(...).WithOrder(int.MaxValue) provides a readable last-resort order, not
proof that every route migrated. Attribute routes need no conventional expansion, so
not every migrated route has an enumerated basis. Hand-rolled forwarders or unrecognized
handlers need runtime confirmation: forwarding inside a referenced project can still
leave a handler classified as local. In all cases, no verdict bypasses "Deleting a Framework
route": check unresolved gaps, conflicts, and runtime host attribution. For Partial, inspect candidates and the
remaining slice; for Unknown at ProxyPrecedence, check forwarder order, recognizability and the local's
acceptedContentTypes, which no Order clears; for Unknown at ProxyPathTransform, load
ref/proxy-destinations.md. Investigate Unclaimed as a possible routing gap, not proof of a live 404.
Deleting a Framework route
Two verdicts license deletion, and each has preconditions. Both speak only to inbound
matching: a route that can never match still generates URLs. Generation selects a route by
name — Url.RouteUrl("live"), the three-argument GetVirtualPath — where deleting it
throws A route named 'live' could not be found; or by route values — Html.ActionLink,
Url.Action, the two-argument GetVirtualPath — which walks the collection for the first
route that can build the URL, so deleting it silently returns null, a different URL, or
the same URL from another route, naming neither the route nor its object. The report
inventories neither kind. Under either verdict, deletion must change no URL the application
depends on and break no consumer, named or not: searching for the name and for direct
references starts that, and comparing generated URLs is evidence, not proof —
GetVirtualPath returns the selected route and its data tokens, not just a string, so a
consumer reading either can break while the URLs compare equal. Preserve or retire every
consumer you find, and where you cannot establish it, do not delete.
Terminated licenses it when all of the following hold:
- The report was produced with
proxyProjectPath supplied.
- No unresolved gap can affect that route or its proposed Core replacement. Check both the
route ID and every ID in
terminatedBy against unresolved[].affectedRouteIds. Entries
with no affected IDs are unscoped gaps, not harmless ones; resolve them or establish that
they cannot affect this URL space before deleting anything.
- No Core route named in the route's
terminatedBy appears in any
conflicts[].participantIds. A Terminated verdict already means no forwarder was found
to preempt that endpoint, so a surviving conflict is one the analysis judged the endpoint
to win, or one it does not decide. Confirm the endpoint in terminatedBy answers.
- Other-project code that a
terminatedBy handler reaches, or that is handed the application or an endpoint builder, does not answer or forward first; where you cannot establish that, do not delete.
- Inspect references in
redirectTargetIds and confirm redirects still reach their
intended destination on Core. A preserved destination URL can outlive its Framework
registration; a removed destination cannot.
Before deletion, exercise representative URLs and verbs against the deployed Core routing table,
including host restrictions, content types and competing endpoints. The static report models neither every
runtime convention nor every Core-local ambiguity — an empty conflicts array proves nothing.
Nor does it see every assembly in bin. It reads references, package runtime assets and copied
content files, and Content or None items that copy an assembly to the output. It cannot see
one a custom Copy task, a package's build/ targets or a post-build step puts there, so before
deleting, compare the deployed bin against what the project declares.
A conflict naming the Framework route itself does not block deletion: it describes the
Framework side — a route or IgnoreRoute shadowing this one, or a Core fallback answering
whatever reaches it — and changes nothing about whether terminatedBy serves the space.
Ignored licenses it only when kind is not Ignore. An earlier IgnoreRoute on the
same surface swallows such a route before it can match, and the scan models registration
only, so that verdict rests on the ignore still swallowing it when the request arrives.
**Establish that it still does — in every deployment the ignore precedes this route on the
same active surface and matches every request the route would an
…(truncated)
1---2name: analyzing-cross-host-route-ownership3description: >4 Determines which URLs a partly migrated app is still served by the old .NET Framework host and5 which the new ASP.NET Core host already answers, by reading both projects and the YARP route6 table. Use when planning the next wave of a side-by-side migration, before deleting or moving a7 Framework route, or when deciding whether a route has finished migrating. Also triggers for8 "which routes still run on the old app", "what is the proxy forwarding", "is this route migrated9 yet", "what is safe to move next", "route inventory", "did we miss a route", "both apps seem to10 handle this URL", and "can I delete this Framework route yet".11metadata:12 source: https://skillmd.com/skills/microsoft/analyzing-cross-host-route-ownership13 traits: .NET|CSharp|DotNetCore14 discovery: lazy15---1617# Cross-Host Route Ownership Analysis1819In a side-by-side migration two hosts are live at once. The new ASP.NET Core host takes20the request first, serves what it has already migrated, and forwards the rest through YARP21to the still-running .NET Framework app. The question that governs every wave is which22URLs are on which side — and it cannot be answered by reading either project alone,23because the answer lives in the relationship between three things: the Framework route24table, the Core endpoint table, and the proxy configuration.2526This skill covers reading that answer. It does not migrate routes27(**migrating-mvc-routing**) and does not create the proxy28(**scaffolding-yarp-proxy-project**).2930This adds a machine-readable inventory and ownership/conflict analysis to the prose31baseline in **migrating-aspnet-framework-to-core/side-by-side.md**. Keep that baseline32for runtime comparison; the report does not replace it.3334**The analyzer supports C# projects only.** Both inputs must be `.csproj` files. Visual Basic35and other project languages are not supported; do not interpret an unsupported project36as having no routes. Projects must be loadable through the current workspace. An unloaded37proxy is reported as unreadable, not scanned by guessing which files belong to it.3839## Get the answer from the tool, not by reading route files4041```42analyze_route_ownership(43 projectPath="{full path to the .NET Framework .csproj}",44 proxyProjectPath="{full path to the ASP.NET Core .csproj}"45)46```4748Both paths must be absolute. `proxyProjectPath` is optional and omitting it changes the49question being asked: without it you get an inventory of the Framework routes with every50answer that depends on Core coverage reported as unknown — useful before the Core host51exists and misleading afterwards. **Supply it whenever the Core host exists.**5253Do not answer ownership questions by reading `RouteConfig.cs` and `Program.cs` yourself.54Route templates that look equivalent frequently are not, and the differences are not55visible in the strings:5657- A Framework route with `defaults: new { action = "Index" }` serves the bare prefix58 `/packages`. A Core route written `packages/{action}/{id?}` does not. The templates read59 almost identically and cover different URL sets.60- `IgnoreRoute` installs a `StopRoutingHandler`. It looks like a registered route, but it means61 Framework *routing* serves nothing there — not that nothing does: an IIS handler (`*.axd`) may.62- A route registered inside `if (config.EnableFeature)` may or may not exist at runtime,63 and the source does not say which.64- MVC and Web API/OData use separate ordering domains; OData shares the Web API collection.65 Core endpoint routing is another domain. There is no comparable global registration index.6667The tool models these. A reading of the two files does not.6869## The seven ownership states, and what each one licenses7071Every route in the report carries exactly one `ownership` value. They are not degrees of72confidence — they are different findings, and they call for different actions.7374| State | Meaning | What it licenses |75|-------|---------|------------------|76| `Terminated` | Static evidence covers this route's paths and methods on Core. | A deletion candidate, subject to every prerequisite in "Deleting a Framework route"; not unconditional permission. |77| `Forwarded` | The proxy forwards this route's URL space to the Framework app, or a Core handler for it forwards at least some requests (`kind: "Forwarder"`; read the handler before saying what it serves). | It is still live on the old host. Migrating it is a unit of work; deleting it is an outage. |78| `Partial` | Local coverage is incomplete or symbolic, or the proxy forwards only a slice. | **Not proven complete.** Inspect candidates and remaining traffic; this need not mean anything has migrated. |79| `Unclaimed` | The proxy was read, but no eligible local coverage or proven forwarding was found. | Investigate a possible routing gap; a Core fallback may still answer. This is not proof of a 404. |80| `Ignored` | An `IgnoreRoute` that provably registers, or a route an earlier one provably swallows. Framework routing does not serve the URL; `residualForwarded` records whether a forwarder relates to it. | A swallowed route never matches inbound and can go, subject to the preconditions in "Deleting a Framework route". The `IgnoreRoute` itself cannot — it is working, not redundant. When `residualForwarded` is `true`, a forwarder relates to these URLs: before treating them, or the Framework host, as retired, check that forwarder's methods, match conditions and destination, and whether an IIS handler (`*.axd`) or a static file answers them on Framework. |81| `Unknown` | Ownership could not be determined. | Read `unknownReason` and resolve it before acting. |82| `NotApplicable` | The route is on the Core host, so there is no Framework space for it to take over. | Nothing. Ownership is a question about Framework routes; filter these out before reasoning about coverage. |8384`Partial` is the state that matters most, because it is the ordinary shape of a migration85in progress and the one that collapses if you only have "migrated" and "not migrated". A86broad Framework default route stays `Partial` for the whole middle of a migration: each87wave takes another slice of it, and it is not finished until the last one lands.8889`Partial` arises two ways, and the difference is visible in `terminatedBy`:9091- **`terminatedBy` is populated.** Core endpoints overlap this space but were not shown to92 cover all of it. Establish what they actually serve before deciding which traffic93 remains.94- **`terminatedBy` is empty.** No eligible local coverage was found; the proxy forwards only95 a slice. This proves neither migration nor that the remainder is unreachable: a Core96 fallback may still answer. Inspect the remaining paths and methods.9798`residualForwarded` records whether a forwarder relates to this space. It does not prove99that every remaining URL or verb reaches Framework. `Terminated` clears it even when a forwarder100overlaps. For other verdicts, false means no related forwarding was found; inspect unresolved101gaps before deciding whether any remainder is unreachable.102103**`Unknown` is a question, not a failure.** The `unknownReason` says what is missing:104105- `NoProxySupplied` — re-run with `proxyProjectPath`.106- `ProxyUnreadable` — the Core project could not be read. Usually it does not build.107 Fix that first; the answer is not unavailable, it was never gathered.108- `ConditionalCoverage` — a registration that decides this route's coverage is gated on109 configuration or sits in a loop, so whether it registers is a deployment fact. This110 record's `predicate` gates only this route's own registration, so it answers the111 question in the first case below and not the second:112 - **This route is itself a gated `IgnoreRoute`** (`kind: "Ignore"`) — its own `predicate`113 holds the condition, and that is the whole finding about whether it registers. Act on114 `residualForwarded` as the `Ignored` row says.115 - **Otherwise a gated Core endpoint or YARP forwarder** decides the space, and nothing116 here points at it: it is deliberately left out of `terminatedBy`, because an unproven117 registration is not a coverage candidate. A `predicate` on this record does not fill118 that gap — a Framework route can be gated itself and still report this reason for a119 gated counterpart, so reading it answers the wrong question. Find the deciding120 registration in `routes`: the entries carrying `conditional: true` or121 `mayRegisterMultipleTimes: true` whose template reaches this route's URL space. A122 gate is in `predicate` there, but a non-null `predicate` is not a readable one: a123 loop records `mayRegisterMultipleTimes` beside an atom reading "loop at line N may124 not execute", and an activation path the tool could not follow records one of its125 own. Read `isOpaque` on the atoms — an opaque atom is the tool saying it could not126 evaluate the condition, not the condition itself. Where the gate is opaque or127 absent, the route stays undeletable — do not infer coverage from template shape.128129 Then decide per environment and re-run.130- `UnevaluableConstraint` — match data on one side could not be evaluated, including131 constraints, defaults, endpoint conventions, or selection metadata. Inspect the evidence and any linked unresolved entries.132- `OpaqueRegistrar` — something claims part of this space through an API the tool cannot133 see into. When `routes` holds a `Middleware` or `MiddlewareBranch` record, **load [ref/pipeline-code.md](ref/pipeline-code.md)**.134- `UnresolvedSymbol` — a required value could not be read: a template, default, reference,135 package version, or other dependency or restore evidence. See the fuller entry below.136- `ProxyPrecedence` — Core endpoints do cover this space, but a forwarder overlapping it is not known to lose137 endpoint selection to them, so the request may still reach Framework. Core orders endpoints by `Order` before138 template specificity, so a forwarder whose `Order` is lower than the local endpoint's wins however specific that139 endpoint is. A local that lists `acceptedContentTypes` without a `*/*` that is bare or has `q` as its first140 parameter is dropped for every other `Content-Type`, and none, whatever the `Order`; the forwarder takes that141 request only if no other local that accepts it outranks or ties with the forwarder. Where `evidence` says that list142 was read from a body a registration may make a service, the endpoint may accept any content type instead. For a143 request both accept, at an equal `Order` and precedence, Core prefers the one that alone declares HTTP methods,144 failing that the one that alone declares content types; the analysis never counts either as the local's win.145 `evidence` names the types. Load [ref/endpoint-order.md](ref/endpoint-order.md) before interpreting conflicts or146 changing order. It distinguishes readable conventions, opaque overrides, and conflicts that disagree.147- `ProxyPathTransform` — Core endpoints cover this space, but a forwarder in `reachedThrough` may deliver to it from another148 URL or method, so it is unconfirmed, not moved; **load [ref/proxy-destinations.md](ref/proxy-destinations.md)**. An earlier149 reason such as `ProxyPrecedence` or `OpaqueRegistrar` is reported in its place, so load it for an `Unknown` route at any150 reason while a forwarder in `routes` carries `destinationTemplate` or `hasOpaqueDestination`.151152`terminatedBy` names covering endpoints on `Terminated`, but on `Partial` it can name symbolic overlaps rather than a153slice proven to have moved. On `Unknown` it names overlapping **candidates** whose coverage could not be proven — the154shortlist to check, not a set of proven replacements. `ProxyPrecedence` and `ProxyPathTransform` are exceptions where155coverage *was* proven and what answers first, or where a forwarder delivers, is in doubt. `OpaqueRegistrar` from156pipeline code may mean that or unproven candidates, and the reason alone does not say which, so verify the list.157Either way, an `Unknown`'s `terminatedBy` never licenses a deletion.158159## How coverage is decided, and what `basis` tells you160161Two fields describe the quality of a route's answer, and they answer different questions.162163`precision` is about **reading the route**: how much of what the tool knows about this164registration came from bound symbols. It is set when the route is scanned, and it says165nothing about how its ownership was later decided.166167- **`Enumerated`** — the scanner read a direct registration, or a conventional one whose168 controller and action are both fixed. On a conventional route `controller` and `action`169 are null whenever the template carries that token; the token's default is in170 `defaultController`/`defaultAction`, which is only the value an omitted segment falls back171 to. Read `expansion` and `basis`, not these fields, for the actions a route reaches.172- **`Subsumption`** — the scanner represents the registration by its template, including173 a conventional route with a controller or action token. This does not determine its eventual coverage basis.174- **`SyntaxOnly`** — symbols did not bind at all and a bounded set of known registration175 shapes was matched textually. Treat findings at this precision as leads.176177`basis` is about **deciding ownership**, and it is the field to read before acting on a verdict.178179- **`Enumerated`** — conventional routes were expanded against the actions that actually exist, and180 coverage was settled over the URLs they really serve. A conventional route such as181 `{controller}/{action}/{id?}` is expanded by pairing each controller/action reachable182 through it with the URL the route builds for it, carrying the verbs both the route's own183 method constraint and the action admit; where they share none, the row keeps the route's184 verbs and `isCertain: false`. This is the strongest answer the tool produces, and the only one185 under which a conventional Core route can contribute proven coverage. A directly mapped186 Core endpoint can cover a Framework template without conventional Core expansion.187- **`Symbolic`** — coverage was decided by comparing template shapes. A shape containing188 another shape is real evidence but weaker: it says the Core template *could* serve these189 URLs, not that any action behind it does.190191The two can disagree, and a route with `precision: "Enumerated"` and `basis: "Symbolic"`192is the ordinary case: the registration was read exactly, and the other host's was not.193194Expansion is read two ways on purpose, and the difference is what keeps a destructive195verdict honest. Deciding a route's *own* URL space takes every action it might dispatch196to; deciding whether Core *covers* it takes only the actions Core certainly dispatches to.197A pairing the expander is unsure of therefore widens the space to be covered and never198counts towards covering it. An action is uncertain when it carries host metadata the tool199cannot evaluate, when configuration can rename it, when overloads on one route value share a200verb, or when a Core constraint, a convention or an unbound attribute can decline or re-route it.201202Enumeration can also settle an overlap in the negative, and this is the one case where a203route reports *less* than the templates suggest. Where both sides were enumerated and not204one URL this route really serves is answered on Core, the overlap the templates implied is205known to be illusory — `nothing/here` fits the shape of `{controller}/{action}` without206being a URL any controller behind it produces. The Core route is then dropped from207`terminatedBy` rather than reported as partial coverage, because sending someone to208reconcile a slice that never moved costs them the same afternoon a real one would. This209retraction is withheld unless every Core registration that could reach the space stated210its URLs; where one did not, absence of evidence is not read as evidence of absence.211212Enumeration is skipped — leaving `basis: "Symbolic"` — for any of these reasons:213214- The inventory is incomplete (unbound project, custom or unbound name selector, actions chosen215 outside the references), or an unresolved Framework reference could supply the route's controller.216- The route is not conventional. An attribute route already states a literal URL and needs217 no expansion; a fallback, an ignore rule or a middleware branch has no action set.218- Its `{controller}` token carries a constraint, or shares a segment with literal text219 (`{controller}-legacy`), so the values it admits are not the controller names.220- Its match data contains something the tool cannot read.221- The expansion would exceed the tool's endpoint ceiling. A route on a large project can222 pair with thousands of actions, and past that point the expansion is abandoned rather223 than truncated — a truncated one would look like a complete, smaller route.224225Nothing is lost when enumeration is skipped except sharpness: the template comparison still226runs, and a route it cannot settle lands in `Partial` or `Unknown` rather than being claimed.227228### Matching and residual coverage229230Framework defaults make the named parameters optional, so `{id}` with231`id = UrlParameter.Optional` is compared with Core `{id?}`. Inline defaults also confer232optionality, while controller/action/area default values determine which shorter aliases233exist. Literal path comparisons ignore case; constraint arguments, including regex text,234retain their case. Opaque constraints and ambiguous mixed segments cannot prove inclusion.235236Where enumeration is available, residual coverage excludes endpoints fully claimed by237provably earlier registrations on the same Framework surface. A provably earlier ignore238covering the entire route yields `Ignored`. Partial or undecidable overlaps are not239generally subtracted. Conditional registrations, loops, and registrations in different240method bodies can leave ordering uncertain. Registration indices are stable inventory241order, not unconditional proof of runtime order.242243An intersection supplies a coverage candidate, not a `Terminated` verdict. That verdict244requires inclusion of the whole relevant space, including shorter aliases and HTTP methods.245On Core, lower `Order` is compared **before** template precedence; for equal order, literals246outrank parameters and catch-alls. Authorization runs after endpoint selection: a local247401/403 does not fall through to YARP. Middleware runs earlier: see `OpaqueRegistrar`.248249## Read `unresolved` before you trust `routes`250251The report has a second array. `unresolved` lists registrations the tool could see but252could not interpret, and each entry names a place where the inventory is incomplete.253**A report with entries here is not a clean bill of health**, and the states above are254only as complete as this list is empty.255256The reasons that change what you should do:257258- `ConfigDrivenGating` — the proxy calls `MapReverseProxy()` but its configured route table is empty, or nothing here259 proves that table is what the proxy loads, or a route's registration depends on runtime configuration. The third case260 is the one that looks wired up: a `ReverseProxy` section and a `MapReverseProxy()` call are both present, but no261 `LoadFromConfig(...)` was shown to bind that section, so the running proxy may take its routes from somewhere else262 entirely. Those routes are reported as conditional rather than dead — the proxy is live and may well forward them.263 What it forwards is a deployment fact that is not in the repository. Ask, or read the deployed configuration. A264 forwarder whose id has `Transforms` in the other kind of settings file carries `hasOpaqueDestination`: **load265 [ref/proxy-destinations.md](ref/proxy-destinations.md)**.266- `MalformedSource` — a project could not be loaded, a proxy directory could not be listed, a configuration file could267 not be read, a route template or configuration file could not be parsed, or a configuration file sets a field YARP refuses. Read the entry's `source`, `description`,268 and `proxyStatus`. If the Framework project did not load, `proxyStatus` is `NotEvaluated`: neither host was269 inventoried, even if a proxy path was supplied. Do not infer unaffected scope from the reason alone. Affected routes270 remain unsettled; unreadable proxy configuration leaves every proxy finding incomplete. A forwarder whose `Transforms`271 could not be parsed carries `hasOpaqueDestination`: **load [ref/proxy-destinations.md](ref/proxy-destinations.md)**.272- `UnsupportedRegistrationApi` — a registration form the tool does not model, or code it273 cannot read (a registrar in a referenced package, say) being handed the route collection.274 Read it yourself. A URL the call site spells out is in `routes` with `hasOpaqueMatchData`,275 but the entry still names no route — the unread code may rewrite it or register more — so276 treat the whole URL space as undetermined.277- `AttributeRoutingNotEnabled` — controllers carry route attributes but nothing calls278 `MapMvcAttributeRoutes()` or `MapHttpAttributeRoutes()`, or on the Core side none of279 `MapControllers()`, `MapControllerRoute()`, `MapDefaultControllerRoute()` or280 `MapAreaControllerRoute()`. Those attributes are inert; a plan that migrates them as281 live routes is migrating nothing.282- `UnresolvedSymbol` — a template, default, reference, or other required value could not be283 read. A registration may be missing entirely or retained with incomplete match data; inspect284 its affected IDs rather than assuming every such entry describes a dropped route. Empty285 affected IDs mean an unscoped gap that can reach any route. A source naming an assembly at286 line 0 points to dependency evidence, not to a line you can open. An entry saying an import287 path depends on properties "which no build file sets" means verdicts describe the build288 evaluated on this machine; confirm the shipping build (CI, say) imports the same files.289- `UnevaluableConstraint` — match data on a registration could not be evaluated. For a290 route constraint that only rejects, the URL space in `routes` is an upper bound on what the291 registration really matches; a constraint or builder hand-off the tool cannot read292 can also reorder, re-route or re-host the affected routes, and then their templates bound nothing.293 For selection metadata — a content-type or host attribute,294 a metadata provider, a selector policy, or an MVC filter added through `options.Filters` —295 it is which requests the endpoint is selected for that is unknown, and296 `acceptedContentTypes` lists only what could be read, not necessarily what it accepts.297 The same holds for any use of `options.Filters` outside the few plain forms the analysis298 follows, a safe one included: a helper that returns the collection, or an extension299 member called on it, is enough. What the analysis reads is C# source as compiled: a filter300 added through reflection, IL rewriting, runtime patching, a generated proxy, or a library301 handed MVC's options is outside its claim. The URL check in "Deleting a Framework302 route" is the runtime backstop for it, not a guarantee: it only exercises representative303 requests, so a passing check does not prove no such filter exists.304 A `MatcherPolicy` declared in the project's source doubts every endpoint in the project,305 so none of them proves migrated coverage. An endpoint convention can change the306 endpoint's order, metadata or pattern. Core action/controller conventions can instead affect307 action certainty or opaque match data without a separate unresolved row. Open the308 registration the entry names and read what it does; until then the Framework route it309 overlaps stays undeletable.310- `UnresolvedRedirectTarget` — a `Redirect(...)` was found but what it redirects to could311 not be proved. Retiring the destination silently breaks the redirect, so find it before312 planning either one. Where the target *was* proved there is no `unresolved` entry at313 all: the redirect route carries `targetResolution: "Single"` and names its destination314 in `redirectTargetIds`, which is how you check whether a route you are about to delete315 is something else's destination.316- `IndeterminateLoop` — a registration sits inside a loop, so how many routes it adds and317 where they sit in a first-match-wins collection are not knowable from the source.318 Ordering for that surface is approximate, which weakens every shadowing claim in it.319- `OpaqueDestination` — the path or method a forwarder delivers could not be read, so **every** Framework route Core covers, whatever that forwarder matches,320 stays `Unknown`, at `ProxyPathTransform` unless an earlier reason applies; **load [ref/proxy-destinations.md](ref/proxy-destinations.md)**.321- `OpaqueRegistrar` — part of the URL space is claimed through an API the tool cannot see322 into, such as Core pipeline code (**load [ref/pipeline-code.md](ref/pipeline-code.md)**). On the323 Framework side it also names your own helper that takes the template and route collection324 as parameters and branches, writes more than once, or is used other than by a direct call.325 Helpers that provably pass the caller's URL to `MapRoute`, `MapPageRoute`, `IgnoreRoute` or326 `MapHttpRoute`, or whose template is a compile-time constant, are read whatever their name; one327 reaching the collection some other way lands in `UnresolvedSymbol`, naming the invoked API. Open328 the named method and treat the URLs it adds as undetermined.329330## `conflicts` is the third array, and it is not optional reading331332Two registrations can both be live and still disagree about who answers a URL.333`conflicts` names those pairs in `participantIds`, alongside the `orderScope` the334disagreement lives in and `evidence` in plain words.335336| `class` | What it means |337|---------|---------------|338| `LocalVersusCatchAll` | Three shapes, told apart by who is named in `participantIds`. **Two Core routes** — a local *catch-all* and the proxy catch-all cover the same space. Registration order does not decide this: Core compares lower numeric `Order` first, and where `Order`, precedence and selection metadata all tie there is no winner at all — the request fails with `AmbiguousMatchException`. Read `evidence` for which of the two this is. **A non-catch-all Core endpoint and the proxy catch-all** — reported whenever the local endpoint does not *provably* win, and also where it does if the catch-all names a `CorsPolicy` and lists `Methods` and the local admits `OPTIONS`, because the tool does not let `Order` settle the CORS preflight (see [ref/endpoint-order.md](ref/endpoint-order.md)). Core compares lower numeric `Order` before template precedence, so a more specific local template does not automatically beat the catch-all: it wins only at a lower `Order`, or at an equal `Order` where its precedence is higher (a template without a catch-all never ties a catch-all on precedence, so the declared-method and content-type rungs of [ref/endpoint-order.md](ref/endpoint-order.md) never decide this shape) — and, if it lists `acceptedContentTypes` without a `*/*` that is bare or has `q` as its first parameter, never for a request whose `Content-Type` falls outside them, or that carries none; the catch-all takes that request only if no other local that accepts it outranks or ties with the catch-all. Where the relative `Order` cannot be established, the conflict is reported rather than assumed away. **A Framework route and a Core fallback** (`MapFallbackToFile` and friends) — informational. A fallback sits at the lowest precedence and answers only what matches nothing else, so it never displaces a real endpoint and is not evidence of migration. |339| `LocalVersusLocal` | Two registrations on one host may compete, and the two hosts fail differently. **Two Framework registrations** — source order, a shared HTTP method and containing templates are not proof of runtime shadowing: inspect activation, execution order and full method coverage, since the first match wins and the later route is simply never reached. **Two Core endpoints** — everything this analysis can read ties. Both serve a URL named in `evidence` at the same `Order` for a shared method, with equal precedence and equal constraints, and Core requires a unique winner, so the request throws `AmbiguousMatchException` rather than falling through to either. What decides it is endpoint *selection*. This analysis reads methods, route constraints and the content types each endpoint accepts (`acceptedContentTypes` on the route). Absent means any only on a route whose selection is read — a minimal API (`MapGet`, `MapMethods` and the like), a bare `Map`, a `MapFallback` with a handler, or an attribute-routed action — and not where the route has `hasOpaqueMatchData` or an unresolved entry names it. A conventional route (`MapControllerRoute`, `MapAreaControllerRoute`, `MapDefaultControllerRoute`) never carries the field, whatever its actions declare; an action it reaches that declares content types is counted as uncertain instead. Core prefers an endpoint that declares HTTP methods over one that declares none, so a pair where only one of the two declares methods is not reported. Content types can then separate a pair, or confine its tie to requests carrying no `Content-Type`; `evidence` says which. An endpoint whose host restriction or other selection metadata could not be read is left out rather than tied. A selector policy declared outside this project, whether compiled into a reference or in a sibling project, is invisible wherever it is registered, and may separate the pair at runtime. Check the two registrations for one before treating the pair as broken — but treat it as a live failure until you have found one that does, because the tie is real everywhere this analysis can see. It is reported only where the shared URL was enumerated. |340| `ProxyVersusLocal` | An explicit proxy route and a local Core endpoint both claim the space. Check content types first: a local that lists `acceptedContentTypes` without a `*/*` that is bare or has `q` as its first parameter is dropped for every request carrying another `Content-Type`, or none, whatever the `Order`, and the proxy route takes it only if no other local that accepts it outranks or ties with the proxy route. For a request both accept, compare `Order`, then template precedence for equal order, then, for equal precedence, declared HTTP methods before declared content types ([ref/endpoint-order.md](ref/endpoint-order.md)); the analysis never counts those last two as the local's win. Do not assume the local endpoint wins: requests may still forward to Framework, or a tie may fail as ambiguous. Read the conflict evidence before treating the local endpoint as the one serving the URL. |341342A `LocalVersusLocal` entry deserves investigation, not automatic exclusion from a wave. Its `evidence`343distinguishes a proven swallowing `IgnoreRoute`, a possible Framework overlap, and a Core tie that344nothing readable separates — the last of which is a bug in the destination unless a selector policy345this analysis cannot see tells the two apart, and worth fixing before more traffic is pointed at it.346347**An empty `conflicts` array is only evidence if the proxy was read.** Check `proxyStatus`348on the report before drawing any conclusion from it, and before trusting an ownership349verdict that depends on proxy coverage:350351| `proxyStatus` | What it means |352|---------------|---------------|353| `Read` | The proxy was parsed. An empty `conflicts` array means no modeled conflict was found, not that runtime ambiguity is impossible. |354| `NotSupplied` | No proxy project was named, so nothing proxy-related was evaluated. Routes that depend on proxy coverage will be `Unknown (NoProxySupplied)`; `Ignored` verdicts are decided on the Framework side alone and still stand. Re-run with `proxyProjectPath` to get real answers. |355| `Unreadable` | A proxy project was named but would not load. Fix that before reading the report — this is not the same as there being no conflicts. |356| `NotEvaluated` | The scan stopped before the proxy was opened, because the Framework project itself would not load. Read `unresolved` for the reason; supplying a different proxy path will not help. |357358**An empty `routes` array does not mean the project has no routes.** It means none were359read. When `proxyStatus` is `NotEvaluated`, the Framework project itself did not load and360nothing was inventoried at all. When `unresolved` carries `MalformedSource`,361`UnsupportedRegistrationApi`, or `UnresolvedSymbol`, registrations exist that are missing362from `routes`. In either case the report is silent about routes that are still serving363traffic, so it cannot support retiring `RouteConfig.cs` or calling a migration finished.364365## Environment-specific proxy configuration366367Routes read from `appsettings.Development.json` (or any other environment file) are reported with the file they368came from in `source.filePath`; a `CorsPolicy`, `Match.Methods` or `Order` merged in from the file a run loads beside369it is named, with that file, in a `ConfigDrivenGating` entry. Which file wins is a deployment fact the repository does370not record — **a route that only exists in Development is not one production serves.** Check the file before planning.371372## Using the report to plan a wave3733741. Run the tool against both projects.3752. If `unresolved` is non-empty, resolve what you can and state the rest as known gaps.376 Do not plan around an inventory you know is partial without saying so.3773. Take the `Forwarded` routes **and every `Partial` route** as the candidate pool.378 Investigate `LocalVersusLocal` entries before excluding anything: a conditional earlier379 registration or one sharing only GET can leave the later route live for other traffic.380 Exclude a candidate only after independently confirming it is unreachable.3814. Group candidates by controller or area, not by route count. Routes that share a382 controller move together or break each other. Group a Framework route by its `expansion`383 rows (template, `httpMethods`, `area` where present, controller, action, `isCertain`), not by its defaults. A384 route's own `httpMethods` is its method constraint (never read for `kind: "Ignore"`, whose385 `[]` says nothing about verbs); a request with another verb falls through to the next386 route, so two same-template routes with disjoint verbs are separate slices. A row with387 `isCertain: false` is one the route may reach (an area it cannot rule out, a shorter388 URL dropping a constrained optional segment, or an action whose selection is uncertain:389 ambiguous same-verb actions or overloads, host metadata, a custom or unbound verb390 provider; a custom MVC method selector stays certain, since the route already391 dispatched when it declines) or one it matches and then dispatches nothing (its verbs392 are the route's, shared with no action verb): keep it in the space a deletion must393 cover, but never read it as that action serving those verbs. Only Framework routes394 carry `expansion`; `expansion: []` means the route was expanded and reaches no action.395 A missing `expansion` (with or without `expansionOmitted: true`, meaning its rows396 exceeded the report's budget) leaves no rows: treat the whole template as one slice.3975. For each `Partial` route in the pool, identify the remaining slice specifically. This398 is where a wave silently leaves URLs behind.3996. After the wave, re-run and exercise the changed URLs and verbs. When conventional400 action enumeration is available and coverage and forwarder precedence are readable, a401 fully moved route can return `Terminated` at `basis: "Enumerated"`. Core pipeline code can402 instead withhold it as `Unknown` at `OpaqueRegistrar`; load403 [ref/pipeline-code.md](ref/pipeline-code.md), since re-running alone will not clear it. The scaffold's404 `MapForwarder(...).WithOrder(int.MaxValue)` provides a readable last-resort order, not405 proof that every route migrated. Attribute routes need no conventional expansion, so406 not every migrated route has an enumerated basis. Hand-rolled forwarders or unrecognized407 handlers need runtime confirmation: forwarding inside a referenced project can still408 leave a handler classified as local. In all cases, no verdict bypasses "Deleting a Framework409 route": check unresolved gaps, conflicts, and runtime host attribution. For `Partial`, inspect candidates and the410 remaining slice; for `Unknown` at `ProxyPrecedence`, check forwarder order, recognizability and the local's411 `acceptedContentTypes`, which no `Order` clears; for `Unknown` at `ProxyPathTransform`, load412 [ref/proxy-destinations.md](ref/proxy-destinations.md). Investigate `Unclaimed` as a possible routing gap, not proof of a live 404.413414## Deleting a Framework route415416Two verdicts license deletion, and each has preconditions. Both speak only to inbound417matching: a route that can never match still generates URLs. Generation selects a route by418name — `Url.RouteUrl("live")`, the three-argument `GetVirtualPath` — where deleting it419throws `A route named 'live' could not be found`; or by route values — `Html.ActionLink`,420`Url.Action`, the two-argument `GetVirtualPath` — which walks the collection for the first421route that can build the URL, so deleting it silently returns `null`, a different URL, or422the same URL from another route, naming neither the route nor its object. The report423inventories neither kind. Under either verdict, deletion must change no URL the application424depends on and break no consumer, named or not: searching for the name and for direct425references starts that, and comparing generated URLs is evidence, not proof —426`GetVirtualPath` returns the selected route and its data tokens, not just a string, so a427consumer reading either can break while the URLs compare equal. Preserve or retire every428consumer you find, and where you cannot establish it, do not delete.429430`Terminated` licenses it when **all** of the following hold:431432- The report was produced with `proxyProjectPath` supplied.433- No unresolved gap can affect that route or its proposed Core replacement. Check both the434 route ID and every ID in `terminatedBy` against `unresolved[].affectedRouteIds`. Entries435 with no affected IDs are unscoped gaps, not harmless ones; resolve them or establish that436 they cannot affect this URL space before deleting anything.437- No Core route named in the route's `terminatedBy` appears in any438 `conflicts[].participantIds`. A `Terminated` verdict already means no forwarder was found439 to preempt that endpoint, so a surviving conflict is one the analysis judged the endpoint440 to win, or one it does not decide. Confirm the endpoint in `terminatedBy` answers.441- Other-project code that a `terminatedBy` handler reaches, or that is handed the application or an endpoint builder, does not answer or forward first; where you cannot establish that, do not delete.442- Inspect references in `redirectTargetIds` and confirm redirects still reach their443 intended destination on Core. A preserved destination URL can outlive its Framework444 registration; a removed destination cannot.445446Before deletion, exercise representative URLs and verbs against the deployed Core routing table,447including host restrictions, content types and competing endpoints. The static report models neither every448runtime convention nor every Core-local ambiguity — an empty `conflicts` array proves nothing.449Nor does it see every assembly in `bin`. It reads references, package runtime assets and copied450content files, and `Content` or `None` items that copy an assembly to the output. It cannot see451one a custom `Copy` task, a package's `build/` targets or a post-build step puts there, so before452deleting, compare the deployed `bin` against what the project declares.453454A conflict naming the *Framework* route itself does not block deletion: it describes the455Framework side — a route or `IgnoreRoute` shadowing this one, or a Core fallback answering456whatever reaches it — and changes nothing about whether `terminatedBy` serves the space.457458`Ignored` licenses it only when `kind` is **not** `Ignore`. An earlier `IgnoreRoute` on the459same surface swallows such a route before it can match, and the scan models registration460only, so that verdict rests on the ignore still swallowing it when the request arrives.461**Establish that it still does — in every deployment the ignore precedes this route on the462same active surface and matches every request the route would an463464…(truncated)