跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

snowbank-contracts

How to guard arguments and assert invariants with the Contract family in SnowBank.Core (namespace SnowBank.Diagnostics.Contracts): the argument guards (Contract.NotNull / NotNullOrEmpty / NotNullOrWhiteSpace / Positive / GreaterThan / GreaterOrEqual / LessThan / LessOrEqual / EqualTo / NotEqualTo / ValueNotNull) that validate a caller's arguments and throw ArgumentNullException / ArgumentException / ArgumentOutOfRangeException, versus the condition assertions (Contract.Requires / Assert / Ensures / Invariant / Fail) that check internal invariants and throw ContractException, plus the three compile levels (always-on Contract.X, Debug-only Contract.Debug.X, Paranoid.X under PARANOID_ANDROID), the CallerArgumentExpression auto-message, the nullable-flow and StackTraceHidden behavior, and the NUnit test integration. Use whenever code validates a method argument, replaces a hand-written `if (x == null) throw new ArgumentNullException(...)` or `Debug.Assert(...)` or `ArgumentNullException.Th

SnowBankSDK · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add SnowBankSDK/foundationdb-dotnet-client --skill snowbank-contracts

技能说明


name: snowbank-contracts description: >- How to guard arguments and assert invariants with the Contract family in SnowBank.Core (namespace SnowBank.Diagnostics.Contracts): the argument guards (Contract.NotNull / NotNullOrEmpty / NotNullOrWhiteSpace / Positive / GreaterThan / GreaterOrEqual / LessThan / LessOrEqual / EqualTo / NotEqualTo / ValueNotNull) that validate a caller's arguments and throw ArgumentNullException / ArgumentException / ArgumentOutOfRangeException, versus the condition assertions (Contract.Requires / Assert / Ensures / Invariant / Fail) that check internal invariants and throw ContractException, plus the three compile levels (always-on Contract.X, Debug-only Contract.Debug.X, Paranoid.X under PARANOID_ANDROID), the CallerArgumentExpression auto-message, the nullable-flow and StackTraceHidden behavior, and the NUnit test integration. Use whenever code validates a method argument, replaces a hand-written if (x == null) throw new ArgumentNullException(...) or Debug.Assert(...) or ArgumentNullException.ThrowIfNull(...), adds a precondition or state invariant, chooses between Contract, Contract.Debug and Paranoid, or hits a ContractException. Prefer these over raw throws and BCL asserts in SnowBank.Core / FoundationDB.Client code.

Contract (SnowBank.Diagnostics.Contracts)

Contract is the guard and assertion family used across SnowBank.Core and FoundationDB.Client. It replaces raw throw new ArgumentNullException(...), ArgumentNullException.ThrowIfNull(...), ArgumentOutOfRangeException.ThrowIf*, and System.Diagnostics.Debug.Assert(...). The namespace is SnowBank.Diagnostics.Contracts; it is a global using in the SnowBank projects, add using SnowBank.Diagnostics.Contracts; in a consumer.

There are two families, and they are not interchangeable:

  1. Argument guards (Contract.NotNull, Positive, GreaterThan, ...) validate arguments that come from OUTSIDE the method. They are the logical equivalent of if (cond) throw new Argument...Exception(...). A failure means the CALLER passed a bad argument. Always on (Debug and Release). Each throws the matching Argument* exception.
  2. Condition assertions (Contract.Requires, Assert, Ensures, Invariant, Fail) check a condition that must NEVER be false, an invariant of your own code. A failure means the component itself has a bug. Each throws ContractException.

The rule for choosing: ask who can trigger it. A caller outside the type gets an argument guard. Your own code breaking its own invariant gets Contract.Debug.Requires for a dev-time check, or an explicit if (...) throw when the invariant must hold at run time (section 3).


1. Argument guards

Use these to validate public-API arguments. Each captures the argument name on its own (see section 5), takes an optional message as the second argument, and throws the exception below.

GuardReplacesThrows
Contract.NotNull(x)if (x == null) throw new ArgumentNullException(...)ArgumentNullException
Contract.NotNullOrEmpty(s) (string)null + s.Length == 0ArgumentNullException (null) / ArgumentException (empty)
Contract.NotNullOrWhiteSpace(s)string.IsNullOrWhiteSpace(s)ArgumentNullException (null) / ArgumentException (blank)
Contract.NotNullOrEmpty(collection)null + emptyArgumentNullException / ArgumentException
Contract.NotEmpty(collection).Count == 0ArgumentException
Contract.Positive(n)if (n <= 0) throw ...ArgumentException
Contract.PowerOfTwo(n)bit checkArgumentException
Contract.GreaterThan(n, t) / GreaterOrEqual / LessThan / LessOrEqualcompare + throwArgumentOutOfRangeException
Contract.EqualTo(x, v) / NotEqualTo(x, v)compare + throwArgumentException
Contract.ValueNotNull(x)null check that returns xArgumentNullException
Contract.PointerNotNull(p) (unsafe)p == nullArgumentNullException
public void Load(Root root, int count)
{
    Contract.NotNull(root);
    Contract.Positive(count);
    // root is non-null from here (section 5)
}

ValueNotNull returns its argument, for a single-line setter:

public string Name
{
    get => this.name;
    set => this.name = Contract.ValueNotNull(value, "Name cannot be null");
}

Numeric guards exist for int, long, double, float (and uint / ulong for PowerOfTwo). NotNullOrEmpty / NotEmpty have overloads for arrays, collections, Slice, and ArraySegment<T>. NotNullAllowStructs<T> is [Obsolete]; call NotNull.

Non-trivial check: when the check is heavy (for example a SequenceCompareTo bound check at a public entry point), write a plain if (...) throw with a message, not a Contract call.

2. Condition assertions

Use these for a condition that must never be false. They throw ContractException.

MethodMeaning
Contract.Requires(cond)precondition at the start of a method
Contract.Assert(cond)assertion inside a method body
Contract.Ensures(cond)postcondition at the end
Contract.Invariant(cond)an invariant that must always hold
Contract.Fail(message, ex?)fail unconditionally (returns never)

Do NOT use Contract.Requires to validate a public argument. It throws ContractException, which signals an internal bug, not a caller error. Public arguments get the typed guards in section 1, which throw the correct Argument* exception.

For an internal invariant, the common form is the Debug variant Contract.Debug.Requires (section 3), not the always-on Contract.Requires. See section 3 for when to use an explicit if (...) throw instead.

3. Three levels, by cost of the check

The same method set exists at three compile levels. Pick by how much you are willing to pay at run time.

| Level | Compiled | Use for | |--

阅读完整来源 ↗