dotnet-inspect: performance analysis and triage

Use this skill to find the members worth optimizing or hardening first in a .NET assembly, and to triage them against actionable rewrite shapes. This analysis is experimental; section names and signal sets may change between releases.

bash

dnx dotnet-inspect -y -- <command>

Rank by leverage first

Top Leverage

ranks members by call-graph leverage: direct callers,

Root Reach

(distinct entry points that transitively reach a member), fanout, depth, and loop calls. Start here on a whole library, then narrow to a type.

bash

dnx dotnet-inspect -y -- library MyLib.dll -S "Top Leverage"
dnx dotnet-inspect -y -- type MyType --library MyLib.dll --all -S "Top Leverage"

Ranking rows carry a copyable

Stable

selector,

Visibility

, and

Selector

. Add

--all

to include non-public members.

Triage against rewrite shapes

Library triage is split into kind-scoped sections under

@Performance

(

Performance: Boxing

Performance: Arrays

Performance: Closures and delegates

, and more). Start with discovery or counts, then select the group or one concrete kind. Type/member scope keeps the focused

Performance Triage

lens.

bash

dnx dotnet-inspect -y -- library MyLib.dll -D @Performance
dnx dotnet-inspect -y -- library MyLib.dll -S @Performance --count
dnx dotnet-inspect -y -- library MyLib.dll -S "Performance: Boxing" --jsonl
dnx dotnet-inspect -y -- library MyLib.dll -S "Performance:*" \
  --loop --min-confidence high --top 20 --tsv
dnx dotnet-inspect -y -- library MyLib.dll \
  --triage-shape scan-method-in-loop-call,linq-scan-in-loop,string-build-in-loop \
  --top 20 --tsv
dnx dotnet-inspect -y -- library MyLib.dll --triage-shape capturing-delegate --top 10 --jsonl

Target IL-visible costs (allocations: box, newarr, delegate newobj, ToArray/ToList/Concat), not JIT-handled concerns (isinst/castclass folding, devirtualization, bounds-check elimination, null-check folding).

Use

--loop

for repeated hot costs,

--min-confidence high|medium|low

for a confidence floor,

--triage-shape

for one or more shapes, and

--top N

for the curated ranked prefix. Supplying any of those flags selects the applicable performance lens automatically. In library row formats,

Performance:*

flattens two or more populated kind sections into one table with a leading

Kind

column. If filtering leaves one populated kind, row formats use that kind's concrete schema without

Kind

; use structured

--json

when the kind discriminator must remain explicit.

@Performance

also includes heterogeneous sections, so use it for discovery, counts, Markdown, or JSON documents instead.

--top

narrows ranked data before rendering;

--rows N

caps rendered rows afterward. Common shapes include

capturing-delegate

box-value-type

small-array

linq-scan-in-loop

scan-method-in-loop-call

(a linear-scan helper invoked from a caller loop),

materialize-in-loop

(a loop-invariant

ToArray

ToList

that can be hoisted),

string-build-in-loop

enumerator-allocation

async-state-machine

, and

allocation-hotspot

. Query the algorithmic shapes explicitly:

scan-method-in-loop-call

stays low-confidence because static analysis cannot prove that the scanned sequence grows with the caller's loop, so a

--min-confidence high

pass intentionally excludes it.

For registry, pipeline, or object-graph construction that does not match a local rewrite shape, opt into the aggregate allocation fanout:

bash

dnx dotnet-inspect -y -- library MyLib.dll \
  --triage-shape allocation-fanout \
  --order-by "OncePaths desc" --top 20 --tsv

Direct Sites

is local to the method.

Once Paths

composes exact intra-assembly callsites and counts repeated callsites separately; conditional, repeated, unknown, cached, and opaque paths remain separate columns. Treat this as IL-visible normal-return-path quantity, not runtime bytes or observed frequency. A high

Opaque Paths

count means virtual, external, delegate, recursive, or runtime-library work still needs a drill or profiler.

Exact rows retain machine-readable provenance from the native Analysis producer in structured JSON:

Candidate

Finding

