CryptoHives.Foundation.Threading.Analyzers 0.5.34-preview

🛡️ CryptoHives Open Source Initiative 🐝

An open, community-driven cryptography and performance library collection for the .NET ecosystem, developed and maintained by The Keepers of the CryptoHives.

CryptoHives.Foundation.Threading.Analyzers

Roslyn analyzers that detect common ValueTask misuse patterns at compile time — helping you avoid subtle bugs, undefined behavior, and performance pitfalls when working with ValueTask and pooled async primitives.

Note: These analyzers are automatically included in the CryptoHives.Foundation.Threading package. Install this package separately only if you need the analyzers without the Threading library.

📦 Installation

dotnet add package CryptoHives.Foundation.Threading.Analyzers

Or as a development-only dependency (no runtime reference):

<PackageReference Include="CryptoHives.Foundation.Threading.Analyzers"
                  Version="*"
                  PrivateAssets="all" />

🔍 Diagnostic Rules

❌ Anti-Patterns Detected

// CHT001: Multiple await — Error
ValueTask vt = GetValueTask();
await vt;
await vt; // Error: already consumed

// CHT002: Blocking call — Warning
ValueTask vt = GetValueTask();
vt.GetAwaiter().GetResult(); // Warning: undefined behavior

// CHT003: Stored in field — Warning
private ValueTask _task; // Warning: may be consumed multiple times

// CHT004: Multiple AsTask() — Error
ValueTask vt = GetValueTask();
var t1 = vt.AsTask();
var t2 = vt.AsTask(); // Error: already consumed

// CHT005: Direct .Result — Warning
ValueTask<int> vt = GetValueTask();
int result = vt.Result; // Warning: undefined behavior

// CHT006: Passed to unsafe method — Warning
await Task.WhenAll(GetValueTask()); // Warning: use AsTask() or Preserve()

// CHT007: AsTask() before signaling — Info (performance)
Task t = someAsyncLock.LockAsync().AsTask();
// ... other work ...
await t; // Info: storing AsTask() before signal causes 10–100x slowdown

// CHT008: Unconsumed — Warning
GetValueTask(); // Warning: result not awaited or discarded

✅ Correct Patterns

// Single await — correct
await GetValueTask();

// Store, then single await — correct
ValueTask vt = GetValueTask();
await vt;

// Preserve() for safe multiple consumption
ValueTask preserved = GetValueTask().Preserve();
await preserved;
await preserved; // Safe — Preserve() wraps in a reusable Task

// AsTask() once, reuse the Task
Task t = GetValueTask().AsTask();
await t;
await t; // Task can be awaited multiple times

// Pass to WhenAll via AsTask()
await Task.WhenAll(
    GetValueTask().AsTask(),
    GetValueTask().AsTask());

// Explicit discard
_ = GetValueTask();

🔧 Automatic Code Fixes

The analyzer package includes code fixes for most diagnostics:

⚙️ Configuration

Adjust rule severity in .editorconfig:

# Promote CHT007 from info to warning
dotnet_diagnostic.CHT007.severity = warning

# Disable CHT003 entirely
dotnet_diagnostic.CHT003.severity = none

Suppress inline when necessary:

#pragma warning disable CHT002
valueTask.GetAwaiter().GetResult(); // intentional blocking call
#pragma warning restore CHT002

📚 Documentation

🔐 Security Policy

If you discover a vulnerability, please do not open a public issue. Follow the guidelines on the CryptoHives Security Page.

⚖️ License

MIT — © 2026 The Keepers of the CryptoHives