Parametri di DataAdapter (ADO.NET)

Articolo
05/20/2011

DbDataAdapter dispone di quattro proprietà che consentono di recuperare e aggiornare i dati dell'origine dati. La proprietà SelectCommand restituisce i dati dall'origine dati, mentre le proprietà InsertCommand, UpdateCommand e DeleteCommand vengono utilizzate per gestire le modifiche nell'origine dati. La proprietà SelectCommand deve essere impostata prima di chiamare il metodo Fill di DataAdapter. È necessario impostare la proprietà InsertCommand, UpdateCommand o DeleteCommand prima di chiamare il metodo Update di DataAdapter a seconda delle modifiche apportate ai dati in DataTable, Se ad esempio sono state aggiunte righe, è necessario impostare la proprietà InsertCommand prima di chiamare Update. Quando Update elabora una riga inserita, aggiornata o eliminata, DataAdapter utilizza la rispettiva proprietà Command per l'operazione. Le informazioni correnti sulla riga modificata vengono passate all'oggetto Command mediante la raccolta Parameters.

Quando si aggiorna una riga nell'origine dati, viene chiamata l'istruzione UPDATE che utilizza un identificatore univoco per identificare la riga nella tabella da aggiornare. In genere, il valore dell'identificatore univoco corrisponde a quello del campo di una chiave primaria. Nell'istruzione UPDATE vengono utilizzati i parametri che contengono sia l'identificatore univoco che le colonne e i valori da aggiornare, come illustrato nell'istruzione Transact-SQL seguente.

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

Nota
La sintassi per i segnaposto dei parametri varia in base all'origine dati.In questo esempio vengono mostrati i segnaposto per un'origine dati SQL Server.Per i parametri System.Data.OleDb e System.Data.Odbc viene utilizzato come segnaposto il punto interrogativo (?).

In questo esempio di Visual Basic, il campo CompanyName viene aggiornato con il valore del parametro @CompanyName nella riga in cui CustomerID è uguale al valore del parametro @CustomerID . Le informazioni della riga modificata vengono recuperate dai parametri mediante la proprietà SourceColumn dell'oggetto SqlParameter. Di seguito sono riportati i parametri della precedente istruzione UPDATE di esempio. Nel codice si presuppone che la variabile adapter rappresenti un oggetto SqlDataAdapter valido.

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

Il metodo Add della raccolta Parameters accetta il nome del parametro, il tipo di dati, le dimensioni (se applicabili al tipo) e il nome dell'oggetto SourceColumn da DataTable. Notare che la proprietà SourceVersion del parametro @CustomerID è impostata su Original. Questo valore assicura che l'aggiornamento della riga esistente nell'origine dati venga eseguito se il valore della colonna o delle colonne identificative è stato cambiato nell'oggetto DataRow modificato. In questo caso il valore Original della riga corrisponde al valore corrente nell'origine dati e il valore Current della riga contiene il valore aggiornato. SourceVersion non è impostato per il parametro @CompanyName, pertanto verrà utilizzato il valore di riga Current predefinito.

Nota
Per le operazioni Fill del DataAdapter e i metodi Get del DataReader, il tipo .NET Framework viene inferito dal tipo restituito dal provider di dati .NET Framework.I tipi .NET Framework inferiti e metodi delle funzioni di accesso per i tipi di dati Microsoft SQL Server, OLE DB e ODBC sono descritti in Mapping dei tipi di dati in ADO.NET.

Parameter.SourceColumn e Parameter.SourceVersion

È possibile passare SourceColumn e SourceVersion come argomenti del costruttore Parameter o impostarli come proprietà di un oggetto Parameter esistente. SourceColumn è il nome dell'oggetto DataColumn derivato da DataRow in cui viene recuperato il valore di Parameter. SourceVersion specifica la versione di DataRow utilizzata da DataAdapter per recuperare il valore.

Nella tabella seguente sono elencati i valori di enumerazione DataRowVersion disponibili per l'utilizzo con SourceVersion.

Enumerazione DataRowVersion	Descrizione
Current	Il parametro utilizza il valore corrente della colonna. Si tratta dell'impostazione predefinita.
Default	Il parametro utilizza il valore DefaultValue della colonna.
Original	Il parametro utilizza il valore originale della colonna.
Proposed	Il parametro utilizza un valore proposto.

Nell'esempio di codice SqlClient della sezione successiva viene definito un parametro per un oggetto UpdateCommand in cui la colonna CustomerID viene utilizzata come SourceColumn per due parametri: @CustomerID (SET CustomerID = @CustomerID) e @OldCustomerID (WHERE CustomerID = @OldCustomerID). Il parametro @CustomerID viene utilizzato per aggiornare la colonna CustomerID in base al valore corrente di DataRow. Di conseguenza, viene utilizzato SourceColumn CustomerID in cui il valore di SourceVersion è uguale a Current. Il parametro @OldCustomerID viene utilizzato per identificare la riga corrente nell'origine dati. Poiché il valore della colonna corrispondente viene individuato nella versione Original della riga, verrà utilizzato lo stesso oggetto SourceColumn (CustomerID) con SourceVersion Original.

Utilizzo di parametri SqlClient

Nell'esempio seguente viene illustrato come creare un oggetto SqlDataAdapter e impostare MissingSchemaAction su AddWithKey per recuperare informazioni aggiuntive sullo schema dal database. Vengono impostate le proprietà SelectCommand, InsertCommand, UpdateCommand e DeleteCommand e i relativi oggetti SqlParameter corrispondenti vengono aggiunti alla raccolta Parameters. Il metodo restituisce un oggetto SqlDataAdapter.

Public Function CreateSqlDataAdapter( _
    ByVal connection As SqlConnection) As SqlDataAdapter

    Dim adapter As SqlDataAdapter = 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

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;
}

Segnaposti di parametri OleDb

Per gli oggetti OleDbDataAdapter e OdbcDataAdapter è necessario utilizzare il punto interrogativo (?) come segnaposto per identificare i parametri.

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 = ?";

Le istruzioni delle query con parametri definiscono i parametri di input e di output che è necessario creare. Per creare un parametro, utilizzare il metodo Parameters.Add o il costruttore Parameter per specificare il nome della colonna, il tipo di dati e le dimensioni. Per tipi di dati intrinseci, ad esempio Integer, non è necessario includere le dimensioni oppure è possibile specificare quelle predefinite.

Nell'esempio di codice seguente vengono creati i parametri per un'istruzione SQL e viene quindi compilato un DataSet.

Esempio di OleDb

' 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");

Parametri Odbc

' 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");

Nota
Se non viene specificato un nome, al parametro viene assegnato il nome predefinito incrementale ParameterN, che inizia con "Parameter1".Si consiglia di evitare la convenzione di denominazione ParameterN quando si specifica il nome del parametro, in quanto il nome indicato può entrare in conflitto con un nome predefinito esistente in ParameterCollection.Se il nome fornito è già presente, viene generata un'eccezione.

Se non viene specificato un nome, al parametro viene assegnato il nome predefinito incrementale ParameterN, che inizia con "Parameter1".Si consiglia di evitare la convenzione di denominazione ParameterN quando si specifica il nome del parametro, in quanto il nome indicato può entrare in conflitto con un nome predefinito esistente in ParameterCollection.Se il nome fornito è già presente, viene generata un'eccezione.