Paramètres DataAdapterDataAdapter Parameters

L'objet DbDataAdapter possède quatre propriétés qui sont utilisées pour récupérer des données dans la source de données et y mettre des données à jour : la propriété SelectCommand retourne des données de la source de données et les propriétés InsertCommand, UpdateCommand et DeleteCommand sont utilisées pour gérer les modifications au niveau de la source de données.The DbDataAdapter has four properties that are used to retrieve data from and update data to the data source: the SelectCommand property returns data from the data source; and the InsertCommand , UpdateCommand, and DeleteCommand properties are used to manage changes at the data source. La propriété SelectCommand doit être définie avant d'appeler la méthode Fill du DataAdapter.The SelectCommand property must be set before you call the Fill method of the DataAdapter. Les propriétés InsertCommand, UpdateCommand ou DeleteCommand doivent être définies avant que la méthode Update du DataAdapter ne soit appelée, en fonction des modifications qui ont été apportées aux données dans le DataTable.The InsertCommand, UpdateCommand, or DeleteCommand properties must be set before the Update method of the DataAdapter is called, depending on what changes were made to the data in the DataTable. Par exemple, si des lignes ont été ajoutées, InsertCommand doit être défini avant d'appeler Update.For example, if rows have been added, the InsertCommand must be set before you call Update. Lorsque Update traite une ligne insérée, mise à jour ou supprimée, le DataAdapter utilise la propriété Command respective pour traiter l'action.When Update is processing an inserted, updated, or deleted row, the DataAdapter uses the respective Command property to process the action. Les informations actuelles concernant la ligne modifiée sont passées à l’objet Command par le biais de la collection Parameters.Current information about the modified row is passed to the Command object through the Parameters collection.

Lorsque vous mettez à jour une ligne à la source de données, vous appelez l’instruction UPDATE, qui utilise un identifiant unique pour identifier la ligne dans la table à mettre à jour.When you update a row at the data source, you call the UPDATE statement, which uses a unique identifier to identify the row in the table to be updated. Cet identificateur unique est généralement la valeur d'un champ de clé primaire.The unique identifier is typically the value of a primary key field. L'instruction UPDATE utilise les paramètres qui contiennent l'identificateur unique ainsi que les colonnes et les valeurs à mettre à jour, comme indiqué dans l'instruction Transact-SQL suivante.The UPDATE statement uses parameters that contain both the unique identifier and the columns and values to be updated, as shown in the following Transact-SQL statement.

UPDATE Customers SET CompanyName = @CompanyName
  WHERE CustomerID = @CustomerID  

Notes

La syntaxe des espaces réservés des paramètres dépend de la source de données.The syntax for parameter placeholders depends on the data source. Cet exemple montre les espaces réservés pour une source de données SQL Server.This example shows placeholders for a SQL Server data source. Utilisez des espaces réservés point d'interrogation (?) pour les paramètres System.Data.OleDb et System.Data.Odbc.Use question mark (?) placeholders for System.Data.OleDb and System.Data.Odbc parameters.

Dans cet exemple de CompanyName base visuelle, le @CompanyName champ est mis CustomerID à jour avec @CustomerID la valeur du paramètre pour la ligne où correspond à la valeur du paramètre.In this Visual Basic example, the CompanyName field is updated with the value of the @CompanyName parameter for the row where CustomerID equals the value of the @CustomerID parameter. Les paramètres récupèrent les informations SourceColumn de la SqlParameter ligne modifiée à l’aide de la propriété de l’objet.The parameters retrieve information from the modified row using the SourceColumn property of the SqlParameter object. Les paramètres suivants sont ceux de l'instruction UPDATE de l'exemple précédent.The following are the parameters for the previous sample UPDATE statement. Le code est basé sur l'hypothèse que la variable adapter représente un objet SqlDataAdapter valide.The code assumes that the variable adapter represents a valid SqlDataAdapter object.

adapter.Parameters.Add( _  
  "@CompanyName", SqlDbType.NChar, 15, "CompanyName")  
Dim parameter As SqlParameter = _  
  adapter.UpdateCommand.Parameters.Add("@CustomerID", _  
  SqlDbType.NChar, 5, "CustomerID")  
parameter.SourceVersion = DataRowVersion.Original  