(

analysis.allocation

analysis.call-site

Provenance=exact

Operation

Token

, and

IL

. Use these fields for runtime/static joins or to carry one triage row into the matching

diff

timeline

confirmation workflow without parsing

Evidence

text:

bash

dnx dotnet-inspect -y -- library MyLib.dll -S "Performance:*" \
  --where "Finding=analysis.allocation" --where "Operation=box" --json
dnx dotnet-inspect -y -- library MyLib.dll -S "Performance:*" \
  --where "Finding=analysis.call-site" --json

Aggregate rows such as

allocation-hotspot

use

Provenance=aggregate

and have a

pt~

candidate id but no exact source Finding, operation, or token.

Provenance=unmatched

flags an instruction-level row that did not join to the expected producer census.

Select direct caller-loop repetition

A once-per-call allocation can still be repeated by an upstream caller's loop. Select rows with an exact direct invocation receipt:

bash

dnx dotnet-inspect -y -- library MyLib.dll -S "Performance:*" \
  --where "CallerLoop=direct" --json

CallerLoopDepth

and

CallerLoopWitness

identify the deterministic invocation site. This evidence does not change the row's local

Loop

, multiplicity, confidence, weight, candidate identity, or default rank. Use it to select a candidate for profiling, not as proof that the caller is hot or that the loop executes.

Only resolved invocation edges qualify. Function loads and callback registration do not prove callback execution, and recursive traversal does not prove realized depth or frequency. Do not infer either case into caller-loop evidence; require runtime evidence or a stronger product-owned invocation contract.

Triage exception-path pool churn

Select the explicit

Resource Triage

library section to find

ArrayPool<T>

acquisitions whose exact def-use path reaches an external-input boundary before modeled cleanup:

bash

dnx dotnet-inspect -y -- library MyLib.dll -S "Resource Triage" --jsonl

Treat

pool-churn-on-exception

as a profiling and hardening candidate, not a permanent-memory-leak or memory-corruption accusation. Static analysis proves the unprotected boundary shape and API evidence, not runtime frequency. Use

Candidate

Finding=analysis.resource-lifecycle

Acquire IL

Boundary IL

, and

Boundary

to retain exact provenance while drilling the method. Each boundary is one row; a multi-boundary candidate repeats its candidate and acquisition fields so every operation stays paired with its own IL offset.

Not every shape is a pure hot-path win.

async-state-machine

is reported as amortized (low confidence) unless the allocation sits in a loop: async lowering moves work into a state object rather than eliminating it, often once per call/enumeration/subscription. Treat amortized rows as context, and confirm a real per-item cost with a profiler before optimizing.

Confirm when an allocation appeared

Correlate one method's native allocation census across caller-selected package cells:

bash

dnx dotnet-inspect -y -- timeline --package MyLib@1.0.0..2.0.0 \
  -t MyType -m HotPath \
  --finding analysis.allocation --at first --at last

Repeat

--at

for sparse probes or use

--at all

for an explicitly bounded dense traversal. These probes locate a candidate old/new boundary; they do not establish onset. Confirm one method's adjacent pair with Analysis's native allocation Findings:

bash

dnx dotnet-inspect -y -- diff --package MyLib@1.4.0..1.5.0 \
  -t MyType -m HotPath \
  --finding analysis.allocation

The method target must resolve at one or both endpoints.

PairFinding.Added

confirms an allocation occurrence was introduced, while

Present

Removed

, and

Changed

identify a wrong boundary, disappearance, or changed allocation facets. The command does not traverse versions; the caller owns the search policy and bound.

Trace a likely cause to a new call

After confirming an allocation boundary, compare the same caller method's direct-call census:

bash

dnx dotnet-inspect -y -- diff --package MyLib@1.4.0..1.5.0 \
  -t MyType -m HotPath \
  --finding analysis.call-site

The target method is the caller and each row identifies a callee.

PairFinding.Added

confirms a new call occurrence, such as a newly introduced

Enumerable.ToArray

Changed

can show that an existing call moved into a loop or changed dispatch/opcode facets. Use the single-version

Calls

section while probing versions; use this final adjacent comparison as the onset proof.

Drill a candidate

Call Graph

is a bounded bidirectional graph: inbound callers up to entry points and outbound calls, centred on the selected member. Project per-node cost with

--fields

(alloc, copy, unsafe, reflection, throw/exception, catch/finally). Its default Markdown edge table is best for comparing relationships and cost cues. Use

--tree

when the path toward or away from the candidate matters,

--mermaid

for a standalone diagram, or

--markdown --mermaid

to embed the diagram. Use

--tsv

--jsonl

when a script will consume the same edge rows. Requested cost cues remain annotations in the node labels; they do not become separate machine columns.

bash

dnx dotnet-inspect -y -- member MyType Method:1 --library MyLib.dll -S "Call Graph,Facts"
dnx dotnet-inspect -y -- member MyType Method:1 --library MyLib.dll -S "Call Graph" --fields "Throw,Catch,Finally"
dnx dotnet-inspect -y -- member MyType Method:1 --library MyLib.dll -S "Call Graph" --fields "Alloc,Loop" --tree
dnx dotnet-inspect -y -- member MyType Method:1 --library MyLib.dll -S "Call Graph" --jsonl

dotnet-inspect-performance

NPX Install

Tags

SKILL.md Content

dotnet-inspect: performance analysis and triage

Rank by leverage first

Triage against rewrite shapes

Select direct caller-loop repetition

Triage exception-path pool churn

Confirm when an allocation appeared

Trace a likely cause to a new call

Drill a candidate