mcs/class/System.Web.Services/Documentation/en/System.Web.Services/WebMethodAttribute.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <Type Name="WebMethodAttribute" FullName="System.Web.Services.WebMethodAttribute">
   3   <TypeSignature Language="C#" Maintainer="auto" Value="public sealed class WebMethodAttribute : Attribute" />
   4   <AssemblyInfo>
   5     <AssemblyName>System.Web.Services</AssemblyName>
   6     <AssemblyPublicKey>
   7     </AssemblyPublicKey>
   8     <AssemblyVersion>1.0.5000.0</AssemblyVersion>
   9     <AssemblyVersion>2.0.0.0</AssemblyVersion>
  10   </AssemblyInfo>
  11   <ThreadSafetyStatement>Gtk# is thread aware, but not thread safe; See the &lt;link location="node:gtk-sharp/programming/threads"&gt;Gtk# Thread Programming&lt;/link&gt; for details.</ThreadSafetyStatement>
  12   <Base>
  13     <BaseTypeName>System.Attribute</BaseTypeName>
  14   </Base>
  15   <Interfaces />
  16   <Attributes>
  17     <Attribute>
  18       <AttributeName>System.AttributeUsage(System.AttributeTargets.Method, Inherited=true)</AttributeName>
  19     </Attribute>
  20   </Attributes>
  21   <Docs>
  22     <remarks>
  23       <attribution license="cc4" from="Microsoft" modified="false" />
  24       <para>Methods within a class that have this attribute set are called XML Web service methods. The method and class must be public and running inside an ASP.NET Web application.</para>
  25     </remarks>
  26     <summary>
  27       <attribution license="cc4" from="Microsoft" modified="false" />
  28       <para>Adding this attribute to a method within an XML Web service created using ASP.NET makes the method callable from remote Web clients. This class cannot be inherited.</para>
  29     </summary>
  30   </Docs>
  31   <Members>
  32     <Member MemberName=".ctor">
  33       <MemberSignature Language="C#" Value="public WebMethodAttribute ();" />
  34       <MemberType>Constructor</MemberType>
  35       <ReturnValue />
  36       <Parameters />
  37       <Docs>
  38         <remarks>To be added</remarks>
  39         <summary>
  40           <attribution license="cc4" from="Microsoft" modified="false" />
  41           <para>Initializes a new instance of the <see cref="T:System.Web.Services.WebMethodAttribute" /> class.</para>
  42         </summary>
  43       </Docs>
  44       <AssemblyInfo>
  45         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
  46         <AssemblyVersion>2.0.0.0</AssemblyVersion>
  47       </AssemblyInfo>
  48     </Member>
  49     <Member MemberName=".ctor">
  50       <MemberSignature Language="C#" Value="public WebMethodAttribute (bool enableSession);" />
  51       <MemberType>Constructor</MemberType>
  52       <ReturnValue />
  53       <Parameters>
  54         <Parameter Name="enableSession" Type="System.Boolean" />
  55       </Parameters>
  56       <Docs>
  57         <remarks>To be added</remarks>
  58         <summary>
  59           <attribution license="cc4" from="Microsoft" modified="false" />
  60           <para>Initializes a new instance of the <see cref="T:System.Web.Services.WebMethodAttribute" /> class.</para>
  61         </summary>
  62         <param name="enableSession">
  63           <attribution license="cc4" from="Microsoft" modified="false" />Initializes whether session state is enabled for the XML Web service method. </param>
  64       </Docs>
  65       <AssemblyInfo>
  66         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
  67         <AssemblyVersion>2.0.0.0</AssemblyVersion>
  68       </AssemblyInfo>
  69     </Member>
  70     <Member MemberName=".ctor">
  71       <MemberSignature Language="C#" Value="public WebMethodAttribute (bool enableSession, System.EnterpriseServices.TransactionOption transactionOption);" />
  72       <MemberType>Constructor</MemberType>
  73       <ReturnValue />
  74       <Parameters>
  75         <Parameter Name="enableSession" Type="System.Boolean" />
  76         <Parameter Name="transactionOption" Type="System.EnterpriseServices.TransactionOption" />
  77       </Parameters>
  78       <Docs>
  79         <remarks>
  80           <attribution license="cc4" from="Microsoft" modified="false" />
  81           <para>A web service call can only be the root of a transaction, due to the stateless nature of the HTTP protocol. This means that the following two settings are equivalent, with each call creating a new transaction:</para>
  82           <code>[WebMethod(TransactionOption = TransactionOption.Required)]
  83 [WebMethod(TransactionOption = TransactionOption.RequiresNew)]</code>
  84           <para>It also means that all the following settings are equivalent; meaning no transaction support:</para>
  85           <code>[WebMethod] // TransactionOption.Disabled is the default
  86 [WebMethod(TransactionOption = TransactionOption.Disabled)]
  87 [WebMethod(TransactionOption = Transaction.NotSupported)]
  88 [WebMethod(TransactionOption = Transaction.Supported)]</code>
  89         </remarks>
  90         <summary>
  91           <attribution license="cc4" from="Microsoft" modified="false" />
  92           <para>Initializes a new instance of the <see cref="T:System.Web.Services.WebMethodAttribute" /> class.</para>
  93         </summary>
  94         <param name="enableSession">
  95           <attribution license="cc4" from="Microsoft" modified="false" />Initializes whether session state is enabled for the XML Web service method. </param>
  96         <param name="transactionOption">
  97           <attribution license="cc4" from="Microsoft" modified="false" />Initializes the transaction support of an XML Web service method. </param>
  98       </Docs>
  99       <AssemblyInfo>
 100         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 101         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 102       </AssemblyInfo>
 103     </Member>
 104     <Member MemberName=".ctor">
 105       <MemberSignature Language="C#" Value="public WebMethodAttribute (bool enableSession, System.EnterpriseServices.TransactionOption transactionOption, int cacheDuration);" />
 106       <MemberType>Constructor</MemberType>
 107       <ReturnValue />
 108       <Parameters>
 109         <Parameter Name="enableSession" Type="System.Boolean" />
 110         <Parameter Name="transactionOption" Type="System.EnterpriseServices.TransactionOption" />
 111         <Parameter Name="cacheDuration" Type="System.Int32" />
 112       </Parameters>
 113       <Docs>
 114         <remarks>
 115           <attribution license="cc4" from="Microsoft" modified="false" />
 116           <para>A web service call can only be the root of a transaction, due to the stateless nature of the HTTP protocol.  This means that the following two settings are equivalent, with each call creating a new transaction:</para>
 117           <code>[WebMethod(TransactionOption = TransactionOption.Required)]
 118 [WebMethod(TransactionOption = TransactionOption.RequiresNew)]</code>
 119           <para>It also means that all the following settings are equivalent; meaning no transaction support:</para>
 120           <code>[WebMethod] // TransactionOption.Disabled is the default
 121 [WebMethod(TransactionOption = TransactionOption.Disabled)]
 122 [WebMethod(TransactionOption = Transaction.NotSupported)]
 123 [WebMethod(TransactionOption = Transaction.Supported)]</code>
 124         </remarks>
 125         <summary>
 126           <attribution license="cc4" from="Microsoft" modified="false" />
 127           <para>Initializes a new instance of the <see cref="T:System.Web.Services.WebMethodAttribute" /> class.</para>
 128         </summary>
 129         <param name="enableSession">
 130           <attribution license="cc4" from="Microsoft" modified="false" />Initializes whether session state is enabled for the XML Web service method. </param>
 131         <param name="transactionOption">
 132           <attribution license="cc4" from="Microsoft" modified="false" />Initializes the transaction support of an XML Web service method. </param>
 133         <param name="cacheDuration">
 134           <attribution license="cc4" from="Microsoft" modified="false" />Initializes the number of seconds the response is cached. </param>
 135       </Docs>
 136       <AssemblyInfo>
 137         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 138         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 139       </AssemblyInfo>
 140     </Member>
 141     <Member MemberName=".ctor">
 142       <MemberSignature Language="C#" Value="public WebMethodAttribute (bool enableSession, System.EnterpriseServices.TransactionOption transactionOption, int cacheDuration, bool bufferResponse);" />
 143       <MemberType>Constructor</MemberType>
 144       <ReturnValue />
 145       <Parameters>
 146         <Parameter Name="enableSession" Type="System.Boolean" />
 147         <Parameter Name="transactionOption" Type="System.EnterpriseServices.TransactionOption" />
 148         <Parameter Name="cacheDuration" Type="System.Int32" />
 149         <Parameter Name="bufferResponse" Type="System.Boolean" />
 150       </Parameters>
 151       <Docs>
 152         <remarks>
 153           <attribution license="cc4" from="Microsoft" modified="false" />
 154           <para>A web service call can only be the root of a transaction, due to the stateless nature of the HTTP protocol.  This means that the following two settings are equivalent, with each call creating a new transaction:</para>
 155           <code>[WebMethod(TransactionOption = TransactionOption.Required)]
 156 [WebMethod(TransactionOption = TransactionOption.RequiresNew)]</code>
 157           <para>It also means that all the following settings are equivalent; meaning no transaction support:</para>
 158           <code>[WebMethod] // TransactionOption.Disabled is the default
 159 [WebMethod(TransactionOption = TransactionOption.Disabled)]
 160 [WebMethod(TransactionOption = Transaction.NotSupported)]
 161 [WebMethod(TransactionOption = Transaction.Supported)]</code>
 162         </remarks>
 163         <summary>
 164           <attribution license="cc4" from="Microsoft" modified="false" />
 165           <para>Initializes a new instance of the <see cref="T:System.Web.Services.WebMethodAttribute" /> class.</para>
 166         </summary>
 167         <param name="enableSession">
 168           <attribution license="cc4" from="Microsoft" modified="false" />Initializes whether session state is enabled for the XML Web service method. </param>
 169         <param name="transactionOption">
 170           <attribution license="cc4" from="Microsoft" modified="false" />Initializes the transaction support of an XML Web service method. </param>
 171         <param name="cacheDuration">
 172           <attribution license="cc4" from="Microsoft" modified="false" />Initializes the number of seconds the response is cached. </param>
 173         <param name="bufferResponse">
 174           <attribution license="cc4" from="Microsoft" modified="false" />Initializes whether the response for this request is buffered. </param>
 175       </Docs>
 176       <AssemblyInfo>
 177         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 178         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 179       </AssemblyInfo>
 180     </Member>
 181     <Member MemberName="BufferResponse">
 182       <MemberSignature Language="C#" Value="public bool BufferResponse { set; get; }" />
 183       <MemberType>Property</MemberType>
 184       <ReturnValue>
 185         <ReturnType>System.Boolean</ReturnType>
 186       </ReturnValue>
 187       <Parameters />
 188       <Docs>
 189         <value>To be added: an object of type 'bool'</value>
 190         <remarks>
 191           <attribution license="cc4" from="Microsoft" modified="false" />
 192           <para>Setting <see cref="P:System.Web.Services.WebMethodAttribute.BufferResponse" /> to true, serializes the response of the XML Web service method into a memory buffer until either the response is completely serialized or the buffer is full. Once the response is buffered, it is returned to the XML Web service client over the network. When <see cref="P:System.Web.Services.WebMethodAttribute.BufferResponse" /> is false, the response to the XML Web service method is sent back to the client as it is serialized. In general, you only want to set <see cref="P:System.Web.Services.WebMethodAttribute.BufferResponse" /> to false, if it is known that an XML Web service method returns large amounts of data to the client. For smaller amounts of data, XML Web service performance is better with <see cref="P:System.Web.Services.WebMethodAttribute.BufferResponse" /> to true.</para>
 193           <para>When <see cref="P:System.Web.Services.WebMethodAttribute.BufferResponse" /> is false, SOAP extensions are disabled for the XML Web service method.</para>
 194         </remarks>
 195         <summary>
 196           <attribution license="cc4" from="Microsoft" modified="false" />
 197           <para>Gets or sets whether the response for this request is buffered.</para>
 198         </summary>
 199       </Docs>
 200       <AssemblyInfo>
 201         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 202         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 203       </AssemblyInfo>
 204     </Member>
 205     <Member MemberName="CacheDuration">
 206       <MemberSignature Language="C#" Value="public int CacheDuration { set; get; }" />
 207       <MemberType>Property</MemberType>
 208       <ReturnValue>
 209         <ReturnType>System.Int32</ReturnType>
 210       </ReturnValue>
 211       <Parameters />
 212       <Docs>
 213         <value>To be added: an object of type 'int'</value>
 214         <remarks>
 215           <attribution license="cc4" from="Microsoft" modified="false" />
 216           <para>When caching is enabled requests and responses are held in memory on the server for at least the cache duration so caution must be used if you expect requests or responses to be very large or you expect requests to vary widely.</para>
 217           <para>There are two issues that can affect output caching in an ASP.NET 2.0 Web service application.</para>
 218           <para>In ASP.NET 2.0 the HTTP method of the test page has changed from GET to POST. However, POSTs are not normally cached. If you change the test page in an ASP.NET 2.0 Web service application to use GET, caching works properly.</para>
 219           <para>In addition, HTTP indicates that a user agent (the browser or calling application) should be able to override server caching by setting the "Cache-Control" to "no-cache". ASP.NET applications, therefore, ignore cached results when they find a "no-cache" header.</para>
 220           <para />
 221         </remarks>
 222         <summary>
 223           <attribution license="cc4" from="Microsoft" modified="false" />
 224           <para>Gets or sets the number of seconds the response should be held in the cache.</para>
 225         </summary>
 226       </Docs>
 227       <AssemblyInfo>
 228         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 229         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 230       </AssemblyInfo>
 231     </Member>
 232     <Member MemberName="Description">
 233       <MemberSignature Language="C#" Value="public string Description { set; get; }" />
 234       <MemberType>Property</MemberType>
 235       <ReturnValue>
 236         <ReturnType>System.String</ReturnType>
 237       </ReturnValue>
 238       <Parameters />
 239       <Docs>
 240         <value>To be added: an object of type 'string'</value>
 241         <remarks>
 242           <attribution license="cc4" from="Microsoft" modified="false" />
 243           <para>The descriptive message is displayed to prospective consumers of the XML Web service when description documents for the XML Web service are generated, such as the Service Description and the Service help page.</para>
 244         </remarks>
 245         <summary>
 246           <attribution license="cc4" from="Microsoft" modified="false" />
 247           <para>A descriptive message describing the XML Web service method.</para>
 248         </summary>
 249       </Docs>
 250       <AssemblyInfo>
 251         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 252         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 253       </AssemblyInfo>
 254     </Member>
 255     <Member MemberName="EnableSession">
 256       <MemberSignature Language="C#" Value="public bool EnableSession { set; get; }" />
 257       <MemberType>Property</MemberType>
 258       <ReturnValue>
 259         <ReturnType>System.Boolean</ReturnType>
 260       </ReturnValue>
 261       <Parameters />
 262       <Docs>
 263         <value>To be added: an object of type 'bool'</value>
 264         <remarks>
 265           <attribution license="cc4" from="Microsoft" modified="false" />
 266           <para>In order to store session state in the ASP.NET <see cref="T:System.Web.SessionState.HttpSessionState" /> object, the XML Web service must inherit from <see cref="T:System.Web.Services.WebService" /> and a <see cref="T:System.Web.Services.WebMethodAttribute" /> applied to the XML Web service method, setting the <see cref="P:System.Web.Services.WebMethodAttribute.EnableSession" /> property to true. If session state is not needed for an XML Web service method, then disabling it may improve performance.</para>
 267           <para>An XML Web service client is uniquely identified by an HTTP cookie returned by an XML Web service. In order for an XML Web service to maintain session state for a client, the client must persist the cookie. Clients can receive the HTTP cookie by creating a new instance of <see cref="T:System.Net.CookieContainer" /> and assigning that to the <see cref="P:System.Web.Services.Protocols.HttpWebClientProtocol.CookieContainer" /> property of the proxy class before calling the XML Web service method. If you need to maintain session state beyond when the proxy class instance goes out of scope, the client must persist the HTTP cookie between calls to the XML Web service. For instance, a Web Forms client can persist the HTTP cookie by saving the <see cref="T:System.Net.CookieContainer" /> in its own session state. Because not all XML Web services use session state and thus clients are not always required to use the <see cref="P:System.Web.Services.Protocols.HttpWebClientProtocol.CookieContainer" /> property of a client proxy, the documentation for the XML Web service should state whether session state is used.</para>
 268         </remarks>
 269         <summary>
 270           <attribution license="cc4" from="Microsoft" modified="false" />
 271           <para>Indicates whether session state is enabled for an XML Web service method.</para>
 272         </summary>
 273       </Docs>
 274       <AssemblyInfo>
 275         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 276         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 277       </AssemblyInfo>
 278     </Member>
 279     <Member MemberName="MessageName">
 280       <MemberSignature Language="C#" Value="public string MessageName { set; get; }" />
 281       <MemberType>Property</MemberType>
 282       <ReturnValue>
 283         <ReturnType>System.String</ReturnType>
 284       </ReturnValue>
 285       <Parameters />
 286       <Docs>
 287         <value>To be added: an object of type 'string'</value>
 288         <remarks>
 289           <attribution license="cc4" from="Microsoft" modified="false" />
 290           <para>The <see cref="P:System.Web.Services.WebMethodAttribute.MessageName" /> property can be used to alias method or property names. The most common use of the <see cref="P:System.Web.Services.WebMethodAttribute.MessageName" /> property will be to uniquely identify polymorphic methods. By default, <see cref="P:System.Web.Services.WebMethodAttribute.MessageName" /> is set to the name of the XML Web service method. Therefore, if an XML Web service contains two or more XML Web service methods with the same name, you can uniquely identify the individual XML Web service methods by setting the <see cref="P:System.Web.Services.WebMethodAttribute.MessageName" /> to a name unique within the XML Web service, without changing the name of the actual method name in code.</para>
 291           <para>When data is passed to an XML Web service it is sent in a request and when it is returned it is sent in a response. Within the request and response, the name used for the XML Web service method is its <see cref="P:System.Web.Services.WebMethodAttribute.MessageName" /> property.</para>
 292           <para>The message name associated with an XML Web service method must be unique within the XML Web service.</para>
 293           <para>If a new XML Web serivce method with the same name but different parameters is added after clients are calling the original method, a different message name should be specified for the new method but the original message name should be left as is to ensure compatability with existing clients.</para>
 294         </remarks>
 295         <summary>
 296           <attribution license="cc4" from="Microsoft" modified="false" />
 297           <para>The name used for the XML Web service method in the data passed to and returned from an XML Web service method.</para>
 298         </summary>
 299       </Docs>
 300       <AssemblyInfo>
 301         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 302         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 303       </AssemblyInfo>
 304     </Member>
 305     <Member MemberName="TransactionOption">
 306       <MemberSignature Language="C#" Value="public System.EnterpriseServices.TransactionOption TransactionOption { set; get; }" />
 307       <MemberType>Property</MemberType>
 308       <ReturnValue>
 309         <ReturnType>System.EnterpriseServices.TransactionOption</ReturnType>
 310       </ReturnValue>
 311       <Parameters />
 312       <Docs>
 313         <value>a <see cref="T:System.EnterpriseServices.TransactionOption" /></value>
 314         <remarks>
 315           <attribution license="cc4" from="Microsoft" modified="false" />
 316           <para>XML Web service methods can only participate as the root object in a transaction, due to the stateless nature of the HTTP protocol. XML Web service methods can invoke COM objects that participate in the same transaction as the XML Web service method, if the COM object is marked to run within a transaction in the Component Services administrative tool. If an XML Web service method with a <see cref="P:System.Web.Services.WebMethodAttribute.TransactionOption" /> property of Required or RequiresNew invokes another XML Web service method with a <see cref="P:System.Web.Services.WebMethodAttribute.TransactionOption" /> property of Required or RequiresNew, each XML Web service method participates in its own transaction, because an XML Web service method can only act as the root object in a transaction.</para>
 317           <list type="table">
 318             <listheader>
 319               <item>
 320                 <term>
 321                   <para>Item </para>
 322                 </term>
 323                 <description>
 324                   <para>Description </para>
 325                 </description>
 326               </item>
 327             </listheader>
 328             <item>
 329               <term>
 330                 <para>Disabled </para>
 331               </term>
 332               <description>
 333                 <para>Indicates that the XML Web service method does not run within the scope of a transaction. When a request is processed, the XML Web service method is executed without a transaction.</para>
 334                 <para>[WebMethod(TransactionOption= TransactionOption.Disabled)] </para>
 335               </description>
 336             </item>
 337             <item>
 338               <term>
 339                 <para>NotSupported </para>
 340               </term>
 341               <description>
 342                 <para>Indicates that the XML Web service method does not run within the scope of a transaction. When a request is processed, the XML Web service method is executed without a transaction.</para>
 343                 <para>[WebMethod(TransactionOption= TransactionOption.NotSupported)] </para>
 344               </description>
 345             </item>
 346             <item>
 347               <term>
 348                 <para>Supported </para>
 349               </term>
 350               <description>
 351                 <para>Indicates that the XML Web service method does not run within the scope of transactions. When a request is processed, the XML Web service is created without a transaction.</para>
 352                 <para>[WebMethod(TransactionOption= TransactionOption.Supported)] </para>
 353               </description>
 354             </item>
 355             <item>
 356               <term>
 357                 <para>Required </para>
 358               </term>
 359               <description>
 360                 <para>Indicates that the XML Web service method requires a transaction. Since XML Web service methods can only participate as the root object in a transaction, a new transaction will be created for the XML Web service method.</para>
 361                 <para>[WebMethod(TransactionOption= TransactionOption.Required)] </para>
 362               </description>
 363             </item>
 364             <item>
 365               <term>
 366                 <para>RequiresNew </para>
 367               </term>
 368               <description>
 369                 <para>Indicates that the XML Web service method requires a new transaction. When a request is processed, the XML Web service is created within a new transaction.</para>
 370                 <para>[WebMethod(TransactionOption= TransactionOption.RequiresNew)] </para>
 371               </description>
 372             </item>
 373           </list>
 374           <para>If an exception is thrown from or not caught by an XML Web service method, the transaction is automatically aborted. If no exceptions occur the transaction is automatically committed unless the method explicitly calls SetAbort.</para>
 375         </remarks>
 376         <summary>
 377           <attribution license="cc4" from="Microsoft" modified="false" />
 378           <para>Indicates the transaction support of an XML Web service method.</para>
 379         </summary>
 380       </Docs>
 381       <AssemblyInfo>
 382         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 383         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 384       </AssemblyInfo>
 385     </Member>
 386   </Members>
 387 </Type>