La méthode Add de la collection Parameters prend le nom du paramètre, le type de données, la taille (si elle est applicable au type) et le nom de la propriété SourceColumn du DataTable.The Add method of the Parameters collection takes the name of the parameter, the data type, the size (if applicable to the type), and the name of the SourceColumn from the DataTable. Notez que la propriété SourceVersion du paramètre @CustomerID a la valeur Original.Notice that the SourceVersion of the @CustomerID parameter is set to Original. Cela garantit que la ligne existante dans la source de données est mise à jour si la valeur de la ou des colonnes d'identification a été modifiée dans l'objet DataRow.This guarantees that the existing row in the data source is updated if the value of the identifying column or columns has been changed in the modified DataRow. Dans ce cas, la valeur de ligne Original correspondrait à la valeur actuelle de la source de données et la valeur de ligne Current contiendrait la valeur mise à jour.In that case, the Original row value would match the current value at the data source, and the Current row value would contain the updated value. Le SourceVersion du paramètre @CompanyName n'est pas défini et utilise la valeur de ligne Current par défaut.The SourceVersion for the @CompanyName parameter is not set and uses the default, Current row value.

Notes

Pour les Fill opérations DataAdapter et Get les méthodes DataReaderde la , le type cadre .NET est déduit du type retourné du fournisseur de données .NET Framework.For both the Fill operations of the DataAdapter and the Get methods of the DataReader, the .NET Framework type is inferred from the type returned from the .NET Framework data provider. Les types de frameworks .NET déduits et les méthodes d’accesseur pour Microsoft SQL Server, OLE DB et ODBC types de données sont décrits dans les cartographies de type de données dans ADO.NET.The inferred .NET Framework types and accessor methods for Microsoft SQL Server, OLE DB, and ODBC data types are described in Data Type Mappings in ADO.NET.

Parameter.SourceColumn, Parameter.SourceVersionParameter.SourceColumn, Parameter.SourceVersion

Le SourceColumn et SourceVersion peuvent être passés comme arguments au constructeur Parameterou définis comme propriétés d'un Parameter existant.The SourceColumn and SourceVersion may be passed as arguments to the Parameter constructor, or set as properties of an existing Parameter. SourceColumn est le nom de l'objet DataColumn provenant de l'objet DataRow dans lequel la valeur de Parameter sera récupérée.The SourceColumn is the name of the DataColumn from the DataRow where the value of the Parameter will be retrieved. SourceVersion spécifie la version du DataRow que le DataAdapter utilise pour récupérer la valeur.The SourceVersion specifies the DataRow version that the DataAdapter uses to retrieve the value.

Le tableau suivant présente les valeurs d'énumération DataRowVersion disponibles pour être utilisées avec SourceVersion.The following table shows the DataRowVersion enumeration values available for use with SourceVersion.

Énumération DataRowVersionDataRowVersion Enumeration DescriptionDescription
Current Le paramètre utilise la valeur actuelle de la colonne.The parameter uses the current value of the column. Il s’agit de la valeur par défaut.This is the default.
Default Ce paramètre utilise le DefaultValue de la colomne.The parameter uses the DefaultValue of the column.
Original Le paramètre utilise la valeur d'origine de la colonne.The parameter uses the original value of the column.
Proposed Le paramètre utilise une valeur proposée.The parameter uses a proposed value.

L'exemple de code SqlClient de la section suivante définit un paramètre d'une propriété UpdateCommand dans lequel la colonne CustomerID est utilisée comme SourceColumn pour deux paramètres : @CustomerID (SET CustomerID = @CustomerID) et @OldCustomerID (WHERE CustomerID = @OldCustomerID).The SqlClient code example in the next section defines a parameter for an UpdateCommand in which the CustomerID column is used as a SourceColumn for two parameters: @CustomerID (SET CustomerID = @CustomerID), and @OldCustomerID (WHERE CustomerID = @OldCustomerID). Le @CustomerID paramètre est utilisé pour mettre à jour DataRowla colonne CustomerID à la valeur actuelle dans le .The @CustomerID parameter is used to update the CustomerID column to the current value in the DataRow. En conséquence, CustomerID SourceColumn le SourceVersion avec Current un de est utilisé.As a result, the CustomerID SourceColumn with a SourceVersion of Current is used. Le @OldCustomerID paramètre est utilisé pour identifier la ligne actuelle dans la source de données.The @OldCustomerID parameter is used to identify the current row in the data source. Puisque la valeur de colonne correspondante se trouve dans la version Original de la ligne, le même SourceColumn (CustomerID) avec un SourceVersion ayant la valeur Original est utilisé.Because the matching column value is found in the Original version of the row, the same SourceColumn (CustomerID) with a SourceVersion of Original is used.

Utilisation de paramètres SqlClientWorking with SqlClient Parameters

L'exemple suivant montre comment créer un objet SqlDataAdapter et affecter la valeur MissingSchemaAction à la propriété AddWithKey de manière à récupérer des informations de schéma supplémentaires de la base de données.The following example demonstrates how to create a SqlDataAdapter and set the MissingSchemaAction to AddWithKey in order to retrieve additional schema information from the database. Les propriétés SelectCommand, InsertCommand, UpdateCommand et DeleteCommand définies, ainsi que les objets SqlParameter correspondants ajoutés à la collection Parameters.The SelectCommand, InsertCommand, UpdateCommand, and DeleteCommand properties set and their corresponding SqlParameter objects added to the Parameters collection. La méthode retourne un objet SqlDataAdapter.The method returns a SqlDataAdapter object.

