Parametri DataAdapter

Articolo
04/10/2024

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 usate 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 usa 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, si chiama l'istruzione UPDATE, che usa un identificatore univoco per identificare la riga della tabella da aggiornare. In genere, il valore dell'identificatore univoco corrisponde a quello del campo di una chiave primaria. Nell'istruzione UPDATE vengono usati 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 vengono usati come segnaposto i punti interrogativi (?).

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 usando 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à usato il valore di riga Current predefinito.

Nota

Sia per le operazioni Fill del DataAdapter che per i metodi Get del DataReader, il tipo .NET Framework viene dedotto dal tipo restituito dal provider di dati .NET Framework. I tipi e i metodi di accesso di .NET Framework dedotti 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 usata da DataAdapter per recuperare il valore.

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

Enumerazione DataRowVersion	Descrizione
`Current`	Il parametro usa il valore corrente della colonna. Si tratta dell'impostazione predefinita.
`Default`	Il parametro usa il valore `DefaultValue` della colonna.
`Original`	Il parametro usa il valore originale della colonna.
`Proposed`	Il parametro usa 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 usata come SourceColumn per due parametri: @CustomerID (SET CustomerID = @CustomerID) e @OldCustomerID (WHERE CustomerID = @OldCustomerID). Il parametro @CustomerID viene usato per aggiornare la colonna CustomerID in base al valore corrente di DataRow. Di conseguenza, viene usato CustomerIDSourceColumn in cui il valore di SourceVersion è uguale a Current. Il parametro @OldCustomerID viene usato per identificare la riga corrente nell'origine dati. Poiché il valore della colonna corrispondente viene individuato nella versione Original della riga, verrà usato lo stesso oggetto SourceColumn (CustomerID) con SourceVersionOriginal.

Uso 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 static SqlDataAdapter CreateSqlDataAdapter(SqlConnection connection)
{
    SqlDataAdapter adapter = new()
    {
        MissingSchemaAction = MissingSchemaAction.AddWithKey,

        // Create the commands.
        SelectCommand = new SqlCommand(
        "SELECT CustomerID, CompanyName FROM CUSTOMERS", connection),
        InsertCommand = new SqlCommand(
        "INSERT INTO Customers (CustomerID, CompanyName) " +
        "VALUES (@CustomerID, @CompanyName)", connection),
        UpdateCommand = new SqlCommand(
        "UPDATE Customers SET CustomerID = @CustomerID, CompanyName = @CompanyName " +
        "WHERE CustomerID = @oldCustomerID", connection),
        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

Segnaposti di parametri OleDb

Per gli oggetti OleDbDataAdapter e OdbcDataAdapter, è necessario usare 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, usare 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, a partire da "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.

Parametri DataAdapter

Parameter.SourceColumn e Parameter.SourceVersion

Uso di parametri SqlClient

Segnaposti di parametri OleDb

Esempio di OleDb

Parametri Odbc

Vedi anche

Risorse aggiuntive