-
Notifications
You must be signed in to change notification settings - Fork 1.6k
/
ContractArgumentValidatorAttribute.xml
124 lines (112 loc) · 8.27 KB
/
ContractArgumentValidatorAttribute.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
<Type Name="ContractArgumentValidatorAttribute" FullName="System.Diagnostics.Contracts.ContractArgumentValidatorAttribute">
<TypeSignature Language="C#" Value="public sealed class ContractArgumentValidatorAttribute : Attribute" />
<TypeSignature Language="ILAsm" Value=".class public auto ansi sealed beforefieldinit ContractArgumentValidatorAttribute extends System.Attribute" />
<TypeSignature Language="DocId" Value="T:System.Diagnostics.Contracts.ContractArgumentValidatorAttribute" />
<TypeSignature Language="VB.NET" Value="Public NotInheritable Class ContractArgumentValidatorAttribute
Inherits Attribute" />
<TypeSignature Language="F#" Value="type ContractArgumentValidatorAttribute = class
 inherit Attribute" />
<TypeSignature Language="C++ CLI" Value="public ref class ContractArgumentValidatorAttribute sealed : Attribute" />
<AssemblyInfo>
<AssemblyName>System.Diagnostics.Contracts</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.3.0</AssemblyVersion>
<AssemblyVersion>4.0.4.0</AssemblyVersion>
<AssemblyVersion>5.0.0.0</AssemblyVersion>
<AssemblyVersion>6.0.0.0</AssemblyVersion>
<AssemblyVersion>7.0.0.0</AssemblyVersion>
<AssemblyVersion>8.0.0.0</AssemblyVersion>
<AssemblyVersion>9.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>2.0.5.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.1.0.0</AssemblyVersion>
</AssemblyInfo>
<TypeForwardingChain>
<TypeForwarding From="mscorlib" FromVersion="4.0.0.0" To="System.Diagnostics.Contracts" ToVersion="0.0.0.0" FrameworkAlternate="dotnet-uwp-10.0" />
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Diagnostics.Contracts" ToVersion="5.0.0.0" FrameworkAlternate="net-5.0" />
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Diagnostics.Contracts" ToVersion="6.0.0.0" FrameworkAlternate="net-6.0" />
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Diagnostics.Contracts" ToVersion="7.0.0.0" FrameworkAlternate="net-7.0" />
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Diagnostics.Contracts" ToVersion="8.0.0.0" FrameworkAlternate="net-8.0" />
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Diagnostics.Contracts" ToVersion="9.0.0.0" FrameworkAlternate="net-9.0" />
</TypeForwardingChain>
<Base>
<BaseTypeName>System.Attribute</BaseTypeName>
</Base>
<Interfaces />
<Attributes>
<Attribute>
<AttributeName Language="C#">[System.AttributeUsage(System.AttributeTargets.Method, AllowMultiple=false)]</AttributeName>
<AttributeName Language="F#">[<System.AttributeUsage(System.AttributeTargets.Method, AllowMultiple=false)>]</AttributeName>
</Attribute>
<Attribute>
<AttributeName Language="C#">[System.Diagnostics.Conditional("CONTRACTS_FULL")]</AttributeName>
<AttributeName Language="F#">[<System.Diagnostics.Conditional("CONTRACTS_FULL")>]</AttributeName>
</Attribute>
</Attributes>
<Docs>
<summary>Enables the factoring of legacy <see langword="if-then-throw" /> code into separate methods for reuse, and provides full control over thrown exceptions and arguments.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
If your code uses explicit `if-then-throw` code to validate parameters, you may be employing helper methods that perform checks and throw particular exceptions on failure, as shown in the following example.
:::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Contracts/ContractArgumentValidatorAttribute/Overview/ifthenthrow1.cs" id="Snippet1":::
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.diagnostics.contracts.contractargumentvalidatorattribute/vb/ifthenthrow1.vb" id="Snippet1":::
In this example, `Execute` has an elective precondition specifying that the parameter value should not be `null`. To enable the contract tools to recognize that the call to `ValidationHelper.NotNull` represents a contract, you can mark the called method with the <xref:System.Diagnostics.Contracts.ContractArgumentValidatorAttribute> attribute. The <xref:System.Diagnostics.Contracts.Contract.EndContractBlock%2A?displayProperty=nameWithType> method call should be used to enable the tools to extract the proper specifications for document generation and static checking, as follows.
:::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Contracts/ContractArgumentValidatorAttribute/Overview/ifthenthrow2.cs" id="Snippet2":::
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.diagnostics.contracts.contractargumentvalidatorattribute/vb/ifthenthrow2.vb" id="Snippet2":::
In addition to `if-then-throw` statements, the contract section of contract validator methods may contain calls to other contract validator methods. However, no other contracts (such as <xref:System.Diagnostics.Contracts.Contract.Requires%2A?displayProperty=nameWithType>, or <xref:System.Diagnostics.Contracts.Contract.Ensures%2A?displayProperty=nameWithType>) are allowed. Code that follows the <xref:System.Diagnostics.Contracts.Contract.EndContractBlock%2A?displayProperty=nameWithType> call is ignored by all contract tools.
The following example shows a range argument validator written in terms of an existing `NotNull` validator method.
:::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Contracts/ContractArgumentValidatorAttribute/Overview/ifthenthrow3.cs" id="Snippet3":::
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.diagnostics.contracts.contractargumentvalidatorattribute/vb/ifthenthrow3.vb" id="Snippet3":::
From a specification point of view, the `Execute` method has the following three contracts:
```
Contract.Requires<ArgumentNullException>(data != null);
Contract.Requires<ArgumentOutOfRangeException>(position >= 0);
Contract.Requires<ArgumentOutOfRangeException>(position < data.Length);
```
In standard methods, calls to contract validator methods can be freely mixed with other contracts such as <xref:System.Diagnostics.Contracts.Contract.Ensures%2A?displayProperty=nameWithType> or <xref:System.Diagnostics.Contracts.Contract.Requires%2A?displayProperty=nameWithType>.
]]></format>
</remarks>
</Docs>
<Members>
<Member MemberName=".ctor">
<MemberSignature Language="C#" Value="public ContractArgumentValidatorAttribute ();" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig specialname rtspecialname instance void .ctor() cil managed" />
<MemberSignature Language="DocId" Value="M:System.Diagnostics.Contracts.ContractArgumentValidatorAttribute.#ctor" />
<MemberSignature Language="VB.NET" Value="Public Sub New ()" />
<MemberSignature Language="C++ CLI" Value="public:
 ContractArgumentValidatorAttribute();" />
<MemberType>Constructor</MemberType>
<AssemblyInfo>
<AssemblyName>System.Diagnostics.Contracts</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.3.0</AssemblyVersion>
<AssemblyVersion>4.0.4.0</AssemblyVersion>
<AssemblyVersion>5.0.0.0</AssemblyVersion>
<AssemblyVersion>6.0.0.0</AssemblyVersion>
<AssemblyVersion>7.0.0.0</AssemblyVersion>
<AssemblyVersion>8.0.0.0</AssemblyVersion>
<AssemblyVersion>9.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>2.0.5.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.1.0.0</AssemblyVersion>
</AssemblyInfo>
<Parameters />
<Docs>
<summary>Initializes a new instance of the <see cref="T:System.Diagnostics.Contracts.ContractArgumentValidatorAttribute" /> class.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
</Members>
</Type>