public static SqlDataAdapter CreateSqlDataAdapter(SqlConnection connection)
{
    SqlDataAdapter adapter = new SqlDataAdapter();
    adapter.MissingSchemaAction = MissingSchemaAction.AddWithKey;

    // Create the commands.
    adapter.SelectCommand = new SqlCommand(
        "SELECT CustomerID, CompanyName FROM CUSTOMERS", connection);
    adapter.InsertCommand = new SqlCommand(
        "INSERT INTO Customers (CustomerID, CompanyName) " +
        "VALUES (@CustomerID, @CompanyName)", connection);
    adapter.UpdateCommand = new SqlCommand(
        "UPDATE Customers SET CustomerID = @CustomerID, CompanyName = @CompanyName " +
        "WHERE CustomerID = @oldCustomerID", connection);
    adapter.DeleteCommand = new SqlCommand(
        "DELETE FROM Customers WHERE CustomerID = @CustomerID", connection);

    // Create the parameters.
    adapter.InsertCommand.Parameters.Add("@CustomerID", 
        SqlDbType.Char, 5, "CustomerID");
    adapter.InsertCommand.Parameters.Add("@CompanyName", 
        SqlDbType.VarChar, 40, "CompanyName");

    adapter.UpdateCommand.Parameters.Add("@CustomerID", 
        SqlDbType.Char, 5, "CustomerID");
    adapter.UpdateCommand.Parameters.Add("@CompanyName", 
        SqlDbType.VarChar, 40, "CompanyName");
    adapter.UpdateCommand.Parameters.Add("@oldCustomerID", 
        SqlDbType.Char, 5, "CustomerID").SourceVersion = 
        DataRowVersion.Original;

    adapter.DeleteCommand.Parameters.Add("@CustomerID", 
        SqlDbType.Char, 5, "CustomerID").SourceVersion = 
        DataRowVersion.Original;

    return adapter;
}
Public Function CreateSqlDataAdapter( _
    ByVal connection As SqlConnection) As SqlDataAdapter

    Dim adapter As New SqlDataAdapter()
    adapter.MissingSchemaAction = MissingSchemaAction.AddWithKey

    ' Create the commands.
    adapter.SelectCommand = New SqlCommand( _
        "SELECT CustomerID, CompanyName FROM CUSTOMERS", connection)
    adapter.InsertCommand = New SqlCommand( _
        "INSERT INTO Customers (CustomerID, CompanyName) " & _
         "VALUES (@CustomerID, @CompanyName)", connection)
    adapter.UpdateCommand = New SqlCommand( _
        "UPDATE Customers SET CustomerID = @CustomerID, CompanyName = " & _
        "@CompanyName WHERE CustomerID = @oldCustomerID", connection)
    adapter.DeleteCommand = New SqlCommand( _
        "DELETE FROM Customers WHERE CustomerID = @CustomerID", connection)

    ' Create the parameters.
    adapter.InsertCommand.Parameters.Add("@CustomerID", _
        SqlDbType.Char, 5, "CustomerID")
    adapter.InsertCommand.Parameters.Add("@CompanyName", _
        SqlDbType.VarChar, 40, "CompanyName")

    adapter.UpdateCommand.Parameters.Add("@CustomerID", _
        SqlDbType.Char, 5, "CustomerID")
    adapter.UpdateCommand.Parameters.Add("@CompanyName", _
        SqlDbType.VarChar, 40, "CompanyName")
    adapter.UpdateCommand.Parameters.Add("@oldCustomerID", _
        SqlDbType.Char, 5, "CustomerID").SourceVersion = _
        DataRowVersion.Original

    adapter.DeleteCommand.Parameters.Add("@CustomerID", _
        SqlDbType.Char, 5, "CustomerID").SourceVersion = _
        DataRowVersion.Original

    Return adapter
End Function

Espaces réservés pour les paramètres OleDbOleDb Parameter Placeholders

Pour les objets OleDbDataAdapter et OdbcDataAdapter, vous devez utiliser les espaces réservés point d'interrogation (?) pour identifier les paramètres.For the OleDbDataAdapter and OdbcDataAdapter objects, you must use question mark (?) placeholders to identify the parameters.

Dim selectSQL As String = _  
  "SELECT CustomerID, CompanyName FROM Customers " & _  
  "WHERE CountryRegion = ? AND City = ?"  
Dim insertSQL AS String = _  
  "INSERT INTO Customers (CustomerID, CompanyName) VALUES (?, ?)"  
Dim updateSQL AS String = _  
  "UPDATE Customers SET CustomerID = ?, CompanyName = ? " & _  
  WHERE CustomerID = ?"  
