LinqContraband 5.14.0

LinqContraband

<div align="center">

Stop Smuggling Bad Queries into Production

</div>

Compile-time EF Core LINQ performance analyzer for .NET — a high-signal Roslyn analyzer that catches N+1 queries, client-side evaluation, premature materialization, sync-over-async, missing AsNoTracking, raw SQL injection risks, and other DbContext query issues in the editor and CI—not production.

The problem

Entity Framework Core and LINQ compile cleanly even when the query shape will hurt production. An N+1 Find inside a loop, ToList() before Where, a local method that forces client-side evaluation, sync-over-async on DbContext, or FromSqlRaw($"...") only fail under load, at 3 AM, or as a security incident.

Runtime profilers and code review miss what static analysis can prove from your IQueryable chains and EF Core API usage.

What it catches

LinqContraband reports proven EF Core LINQ and DbContext pitfalls early:

• N+1 database execution inside loops (Find, materializers, explicit load)
• premature materialization (ToList/AsEnumerable before filters)
• client-side evaluation risk from non-translatable local methods
• sync-over-async EF Core calls in async methods
• missing or misused AsNoTracking (tracking tax, silent writes, mixed modes)
• Cartesian explosion and missing/excessive Include paths
• SaveChanges inside loops and nested SaveChanges
• raw SQL injection patterns (FromSqlRaw / ExecuteSqlRaw interpolation)
• DbContext lifetime and concurrent same-context operations
• unbounded materialization, projection waste, and pagination without OrderBy

When the analyzer cannot prove an EF-backed query shape statically, it stays quiet. High-signal feedback, not noisy guesses.

Try it on your code first

Scan a solution without changing it (.NET 10 SDK):

dnx LinqContraband.Scan

The scanner builds the solution in the current directory with the analyzers injected. It then prints which rules fired, how often, and in which files, and writes a SARIF file you can upload to GitHub code scanning. On .NET 8 or 9, install it once with dotnet tool install -g LinqContraband.Scan and run linqcontraband-scan.

Install

dotnet add package LinqContraband

That adds the latest release. To edit the project file by hand instead, use the version shown on the NuGet badge:

<PackageReference Include="LinqContraband" Version="x.y.z" PrivateAssets="all" />

No runtime dependency is added to your app. LinqContraband runs as a Roslyn analyzer during build and in supported IDEs (Visual Studio, Rider, VS Code / C# Dev Kit) and CI.

Install only from NuGet or from this repository. LinqContraband ships as the LinqContraband analyzer package and the LinqContraband.Scan .NET tool, both on NuGet. It is not distributed as a standalone ZIP installer or executable; treat third-party ZIP downloads as untrusted.

• Official package: nuget.org/packages/LinqContraband
• Canonical source: github.com/georgepwall1991/LinqContraband
• Documentation: georgepwall1991.github.io/LinqContraband

A taste

// LC002: ToList() pulls every order into memory, then filters in C#.
var slow = db.Orders.ToList().Where(o => o.DueDate < today);

// Fix (offered as a code fix): filter in SQL, then materialize.
var fast = db.Orders.Where(o => o.DueDate < today).ToList();

// LC007: one database round trip per customer (N+1).
foreach (var id in customerIds)
    customers.Add(db.Customers.Find(id));

// Fix: one query for the whole set.
customers = db.Customers.Where(c => customerIds.Contains(c.Id)).ToList();

Every diagnostic's help link in your IDE opens the rule's page, which shows the problem, the fix, and the cases the rule deliberately leaves alone.

See it work

Product-flow diagrams from real sample diagnostics and shipped LC message formats:

1. Build / IDE diagnostics (EF Core LINQ)

2. Before / after code fix (premature materialization)

3. Product loop — analyzer in IDE and CI

30-second path

1. Reference the package with PrivateAssets="all".
2. Keep writing EF Core LINQ as usual (DbSet, IQueryable, Include, SaveChanges).
3. Build as usual, in the IDE or with dotnet build. The analyzers run as part of the compiler.
4. Fix any LC00x warnings (many have code fixes).
5. Optionally promote critical rules to error in .editorconfig (see Configuration below).

Feature snapshot

Compatibility

• .NET / Roslyn hosts: Visual Studio, Rider, VS Code (C# Dev Kit), and dotnet build / CI
• EF Core: Modern Entity Framework Core versions used with C# IQueryable / DbContext APIs
• Package kind: Development dependency analyzer (PrivateAssets="all"); no app runtime package

Rules

56 rules, 39 with automatic code fixes. Each rule links to its full page: what it flags, why it matters, how to fix it, and where it deliberately stays quiet.

Browse the same rules grouped by failure mode in the rule catalog, or start from a topic guide:

• N+1 query detector and SaveChanges in loops
• Client-side evaluation and premature materialization
• Include and eager loading and projection
• AsNoTracking and change tracking and DbContext lifetime
• Async queries and CancellationToken
• Raw SQL injection, ExecuteUpdate, and pagination OrderBy
• EF Core query performance checklist

Configuration

Pick a preset with one line in your project file (or Directory.Build.props):

<PropertyGroup>
  <LinqContrabandPreset>security</LinqContrabandPreset>
</PropertyGroup>

Combine presets with ;, for example security;essentials. Your own .editorconfig entries still win over a preset.

Or set any rule's severity yourself in .editorconfig:

[*.cs]
dotnet_diagnostic.LC001.severity = error
dotnet_diagnostic.LC002.severity = error
dotnet_diagnostic.LC003.severity = warning

# Optional rule-specific thresholds (defaults: 4 and 3)
dotnet_code_quality.LC038.include_threshold = 6
dotnet_code_quality.LC042.query_operator_threshold = 5

Advisory rules default to Info, so they show up as IDE hints without drowning out the higher-confidence warnings. dotnet build does not print Info diagnostics; to see them on the command line, use the strict preset (it raises them to warnings) or write a SARIF log with -p:ErrorLog=linqcontraband.sarif.

LinqContraband also hides the .NET SDK's culture and string-comparison warnings (CA1862, CA1304, CA1305, CA1307, CA1309, CA1310, CA1311) inside EF Core query lambdas, where their suggested StringComparison or CultureInfo overloads cannot be translated to SQL and would make the query throw. In-memory LINQ keeps them. To keep one inside queries as well, add its suppression id (LCS plus the CA number, such as LCS1862) to <NoWarn>; see LC014.

Run it in CI

LinqContraband runs inside the normal dotnet build, so a CI job needs no database, service container, or extra tool:

- run: dotnet restore
- run: dotnet build --configuration Release --no-restore

Use the security or critical preset (see Configuration) to block pull requests on the rules that matter most, or promote individual rules to error in .editorconfig. The CI guide covers a gradual rollout.

Contributing

Found a new way to smuggle bad queries? Open an issue or send a pull request. The contributing guide explains how to add or change a rule.

License: MIT