Configuration des paramètres
S'applique à : 
.NET Framework .NET .NET Standard
Les objets de commande utilisent des paramètres pour passer des valeurs à des instructions SQL ou à des procédures stockées, en fournissant la vérification et la validation des types. Contrairement au texte de la commande, l'entrée de paramètre est traitée comme une valeur littérale et non pas comme du code exécutable. Ce comportement permet de se protéger contre les attaques « injection SQL », dans lesquelles un attaquant insère une commande qui compromet la sécurité sur le serveur dans une instruction SQL.
Les commandes paramétrées améliorent également les performances d'exécution des requêtes car elles permettent au serveur de base de données de faire correspondre la commande entrante avec un plan de requête mis en cache approprié. Pour plus d’informations, consultez Mise en cache et réutilisation du plan d'exécution et Réutilisation des paramètres et du plan d'exécution. Outre les avantages relatifs à la sécurité et aux performances, les commandes paramétrées fournissent une méthode pratique d'organisation des valeurs passées à une source de données.
Un objet DbParameter peut être créé à l'aide de son constructeur ou en l'ajoutant à la propriété DbParameterCollection en appelant la méthode Add de la collection DbParameterCollection . La méthode Add prendra comme entrée des arguments de constructeur ou un objet Parameter existant, selon le fournisseur de données.
Fournir la propriété ParameterDirection
Lorsque vous ajoutez des paramètres, vous devez fournir une propriété ParameterDirection pour les paramètres autres que les paramètres d'entrée. Le tableau ci-dessous indique les valeurs ParameterDirection que vous pouvez utiliser avec l'énumération ParameterDirection .
| Nom du membre | Description |
|---|---|
| Input | Le paramètre est un paramètre d'entrée. Cette valeur est la valeur par défaut. |
| InputOutput | Le paramètre peut être à la fois un paramètre d'entrée et de sortie. |
| Output | Le paramètre est un paramètre de sortie. |
| ReturnValue | Le paramètre représente une valeur de retour d'une opération telle qu'une procédure stockée, une fonction intégrée ou une fonction définie par l'utilisateur. |
Utiliser des espaces réservés de paramètres
La syntaxe des espaces réservés des paramètres dépend de la source de données. Le Fournisseur de données Microsoft SqlClient pour SQL Server gère différemment la dénomination et la spécification des paramètres et des espaces réservés de paramètres. Le Fournisseur de données SqlClient utilise des paramètres nommés au format @parametername.
Spécifier les types de données des paramètres
Le type de données d’un paramètre est spécifique au Fournisseur de données Microsoft SqlClient pour SQL Server. La spécification du type convertit la valeur de Parameter en Fournisseur de données Microsoft SqlClient pour le type de SQL Server avant de passer la valeur à la source de données. Vous pouvez également spécifier le type d'un Parameter de façon générique en affectant à la propriété DbType de l'objet Parameter un DbTypeparticulier.
Le type Fournisseur de données Microsoft SqlClient pour SQL Server d’un objet Parameter est déduit à partir du type .NET Framework de la valeur Value de l’objet Parameter ou à partir de DbType de l’objet Parameter. Le tableau suivant indique le type Parameter déduit en fonction de l'objet passé comme valeur Parameter ou du DbTypespécifié.
| Type .NET | DbType | SqlDbType |
|---|---|---|
| Boolean | Boolean |
Bit |
| Byte | Byte |
TinyInt |
byte[] |
Binary |
VarBinary. Cette conversion implicite échouera si le tableau d’octets est supérieur à la taille maximale d’un VarBinary, soit 8 000 octets. Pour des tableaux d'octets supérieurs à 8 000 octets, définissez explicitement SqlDbType. |
| Char | La déduction de SqlDbType à partir de char n’est pas prise en charge. | |
| DateTime | DateTime |
DateTime |
| DateTimeOffset | DateTimeOffset |
DateTimeOffset dans SQL Server 2008. La déduction de SqlDbType à partir de DateTimeOffset n’est pas prise en charge dans les versions de SQL Server antérieures à SQL Server 2008. |
| Decimal | Decimal |
Decimal |
| Double | Double |
Float |
| Single | Single |
Real |
| Guid | Guid |
UniqueIdentifier |
| Int16 | Int16 |
SmallInt |
| Int32 | Int32 |
Int |
| Int64 | Int64 |
BigInt |
| Object | Object |
Variant |
| String | String |
NVarChar. Cette conversion implicite échouera si le tableau d’octets est supérieur à la taille maximale d’un NVarChar, soit 4 000 octets. Pour les chaînes supérieures à 4 000 caractères, définissez explicitement SqlDbType. |
| TimeSpan | Time |
Time dans SQL Server 2008. La déduction de SqlDbType à partir de TimeSpan n’est pas prise en charge dans les versions de SQL Server antérieures à SQL Server 2008. |
| UInt16 | UInt16 |
La déduction de SqlDbType à partir de UInt16 n’est pas prise en charge. |
| UInt32 | UInt32 |
La déduction de SqlDbType à partir de UInt32 n’est pas prise en charge. |
| UInt64 | UInt64 |
La déduction de SqlDbType à partir de UInt64 n’est pas prise en charge. |
AnsiString |
VarChar |
|
AnsiStringFixedLength |
Char |
|
Currency |
Money |
|
Date |
Date dans SQL Server 2008. La déduction de SqlDbType à partir de Date n’est pas prise en charge dans les versions de SQL Server antérieures à SQL Server 2008. |
|
SByte |
La déduction de SqlDbType à partir de SByte n’est pas prise en charge. |
|
StringFixedLength |
NChar |
|
Time |
Time dans SQL Server 2008. La déduction de SqlDbType à partir de Time n’est pas prise en charge dans les versions de SQL Server antérieures à SQL Server 2008. |
|
VarNumeric |
La déduction de SqlDbType à partir de VarNumeric n’est pas prise en charge. |
|
| type défini par l'utilisateur (objet avec SqlUserDefinedAggregateAttribute) | SqlClient retourne toujours un Objet | SqlDbType.Udt si SqlUserDefinedTypeAttribute est présent ; sinon, Variant. |
Notes
Les conversions du type decimal vers d'autres types sont des conversions restrictives qui arrondissent la valeur décimale à la valeur entière la plus proche de zéro. Si le résultat de la conversion n’est pas représentable dans le type de destination, une exception OverflowException est levée.
Notes
Lorsque vous envoyez une valeur de paramètre Null au serveur, vous devez spécifier DBNull plutôt que null (Nothing en Visual Basic). Dans le système, la valeur null désigne un objet vide qui ne possède pas de valeur. DBNull est utilisé pour représenter des valeurs null.
Dériver les informations de paramètre
Les paramètres peuvent aussi être dérivés d'une procédure stockée à l'aide de la classe DbCommandBuilder . La classe SqlCommandBuilder fournit une méthode statique, DeriveParameters, qui remplit automatiquement la collection Paramètres d’un objet de commande qui utilise les informations sur les paramètres d’une procédure stockée. DeriveParameters remplace toutes les informations existantes sur les paramètres pour la commande.
Notes
La dérivation des informations de paramètre entraîne une baisse des performances car elle requiert un aller-retour supplémentaire vers la source de données pour extraire les informations. Si les informations sur les paramètres sont connues au moment du design, vous pouvez améliorer la performance de votre application en définissant les paramètres de manière explicite.
Pour plus d’informations, consultez Génération de commandes avec CommandBuilders.
Utilisation de paramètres avec SqlCommand et une procédure stockée
Les procédures stockées offrent de nombreux avantages dans les applications pilotées par des données. En utilisant des procédures stockées, les opérations de base de données peuvent être encapsulées dans une commande unique, optimisées pour de meilleures performances et améliorées avec une sécurité supplémentaire. Bien qu’une procédure stockée puisse être appelée en passant le nom de la procédure stockée suivie d’arguments de paramètre en tant qu’instruction SQL, l’utilisation de la Parameters collection de l’objet ADO.NET DbCommand vous permet de définir plus explicitement les paramètres de procédure stockée et d’accéder aux paramètres de sortie et aux valeurs de retour.
Remarque
Les instructions paramétrées sont exécutées sur le serveur à l'aide de sp_executesql, , ce qui permet la réutilisation des plans de requête. Les curseurs ou variables locaux dans le lot sp_executesql ne sont pas visibles pour le lot qui appelle sp_executesql. Les modifications dans le contexte de la base de données durent uniquement jusqu'à la fin de l'instruction sp_executesql . Pour plus d’informations, consultez sp_executesql (Transact-SQL).
Lorsque vous utilisez des paramètres avec un objet SqlCommand pour exécuter une procédure stockée SQL Server, les noms des paramètres ajoutés à la collection Parameters doivent correspondre à ceux des marqueurs de paramètres dans la procédure stockée. Microsoft SqlClient Fournisseur de données pour SQL Server ne prend pas en charge l’espace réservé du point d’interrogation ( ?) pour passer des paramètres à une instruction SQL ou à une procédure stockée. Il traite les paramètres de la procédure stockée comme des paramètres nommés et recherche les marqueurs de paramètres correspondants. Par exemple, la procédure stockée CustOrderHist est définie à l'aide d'un paramètre nommé @CustomerID. Lorsque votre code exécute la procédure stockée, il doit également utiliser un paramètre nommé @CustomerID.
CREATE PROCEDURE dbo.CustOrderHist @CustomerID varchar(5)
Exemple
Cet exemple montre comment appeler une procédure stockée SQL Server dans l'exemple de base de données Northwind . Le nom de la procédure stockée est dbo.SalesByCategory et il possède un paramètre d'entrée nommé @CategoryName avec un type de données nvarchar(15). Le code crée un nouveau SqlConnection à l'intérieur d'un bloc using pour que la connexion soit libérée une fois la procédure terminée. Les objets SqlCommand et SqlParameter sont créés et leurs propriétés sont définies. Un SqlDataReader exécute SqlCommand et retourne le jeu de résultats provenant de la procédure stockée, en affichant la sortie dans la fenêtre de console.
Notes
Au lieu de créer les objets SqlCommand et SqlParameter puis de définir les propriétés dans des instructions distinctes, vous pouvez choisir d'utiliser l'un des constructeurs surchargés pour définir plusieurs propriétés dans une instruction unique.
static void GetSalesByCategory(string connectionString,
string categoryName)
{
using (SqlConnection connection = new SqlConnection(connectionString))
{
// Create the command and set its properties.
SqlCommand command = new SqlCommand();
command.Connection = connection;
command.CommandText = "SalesByCategory";
command.CommandType = CommandType.StoredProcedure;
// Add the input parameter and set its properties.
SqlParameter parameter = new SqlParameter();
parameter.ParameterName = "@CategoryName";
parameter.SqlDbType = SqlDbType.NVarChar;
parameter.Direction = ParameterDirection.Input;
parameter.Value = categoryName;
// Add the parameter to the Parameters collection.
command.Parameters.Add(parameter);
// Open the connection and execute the reader.
connection.Open();
using (SqlDataReader reader = command.ExecuteReader())
{
if (reader.HasRows)
{
while (reader.Read())
{
Console.WriteLine("{0}: {1:C}", reader[0], reader[1]);
}
}
else
{
Console.WriteLine("No rows found.");
}
reader.Close();
}
}
}