Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
249 lines (227 sloc) 20.7 KB
<Type Name="SqlDataSourceStatusEventArgs" FullName="System.Web.UI.WebControls.SqlDataSourceStatusEventArgs">
<TypeSignature Language="C#" Value="public class SqlDataSourceStatusEventArgs : EventArgs" />
<TypeSignature Language="ILAsm" Value=".class public auto ansi beforefieldinit SqlDataSourceStatusEventArgs extends System.EventArgs" />
<TypeSignature Language="DocId" Value="T:System.Web.UI.WebControls.SqlDataSourceStatusEventArgs" />
<TypeSignature Language="VB.NET" Value="Public Class SqlDataSourceStatusEventArgs&#xA;Inherits EventArgs" />
<TypeSignature Language="C++ CLI" Value="public ref class SqlDataSourceStatusEventArgs : EventArgs" />
<TypeSignature Language="F#" Value="type SqlDataSourceStatusEventArgs = class&#xA; inherit EventArgs" />
<AssemblyInfo>
<AssemblyName>System.Web</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Base>
<BaseTypeName>System.EventArgs</BaseTypeName>
</Base>
<Interfaces />
<Docs>
<summary>Provides data for an event that is raised by the <see cref="T:System.Web.UI.WebControls.SqlDataSource" /> control after a data operation has completed.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The <xref:System.Web.UI.WebControls.SqlDataSourceStatusEventArgs> class is used in the <xref:System.Web.UI.WebControls.SqlDataSource.Selected>, <xref:System.Web.UI.WebControls.SqlDataSource.Updated>, <xref:System.Web.UI.WebControls.SqlDataSource.Inserted>, and <xref:System.Web.UI.WebControls.SqlDataSource.Deleted> events to pass information about a database operation after it is performed by the data source control. This information includes the number of rows affected by the operation, the <xref:System.Data.Common.DbCommand> object that the data source used to perform the operation, and any exception information that resulted. By adding an event handler delegate to handle the <xref:System.Web.UI.WebControls.SqlDataSource.Selected>, <xref:System.Web.UI.WebControls.SqlDataSource.Updated>, <xref:System.Web.UI.WebControls.SqlDataSource.Inserted> or <xref:System.Web.UI.WebControls.SqlDataSource.Deleted> events, you can examine this data and perform any additional post processing required.
The <xref:System.Web.UI.WebControls.SqlDataSource> control exposes many events that you can handle to work with the underlying data objects during the course of a data operation. The following table lists the events and associated <xref:System.EventArgs> and event handler classes, to better guide you to the various events that correspond to the life cycle of a data operation using the <xref:System.Web.UI.WebControls.SqlDataSource> control.
|Event|EventArgs|EventHandler|
|-----------|---------------|------------------|
|<xref:System.Web.UI.WebControls.SqlDataSource.Selecting> occurs before the data is retrieved.|<xref:System.Web.UI.WebControls.SqlDataSourceSelectingEventArgs>|<xref:System.Web.UI.WebControls.SqlDataSourceSelectingEventHandler>|
|<xref:System.Web.UI.WebControls.SqlDataSource.Inserting>, <xref:System.Web.UI.WebControls.SqlDataSource.Updating>, <xref:System.Web.UI.WebControls.SqlDataSource.Deleting> occur before an insert, update, or delete operation is performed.|<xref:System.Web.UI.WebControls.SqlDataSourceCommandEventArgs>|<xref:System.Web.UI.WebControls.SqlDataSourceCommandEventHandler>|
|<xref:System.Web.UI.WebControls.SqlDataSource.Selected>, <xref:System.Web.UI.WebControls.SqlDataSource.Inserted>, <xref:System.Web.UI.WebControls.SqlDataSource.Updated>, <xref:System.Web.UI.WebControls.SqlDataSource.Deleted> occur after the data retrieval, insert, update, or delete operations completes.|<xref:System.Web.UI.WebControls.SqlDataSourceStatusEventArgs>|<xref:System.Web.UI.WebControls.SqlDataSourceStatusEventHandler>|
## Examples
The following code example demonstrates how to use the <xref:System.Web.UI.WebControls.SqlDataSourceStatusEventArgs> class to examine the return value and values of output parameters that are returned when using a <xref:System.Web.UI.WebControls.SqlDataSource> control with a stored procedure to populate a <xref:System.Web.UI.WebControls.GridView> control. The stored procedure selects data that is displayed in the <xref:System.Web.UI.WebControls.GridView>, but also passes other information back to the caller, such as an integer output parameter and a return value. The parameters that the <xref:System.Web.UI.WebControls.SqlDataSource> uses for the stored procedure are contained by the <xref:System.Web.UI.WebControls.SqlDataSource.SelectParameters%2A> collection, and consist of parameters that pass information from the Web form to the stored procedure as well as parameters that pass information back to the form. The <xref:System.Web.UI.WebControls.Parameter.Direction%2A> property of these parameters is set to <xref:System.Data.ParameterDirection.Output> and <xref:System.Data.ParameterDirection.ReturnValue>.
[!code-aspx-csharp[System.Web.UI.WebControls.SqlDataSourceStatusEventArgs_1#1](~/samples/snippets/csharp/VS_Snippets_WebNet/System.Web.UI.WebControls.SqlDataSourceStatusEventArgs_1/CS/sql21cs.aspx#1)]
[!code-aspx-vb[System.Web.UI.WebControls.SqlDataSourceStatusEventArgs_1#1](~/samples/snippets/visualbasic/VS_Snippets_WebNet/System.Web.UI.WebControls.SqlDataSourceStatusEventArgs_1/VB/sql21vb.aspx#1)]
]]></format>
</remarks>
<altmember cref="T:System.Web.UI.WebControls.SqlDataSourceStatusEventHandler" />
<altmember cref="T:System.Web.UI.WebControls.SqlDataSource" />
<altmember cref="E:System.Web.UI.WebControls.SqlDataSource.Selected" />
<altmember cref="E:System.Web.UI.WebControls.SqlDataSource.Updated" />
<altmember cref="E:System.Web.UI.WebControls.SqlDataSource.Inserted" />
<altmember cref="E:System.Web.UI.WebControls.SqlDataSource.Deleted" />
</Docs>
<Members>
<Member MemberName=".ctor">
<MemberSignature Language="C#" Value="public SqlDataSourceStatusEventArgs (System.Data.Common.DbCommand command, int affectedRows, Exception exception);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig specialname rtspecialname instance void .ctor(class System.Data.Common.DbCommand command, int32 affectedRows, class System.Exception exception) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Web.UI.WebControls.SqlDataSourceStatusEventArgs.#ctor(System.Data.Common.DbCommand,System.Int32,System.Exception)" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; SqlDataSourceStatusEventArgs(System::Data::Common::DbCommand ^ command, int affectedRows, Exception ^ exception);" />
<MemberSignature Language="F#" Value="new System.Web.UI.WebControls.SqlDataSourceStatusEventArgs : System.Data.Common.DbCommand * int * Exception -&gt; System.Web.UI.WebControls.SqlDataSourceStatusEventArgs" Usage="new System.Web.UI.WebControls.SqlDataSourceStatusEventArgs (command, affectedRows, exception)" />
<MemberType>Constructor</MemberType>
<AssemblyInfo>
<AssemblyName>System.Web</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Attributes>
<Attribute FrameworkAlternate="netframework-4.0">
<AttributeName>System.Runtime.TargetedPatchingOptOut("Performance critical to inline this type of method across NGen image boundaries")</AttributeName>
</Attribute>
</Attributes>
<Parameters>
<Parameter Name="command" Type="System.Data.Common.DbCommand" />
<Parameter Name="affectedRows" Type="System.Int32" />
<Parameter Name="exception" Type="System.Exception" />
</Parameters>
<Docs>
<param name="command">The <see cref="T:System.Data.Common.DbCommand" /> that represents the database query, command, or stored procedure that is submitted to the database by the <see cref="T:System.Web.UI.WebControls.SqlDataSource" /> control.</param>
<param name="affectedRows">The number of rows affected by the database operation, if applicable.</param>
<param name="exception">An <see cref="T:System.Exception" /> thrown by the database operation, if applicable.</param>
<summary>Initializes a new instance of the <see cref="T:System.Web.UI.WebControls.SqlDataSourceStatusEventArgs" /> class, using the specified output parameters, return value, and number of rows affected by the database operation.</summary>
<remarks>To be added.</remarks>
<altmember cref="P:System.Web.UI.WebControls.SqlDataSourceStatusEventArgs.Command" />
<altmember cref="P:System.Web.UI.WebControls.SqlDataSourceStatusEventArgs.AffectedRows" />
</Docs>
</Member>
<Member MemberName="AffectedRows">
<MemberSignature Language="C#" Value="public int AffectedRows { get; }" />
<MemberSignature Language="ILAsm" Value=".property instance int32 AffectedRows" />
<MemberSignature Language="DocId" Value="P:System.Web.UI.WebControls.SqlDataSourceStatusEventArgs.AffectedRows" />
<MemberSignature Language="VB.NET" Value="Public ReadOnly Property AffectedRows As Integer" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; property int AffectedRows { int get(); };" />
<MemberSignature Language="F#" Value="member this.AffectedRows : int" Usage="System.Web.UI.WebControls.SqlDataSourceStatusEventArgs.AffectedRows" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyName>System.Web</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Attributes>
<Attribute FrameworkAlternate="netframework-4.0">
<AttributeName>get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline this type of method across NGen image boundaries")</AttributeName>
</Attribute>
</Attributes>
<ReturnValue>
<ReturnType>System.Int32</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets the number of rows affected by a database operation.</summary>
<value>The number of rows affected by a database operation. The default value is -1.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
All operations return the number of rows affected by the operation. The <xref:System.Web.UI.WebControls.SqlDataSourceStatusEventArgs.AffectedRows%2A> property has the same value as the return value of the <xref:System.Web.UI.WebControls.SqlDataSource.Update%2A>, <xref:System.Web.UI.WebControls.SqlDataSource.Insert%2A>, and <xref:System.Web.UI.WebControls.SqlDataSource.Delete%2A> methods.
When the <xref:System.Web.UI.WebControls.SqlDataSource.Select%2A> method is called and the data source is set to <xref:System.Web.UI.WebControls.SqlDataSourceMode.DataReader> mode, the return value is 0 in all cases.
]]></format>
</remarks>
<altmember cref="M:System.Web.UI.WebControls.SqlDataSource.Update" />
<altmember cref="M:System.Web.UI.WebControls.SqlDataSource.Insert" />
<altmember cref="M:System.Web.UI.WebControls.SqlDataSource.Delete" />
</Docs>
</Member>
<Member MemberName="Command">
<MemberSignature Language="C#" Value="public System.Data.Common.DbCommand Command { get; }" />
<MemberSignature Language="ILAsm" Value=".property instance class System.Data.Common.DbCommand Command" />
<MemberSignature Language="DocId" Value="P:System.Web.UI.WebControls.SqlDataSourceStatusEventArgs.Command" />
<MemberSignature Language="VB.NET" Value="Public ReadOnly Property Command As DbCommand" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; property System::Data::Common::DbCommand ^ Command { System::Data::Common::DbCommand ^ get(); };" />
<MemberSignature Language="F#" Value="member this.Command : System.Data.Common.DbCommand" Usage="System.Web.UI.WebControls.SqlDataSourceStatusEventArgs.Command" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyName>System.Web</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Attributes>
<Attribute FrameworkAlternate="netframework-4.0">
<AttributeName>get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline this type of method across NGen image boundaries")</AttributeName>
</Attribute>
</Attributes>
<ReturnValue>
<ReturnType>System.Data.Common.DbCommand</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets the database command submitted to the database.</summary>
<value>The <see cref="T:System.Data.Common.DbCommand" /> object that represents the database command submitted to the database.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
You can handle the <xref:System.Web.UI.WebControls.SqlDataSource.Selected>, <xref:System.Web.UI.WebControls.SqlDataSource.Updated>, <xref:System.Web.UI.WebControls.SqlDataSource.Inserted>, or <xref:System.Web.UI.WebControls.SqlDataSource.Deleted> event to examine and manipulate the properties of the <xref:System.Data.Common.DbCommand> after it is submitted by the <xref:System.Web.UI.WebControls.SqlDataSource> control to the database. The <xref:System.Web.UI.WebControls.SqlDataSourceStatusEventArgs.Command%2A> property enables you to access return values and values in any output parameters after the database operation is performed through its <xref:System.Data.Common.DbCommand.Parameters%2A> property, as well as the <xref:System.Data.Common.DbCommand.CommandText%2A> property, which represents the SQL query, command, or stored procedure name that was submitted to the database.
Any output parameters are specifically from parameters that have an <xref:System.Data.ParameterDirection.InputOutput> or <xref:System.Data.ParameterDirection.Output> value for the <xref:System.Web.UI.WebControls.Parameter.Direction%2A> property of the <xref:System.Web.UI.WebControls.Parameter> object. A return value is from a parameter that has a <xref:System.Data.ParameterDirection.ReturnValue> value.
## Examples
The following code example demonstrates how to examine the values of output parameters when using a <xref:System.Web.UI.WebControls.SqlDataSource> control with a stored procedure. The <xref:System.Web.UI.WebControls.SqlDataSource.SelectParameters%2A> collection contains the parameters that the <xref:System.Web.UI.WebControls.SqlDataSource> uses for the stored procedure, and consists of parameters that pass information from the Web form to the stored procedure as well as parameters that pass information back to the form. This code example is part of a larger example provided for the <xref:System.Web.UI.WebControls.SqlDataSourceStatusEventArgs> class.
[!code-aspx-csharp[System.Web.UI.WebControls.SqlDataSourceStatusEventArgs_1#1](~/samples/snippets/csharp/VS_Snippets_WebNet/System.Web.UI.WebControls.SqlDataSourceStatusEventArgs_1/CS/sql21cs.aspx#1)]
[!code-aspx-vb[System.Web.UI.WebControls.SqlDataSourceStatusEventArgs_1#1](~/samples/snippets/visualbasic/VS_Snippets_WebNet/System.Web.UI.WebControls.SqlDataSourceStatusEventArgs_1/VB/sql21vb.aspx#1)]
]]></format>
</remarks>
<altmember cref="E:System.Web.UI.WebControls.SqlDataSource.Selected" />
<altmember cref="E:System.Web.UI.WebControls.SqlDataSource.Updated" />
<altmember cref="E:System.Web.UI.WebControls.SqlDataSource.Inserted" />
<altmember cref="E:System.Web.UI.WebControls.SqlDataSource.Deleted" />
</Docs>
</Member>
<Member MemberName="Exception">
<MemberSignature Language="C#" Value="public Exception Exception { get; }" />
<MemberSignature Language="ILAsm" Value=".property instance class System.Exception Exception" />
<MemberSignature Language="DocId" Value="P:System.Web.UI.WebControls.SqlDataSourceStatusEventArgs.Exception" />
<MemberSignature Language="VB.NET" Value="Public ReadOnly Property Exception As Exception" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; property Exception ^ Exception { Exception ^ get(); };" />
<MemberSignature Language="F#" Value="member this.Exception : Exception" Usage="System.Web.UI.WebControls.SqlDataSourceStatusEventArgs.Exception" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyName>System.Web</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Attributes>
<Attribute FrameworkAlternate="netframework-4.0">
<AttributeName>get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline this type of method across NGen image boundaries")</AttributeName>
</Attribute>
</Attributes>
<ReturnValue>
<ReturnType>System.Exception</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets a wrapper for any exceptions thrown by the database during a data operation.</summary>
<value>An <see cref="T:System.Exception" /> that wraps any exceptions thrown by the database in its <see cref="P:System.Exception.InnerException" /> property.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The <xref:System.Exception> property does not represent the actual exception thrown by the database operation. You can access the thrown exception using the <xref:System.Exception.InnerException%2A> property.
]]></format>
</remarks>
<altmember cref="E:System.Web.UI.WebControls.SqlDataSource.Selected" />
<altmember cref="E:System.Web.UI.WebControls.SqlDataSource.Updated" />
<altmember cref="E:System.Web.UI.WebControls.SqlDataSource.Inserted" />
<altmember cref="E:System.Web.UI.WebControls.SqlDataSource.Deleted" />
</Docs>
</Member>
<Member MemberName="ExceptionHandled">
<MemberSignature Language="C#" Value="public bool ExceptionHandled { get; set; }" />
<MemberSignature Language="ILAsm" Value=".property instance bool ExceptionHandled" />
<MemberSignature Language="DocId" Value="P:System.Web.UI.WebControls.SqlDataSourceStatusEventArgs.ExceptionHandled" />
<MemberSignature Language="VB.NET" Value="Public Property ExceptionHandled As Boolean" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; property bool ExceptionHandled { bool get(); void set(bool value); };" />
<MemberSignature Language="F#" Value="member this.ExceptionHandled : bool with get, set" Usage="System.Web.UI.WebControls.SqlDataSourceStatusEventArgs.ExceptionHandled" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyName>System.Web</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Attributes>
<Attribute FrameworkAlternate="netframework-4.0">
<AttributeName>get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline this type of method across NGen image boundaries")</AttributeName>
</Attribute>
<Attribute FrameworkAlternate="netframework-4.0">
<AttributeName>set: System.Runtime.TargetedPatchingOptOut("Performance critical to inline this type of method across NGen image boundaries")</AttributeName>
</Attribute>
</Attributes>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets or sets a value indicating whether an exception thrown by the database has been handled.</summary>
<value>
<see langword="true" /> if an exception thrown by the database has been handled and should not be thrown by the <see cref="T:System.Web.UI.WebControls.SqlDataSource" /> control; otherwise, <see langword="false" />.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
If the database throws an exception, the <xref:System.Web.UI.WebControls.SqlDataSourceStatusEventArgs.ExceptionHandled%2A> property is set to `false` and the exception is wrapped by the <xref:System.Web.UI.WebControls.SqlDataSourceStatusEventArgs.Exception%2A> property. If you use an <xref:System.Web.UI.WebControls.SqlDataSourceStatusEventHandler>, you can check the <xref:System.Web.UI.WebControls.ObjectDataSourceStatusEventArgs.Exception%2A> property and handle the exception. If you handle the exception, set the <xref:System.Web.UI.WebControls.SqlDataSourceStatusEventArgs.ExceptionHandled%2A> property to `true` or the <xref:System.Web.UI.WebControls.SqlDataSource> control will throw an exception.
]]></format>
</remarks>
<altmember cref="T:System.Web.UI.WebControls.SqlDataSourceStatusEventHandler" />
<altmember cref="P:System.Web.UI.WebControls.SqlDataSourceStatusEventArgs.Exception" />
</Docs>
</Member>
</Members>
</Type>
You can’t perform that action at this time.