mcs/class/corlib/Documentation/en/System.Diagnostics.Contracts/ContractOptionAttribute.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <Type Name="ContractOptionAttribute" FullName="System.Diagnostics.Contracts.ContractOptionAttribute">
   3   <TypeSignature Language="C#" Value="public sealed class ContractOptionAttribute : Attribute" />
   4   <TypeSignature Language="ILAsm" Value=".class public auto ansi sealed beforefieldinit ContractOptionAttribute extends System.Attribute" />
   5   <AssemblyInfo>
   6     <AssemblyName>mscorlib</AssemblyName>
   7     <AssemblyVersion>4.0.0.0</AssemblyVersion>
   8   </AssemblyInfo>
   9   <Base>
  10     <BaseTypeName>System.Attribute</BaseTypeName>
  11   </Base>
  12   <Interfaces />
  13   <Attributes>
  14     <Attribute>
  15       <AttributeName>System.AttributeUsage(System.AttributeTargets.All, AllowMultiple=true, Inherited=false)</AttributeName>
  16     </Attribute>
  17     <Attribute>
  18       <AttributeName>System.Diagnostics.Conditional("CONTRACTS_FULL")</AttributeName>
  19     </Attribute>
  20   </Attributes>
  21   <Docs>
  22     <remarks>
  23       <attribution license="cc4" from="Microsoft" modified="false" />
  24       <para>The following table shows the currently supported options.</para>
  25       <list type="table">
  26         <listheader>
  27           <item>
  28             <term>
  29               <para>Category</para>
  30             </term>
  31             <description>
  32               <para>Setting</para>
  33             </description>
  34             <description>
  35               <para>Value/effect</para>
  36             </description>
  37           </item>
  38         </listheader>
  39         <item>
  40           <term>
  41             <para>contract</para>
  42           </term>
  43           <description>
  44             <para>inheritance</para>
  45           </description>
  46           <description>
  47             <para>true to turn contract inheritance on; false to turn it off.  The default is true.</para>
  48           </description>
  49         </item>
  50         <item>
  51           <term>
  52             <para>runtime</para>
  53           </term>
  54           <description>
  55             <para>checking</para>
  56           </description>
  57           <description>
  58             <para>true to turn run-time checking on; false to turn it off. The default is true.</para>
  59           </description>
  60         </item>
  61       </list>
  62       <para>You can use this attribute as illustrated in the following examples.</para>
  63       <para>To turn off run-time checking for the entire assembly:</para>
  64       <code>[assembly:ContractOption("runtime", "checking", false)]</code>
  65       <para>To turn run-time contract checking on for a specific type:</para>
  66       <code>   [ContractOption("runtime", "checking", true)]
  67    class TypeWithRuntimeChecking {
  68
  69        ...
  70 </code>
  71       <para>To turn run-time checking off for a specific method:</para>
  72       <code>// Turn off all contract inheritance from interface IList&lt;T&gt;
  73 [ContractOption("contract", "inheritance", false)]
  74 class MyConcurrentList&lt;T&gt; : IList&lt;T&gt; {
  75    ...
  76 }
  77
  78 [ContractOption("runtime", "checking", false)]
  79 public override MyMethod(int x) {
  80    // no inherited contracts checked at runtime,
  81    // no invariants checked at runtime.
  82    ...
  83 }
  84
  85        [ContractOption("runtime", "checking", false)]
  86        public void MethodWithoutRuntimeChecking(...) {
  87           ...
  88        }
  89    }
  90 </code>
  91     </remarks>
  92     <summary>
  93       <attribution license="cc4" from="Microsoft" modified="false" />
  94       <para>Enables you to set contract and tool options at assembly, type, or method granularity.</para>
  95     </summary>
  96   </Docs>
  97   <Members>
  98     <Member MemberName=".ctor">
  99       <MemberSignature Language="C#" Value="public ContractOptionAttribute (string category, string setting, bool enabled);" />
 100       <MemberSignature Language="ILAsm" Value=".method public hidebysig specialname rtspecialname instance void .ctor(string category, string setting, bool enabled) cil managed" />
 101       <MemberType>Constructor</MemberType>
 102       <AssemblyInfo>
 103         <AssemblyVersion>4.0.0.0</AssemblyVersion>
 104       </AssemblyInfo>
 105       <Parameters>
 106         <Parameter Name="category" Type="System.String" />
 107         <Parameter Name="setting" Type="System.String" />
 108         <Parameter Name="enabled" Type="System.Boolean" />
 109       </Parameters>
 110       <Docs>
 111         <remarks>To be added.</remarks>
 112         <summary>
 113           <attribution license="cc4" from="Microsoft" modified="false" />
 114           <para>Initializes a new instance of the <see cref="T:System.Diagnostics.Contracts.ContractOptionAttribute" /> class by using the provided category, setting, and enable/disable value.</para>
 115         </summary>
 116         <param name="category">
 117           <attribution license="cc4" from="Microsoft" modified="false" />The category for the option to be set.</param>
 118         <param name="setting">
 119           <attribution license="cc4" from="Microsoft" modified="false" />The option setting.</param>
 120         <param name="enabled">
 121           <attribution license="cc4" from="Microsoft" modified="false" />true to enable the option; false to disable the option.</param>
 122       </Docs>
 123     </Member>
 124     <Member MemberName=".ctor">
 125       <MemberSignature Language="C#" Value="public ContractOptionAttribute (string category, string setting, string value);" />
 126       <MemberSignature Language="ILAsm" Value=".method public hidebysig specialname rtspecialname instance void .ctor(string category, string setting, string value) cil managed" />
 127       <MemberType>Constructor</MemberType>
 128       <AssemblyInfo>
 129         <AssemblyVersion>4.0.0.0</AssemblyVersion>
 130       </AssemblyInfo>
 131       <Parameters>
 132         <Parameter Name="category" Type="System.String" />
 133         <Parameter Name="setting" Type="System.String" />
 134         <Parameter Name="value" Type="System.String" />
 135       </Parameters>
 136       <Docs>
 137         <remarks>
 138           <attribution license="cc4" from="Microsoft" modified="false" />
 139           <para>There are only two category/setting options, and they can be set by either of the constructor overloads. You can use this overload with the same settings as the <see cref="M:System.Diagnostics.Contracts.ContractOptionAttribute.#ctor(System.String,System.String,System.Boolean)" /> overload by specifying "true" or "false" in string format; for example:</para>
 140           <code>[ContractOption("contract", "inheritance", “false”)]
 141 class MyConcurrentList&lt;T&gt; : IList&lt;T&gt; {
 142    ...
 143 }
 144 </code>
 145         </remarks>
 146         <summary>
 147           <attribution license="cc4" from="Microsoft" modified="false" />
 148           <para>Initializes a new instance of the <see cref="T:System.Diagnostics.Contracts.ContractOptionAttribute" /> class by using the provided category, setting, and value.</para>
 149         </summary>
 150         <param name="category">
 151           <attribution license="cc4" from="Microsoft" modified="false" />The category of the option to be set.</param>
 152         <param name="setting">
 153           <attribution license="cc4" from="Microsoft" modified="false" />The option setting.</param>
 154         <param name="value">
 155           <attribution license="cc4" from="Microsoft" modified="false" />The value for the setting.</param>
 156       </Docs>
 157     </Member>
 158     <Member MemberName="Category">
 159       <MemberSignature Language="C#" Value="public string Category { get; }" />
 160       <MemberSignature Language="ILAsm" Value=".property instance string Category" />
 161       <MemberType>Property</MemberType>
 162       <AssemblyInfo>
 163         <AssemblyVersion>4.0.0.0</AssemblyVersion>
 164       </AssemblyInfo>
 165       <ReturnValue>
 166         <ReturnType>System.String</ReturnType>
 167       </ReturnValue>
 168       <Docs>
 169         <value>To be added.</value>
 170         <remarks>To be added.</remarks>
 171         <summary>
 172           <attribution license="cc4" from="Microsoft" modified="false" />
 173           <para>Gets the category of the option.</para>
 174         </summary>
 175       </Docs>
 176     </Member>
 177     <Member MemberName="Enabled">
 178       <MemberSignature Language="C#" Value="public bool Enabled { get; }" />
 179       <MemberSignature Language="ILAsm" Value=".property instance bool Enabled" />
 180       <MemberType>Property</MemberType>
 181       <AssemblyInfo>
 182         <AssemblyVersion>4.0.0.0</AssemblyVersion>
 183       </AssemblyInfo>
 184       <ReturnValue>
 185         <ReturnType>System.Boolean</ReturnType>
 186       </ReturnValue>
 187       <Docs>
 188         <value>To be added.</value>
 189         <remarks>To be added.</remarks>
 190         <summary>
 191           <attribution license="cc4" from="Microsoft" modified="false" />
 192           <para>Determines if an option is enabled.</para>
 193         </summary>
 194       </Docs>
 195     </Member>
 196     <Member MemberName="Setting">
 197       <MemberSignature Language="C#" Value="public string Setting { get; }" />
 198       <MemberSignature Language="ILAsm" Value=".property instance string Setting" />
 199       <MemberType>Property</MemberType>
 200       <AssemblyInfo>
 201         <AssemblyVersion>4.0.0.0</AssemblyVersion>
 202       </AssemblyInfo>
 203       <ReturnValue>
 204         <ReturnType>System.String</ReturnType>
 205       </ReturnValue>
 206       <Docs>
 207         <value>To be added.</value>
 208         <remarks>To be added.</remarks>
 209         <summary>
 210           <attribution license="cc4" from="Microsoft" modified="false" />
 211           <para>Gets the setting for the option.</para>
 212         </summary>
 213       </Docs>
 214     </Member>
 215     <Member MemberName="Value">
 216       <MemberSignature Language="C#" Value="public string Value { get; }" />
 217       <MemberSignature Language="ILAsm" Value=".property instance string Value" />
 218       <MemberType>Property</MemberType>
 219       <AssemblyInfo>
 220         <AssemblyVersion>4.0.0.0</AssemblyVersion>
 221       </AssemblyInfo>
 222       <ReturnValue>
 223         <ReturnType>System.String</ReturnType>
 224       </ReturnValue>
 225       <Docs>
 226         <value>To be added.</value>
 227         <remarks>To be added.</remarks>
 228         <summary>
 229           <attribution license="cc4" from="Microsoft" modified="false" />
 230           <para>Gets the value for the option.</para>
 231         </summary>
 232       </Docs>
 233     </Member>
 234   </Members>
 235 </Type>