Dim deleteSQL As String = "DELETE FROM Customers WHERE CustomerID = ?"  
string selectSQL =
  "SELECT CustomerID, CompanyName FROM Customers " +  
  "WHERE CountryRegion = ? AND City = ?";  
string insertSQL =
  "INSERT INTO Customers (CustomerID, CompanyName) " +  
  "VALUES (?, ?)";  
string updateSQL =
  "UPDATE Customers SET CustomerID = ?, CompanyName = ? " +  
  "WHERE CustomerID = ? ";  
string deleteSQL = "DELETE FROM Customers WHERE CustomerID = ?";  

Les instructions de requête paramétrées définissent les paramètres d'entrée et de sortie à créer.The parameterized query statements define which input and output parameters must be created. Pour créer un paramètre, utilisez la méthode Parameters.Add ou le constructeur Parameter pour spécifier le nom de colonne, le type de données et la taille.To create a parameter, use the Parameters.Add method or the Parameter constructor to specify the column name, data type, and size. Pour les types de données intrinsèques, comme Integer, il n'est pas nécessaire d'inclure la taille, ou vous pouvez spécifier la taille par défaut.For intrinsic data types, such as Integer, you do not have to include the size, or you can specify the default size.

L'exemple de code suivant crée les paramètres d'une instruction SQL et remplit un DataSet.The following code example creates the parameters for a SQL statement and then fills a DataSet.

Exemple OleDbOleDb Example

' Assumes that connection is a valid OleDbConnection object.  
Dim adapter As OleDbDataAdapter = New OleDbDataAdapter
  
Dim selectCMD AS OleDbCommand = New OleDbCommand(selectSQL, connection)  
adapter.SelectCommand = selectCMD  
  
' Add parameters and set values.  
selectCMD.Parameters.Add( _  
  "@CountryRegion", OleDbType.VarChar, 15).Value = "UK"  
selectCMD.Parameters.Add( _  
  "@City", OleDbType.VarChar, 15).Value = "London"  
  
Dim customers As DataSet = New DataSet  
adapter.Fill(customers, "Customers")  
// Assumes that connection is a valid OleDbConnection object.  
OleDbDataAdapter adapter = new OleDbDataAdapter();  
  
OleDbCommand selectCMD = new OleDbCommand(selectSQL, connection);  
adapter.SelectCommand = selectCMD;  
  
// Add parameters and set values.  
selectCMD.Parameters.Add(  
  "@CountryRegion", OleDbType.VarChar, 15).Value = "UK";  
selectCMD.Parameters.Add(  
  "@City", OleDbType.VarChar, 15).Value = "London";  
  
DataSet customers = new DataSet();  
adapter.Fill(customers, "Customers");  

Paramètres OdbcOdbc Parameters

' Assumes that connection is a valid OdbcConnection object.  
Dim adapter As OdbcDataAdapter = New OdbcDataAdapter  
  
Dim selectCMD AS OdbcCommand = New OdbcCommand(selectSQL, connection)  
adapter.SelectCommand = selectCMD  
  
' Add Parameters and set values.  
selectCMD.Parameters.Add("@CountryRegion", OdbcType.VarChar, 15).Value = "UK"  
selectCMD.Parameters.Add("@City", OdbcType.VarChar, 15).Value = "London"  
  
Dim customers As DataSet = New DataSet  
adapter.Fill(customers, "Customers")  
// Assumes that connection is a valid OdbcConnection object.  
OdbcDataAdapter adapter = new OdbcDataAdapter();  
  
OdbcCommand selectCMD = new OdbcCommand(selectSQL, connection);  
adapter.SelectCommand = selectCMD;  
  
//Add Parameters and set values.  
selectCMD.Parameters.Add("@CountryRegion", OdbcType.VarChar, 15).Value = "UK";  
selectCMD.Parameters.Add("@City", OdbcType.VarChar, 15).Value = "London";  
  
DataSet customers = new DataSet();  
adapter.Fill(customers, "Customers");  

Notes

Si un nom de paramètre n’est pas fourni pour un paramètre, le paramètre reçoit un nom par défaut différentiel deParaN , en commençant par "Parameter1".If a parameter name is not supplied for a parameter, the parameter is given an incremental default name of ParameterN , starting with "Parameter1". Nous vous recommandons d’éviter la convention de nommage ParamétN lorsque vous fournissez ParameterCollectionun nom de paramètre, parce que le nom que vous fournissez pourrait entrer en conflit avec un nom de paramètre par défaut existant dans le .We recommend that you avoid the ParameterN naming convention when you supply a parameter name, because the name that you supply might conflict with an existing default parameter name in the ParameterCollection. Si le nom fourni existe déjà, une exception est levée.If the supplied name already exists, an exception is thrown.

Voir aussiSee also