Comment ajouter des paramètres de configuration personnalisés pour une application (ASP) .NET

Depuis sa publication, les applications et les composants ASP.NET ont utilisé le fichier web.config pour charger les paramètres nécessaires à leur fonctionnement. Cependant, l'ajout de paramètres personnalisés pour ajouter de la flexibilité et de la robustesse à une application ou à un composant n'est pas aussi simple que la plupart des gens le souhaiteraient. Cet article vous apprend à écrire les classes nécessaires à la gestion des éléments de configuration XML et à utiliser les paramètres qu'elles contiennent dans votre code..

Tutoriel republié

Toutes les quelques semaines, nous revoyons certains des articles préférés de nos lecteurs tout au long de l'histoire du site. Ce tutoriel a été publié pour la première fois en novembre 2012..

Le .NET Framework fournit une grande variété de paramètres pouvant être configurés dans web.config pour modifier le comportement d'un ou de plusieurs composants intégrés dans l'application. Pour certains développeurs, s'en tenir uniquement aux paramètres fournis par .NET Framework est suffisant. Mais beaucoup plus de développeurs ont besoin de contrôler un ensemble plus vaste de paramètres - soit pour des composants (écrits par eux-mêmes ou par un tiers), soit simplement pour un ensemble de valeurs qu'ils utilisent tout au long de leur application..

Le fichier web.config vous permet de définir des paramètres personnalisés avec le élément, mais il ne permet rien d’autre que de simples paires clé / valeur. L'élément XML suivant est un exemple de paramètre contenu dans :

Les paramètres clé / valeur peuvent certainement être utiles dans de nombreuses circonstances, mais les paramètres ne sont tout simplement pas assez flexibles pour des composants ou des paramètres robustes ou complexes.

Heureusement, Microsoft permet aux développeurs d’écrire des classes qui ajoutent un accès par programme aux paramètres de configuration personnalisés contenus dans web.config..

La section de configuration

Les paramètres de web.config sont classés en sections de configuration. Par exemple, les paramètres contenus dans le section concerne les paramètres ASP.NET pour votre application. Vous pouvez modifier le schéma d'authentification de votre application, ajouter ou supprimer des gestionnaires HTTP pour exécuter des fonctions spécifiques pour des types de fichiers spécifiques. le Cette section vous permet de contrôler de nombreux paramètres IIS7 sans avoir un accès direct à IIS7..

Une section de configuration est requise pour tous les paramètres non contenus dans élément. C'est donc une bonne idée de concevoir la structure XML de vos paramètres de configuration avant d'écrire du code..

La configuration utilisée à titre d'exemple dans ce tutoriel concerne un composant qui récupère des flux RSS ou Atom. Il ne fait aucune analyse, car cela sort du cadre de ce tutoriel. Au lieu de coder en dur la liste des flux à récupérer, le composant se fie à sa configuration pour contenir les noms et les URL des flux à récupérer. Le composant s'appelle FeedRetriever, et la structure XML souhaitée pour sa configuration ressemble à ceci:

le L'élément est défini par la section de configuration. En règle générale, une section de configuration doit partager le nom du composant pour lequel elle est conçue. le éléments seul enfant est le élément. Pensez à cet élément comme une collection de flux, car il contient plusieurs éléments (pensez à la méthode Add () dont disposent la plupart des objets de collection). Le choix d’utiliser un élément nommé "add" peut sembler étrange au début, mais le Cet élément est utilisé dans la majorité des sections de configuration intégrées. Donc, l’utiliser ici suit simplement les pratiques de conception mises en avant par Microsoft.

Celles-ci les éléments utilisent les attributs name, url et cache pour définir certains paramètres pour chaque flux. Naturellement, les attributs name et url sont obligatoires, mais l'attribut cache n'est pas et doit être défini par défaut sur true.

La configuration ci-dessus est simple. le élément pourrait être modifié pour contenir un autre enfant, appelé , contenir des paramètres qui s’appliqueraient à tous les flux. le Les éléments peuvent également utiliser des attributs supplémentaires, tels que cacheTime et requestFrequency, pour contrôler la durée de mise en cache d'un flux et la fréquence à laquelle il est demandé à l'hôte distant. Votre imagination est la seule limite à l'extensibilité et à la configuration..

Écrire le gestionnaire de configuration

Après avoir conçu la structure XML, l'étape suivante consiste à écrire un gestionnaire de configuration pour traiter les paramètres définis dans le XML. Le gestionnaire est principalement une classe qui hérite de System.Configuration.ConfigurationSection, mais il intègre également l'utilisation d'autres classes, telles que les classes dérivées de System.Configuration.ConfigurationElement et System.Configuration.ConfigurationElementCollection..

Les classes basées sur ConfigurationElement représentent des éléments individuels. c'est le bloc de construction d'une section de configuration. Les types dérivés de ConfigurationElementCollection représentent simplement des éléments contenant plus d'un type d'élément. Dans la configuration indiquée ci-dessus, le L'élément est représenté par une classe dérivée de ConfigurationElementCollection, et le les éléments sont représentés par une classe basée sur ConfigurationElement.

Représentant le Élément

Vous allez commencer avec le élément en le représentant avec une classe appelée FeedElement (dérivée de ConfigurationElement). Cette classe et les futures classes liées à la configuration résident dans l'espace de noms FeedRetriever.Configuration.

Chaque objet ConfigurationElement fonctionne comme un indexeur pour sa collection interne de valeurs de propriété. C’est cette collection interne, avec les attributs .NET, qui vous permet de mapper le Attributs de l'élément aux propriétés de la classe FeedElement.

Le code suivant est le code complet de la classe FeedElement:

Classe publique FeedElement: ConfigurationElement [ConfigurationProperty ("name", IsKey = true, IsRequired = true)] chaîne publique Name get return (chaîne) this ["name"];  set this ["name"] = value;  [ConfigurationProperty ("url", IsRequired = true, DefaultValue = "http: // localhost")] [RegexStringValidator (@ "https? \: // \ S +")] chaîne publique Url get return (chaîne) this ["url"];  set this ["url"] = valeur;  [ConfigurationProperty ("cache", IsRequired = false, DefaultValue = true)] public bool Cache get return (bool) this ["cache"];  set this ["cache"] = value;

La classe ConfigurationElement sert d'indexeur à une collection sous-jacente de propriétés de configuration (d'où la notation d'indexeur de this [keyValue]). En utilisant le mot-clé this et en accédant à la propriété sous-jacente à l'aide d'une clé de chaîne, vous pouvez obtenir et définir la valeur de la propriété sans avoir besoin d'un champ privé pour contenir ces données. La collection de propriétés sous-jacente stocke les données sous le type Object; par conséquent, vous devez convertir la valeur en tant que type approprié si vous souhaitez faire quoi que ce soit avec elle.

Les propriétés représentant les attributs XML sont décorées avec les attributs ConfigurationPropertyAttribute. Le premier paramètre de l'attribut ConfigurationPropertyAttribute est le nom de l'attribut XML trouvé dans la liste. élément. Après le premier paramètre, un ensemble de paramètres nommés est défini. La liste suivante est une liste complète des paramètres possibles:

DefaultValue - Obtient ou définit la valeur par défaut de la propriété décorée. Ce paramètre
n'est pas requis.
IsDefaultCollection - Obtient ou définit une valeur booléenne indiquant si la propriété
est la collection de propriétés par défaut pour la propriété décorée. Ce paramètre est
non requis, et la valeur par défaut est false.
IsKey - Obtient ou définit une valeur booléenne indiquant si cette propriété est une propriété de clé.
pour la propriété de l'élément décoré. Ce paramètre n'est pas obligatoire et sa valeur par défaut
la valeur est fausse.
IsRequired - Obtient ou définit une valeur booléenne indiquant si l'élément décoré
la propriété est requise. Ce paramètre n'est pas obligatoire et sa valeur par défaut est false.

La valeur par défaut de "http: // localhost" pour la propriété Url n'est pas une erreur. Le .NET Framework vous permet également de décorer les propriétés avec des attributs de validation, tels que RegexStringValidatorAttribute, qui décore la propriété Url. Ce validateur prend la valeur de la propriété Url et la valide par rapport à l'expression régulière fournie à l'attribut; Cependant, il valide également la propriété Url avant qu'il ne contienne les données de l'élément XML. La valeur par défaut de la propriété Url est une chaîne vide lors de la création initiale d'un objet FeedElement. Une chaîne vide ne valide pas l'expression régulière fournie. Par conséquent, le validateur lève une exception ArgumentException avant que des données ne soient chargées à partir du fichier XML..

Deux solutions de contournement sont possibles pour ce problème. La première approche modifie l'expression régulière pour autoriser les chaînes vides. La deuxième approche attribue une valeur par défaut à la propriété. Ce n'est pas grave dans ce cas particulier. Même avec une valeur par défaut, l’attribut url est toujours un attribut requis dans element - l'application lève une exception ConfigurationErrorsException si l'élément n'a pas d'attribut url.

Il existe plusieurs autres attributs de validation dans l'espace de noms System.Configuration pour valider les données affectées aux propriétés et les attributs XML auxquels elles sont mappées. La liste suivante répertorie tous les attributs du validateur dans l'espace de noms System.Configuration:

CallbackValidatorAttribute - Fournit une association entre un objet CallbackValidator et le code à valider - permet
validation dynamique pour une valeur de configuration.
IntegerValidatorAttribute - Valide à l'aide d'un objet IntegerValidator pour déterminer si la valeur de configuration se situe dans ou hors d'une plage spécifique..
LongValidatorAttribute - Valide à l'aide d'un objet LongValidator pour déterminer si la valeur de configuration se situe dans ou en dehors d'une plage spécifique..
PositiveTimeSpanValidatorAttribute - Valide à l'aide d'un objet PositiveTimeSpanValidator pour des valeurs de configuration TimeSpan positives.
RegexStringValidatorAttribute - Valide à l'aide d'un objet RegexStringValidator pour déterminer si la valeur de configuration est conforme à l'expression régulière..
StringValidatorAttribute - Valide à l'aide d'un objet StringValidator pour s'assurer que la valeur de configuration répond à certains critères - tels que la longueur de la chaîne et les caractères non valides..
SubclassTypeValidatorAttribute - Valide à l'aide d'un objet SubclassTypeValidator pour déterminer si la valeur de configuration dérive d'un type donné..
TimeSpanValidatorAttribute - Valide à l'aide d'un objet TimeSpanValidator pour déterminer si la valeur de configuration se situe dans ou hors d'une plage spécifique..

À l'exception de CallbackValidatorAttribute, il n'est pas nécessaire de créer les objets de validation correspondants à utiliser avec les attributs de validation. Le runtime .NET crée les objets de validation appropriés pour vous et les attributs contiennent les paramètres nécessaires à la configuration des objets de validation..

Ce petit morceau de code est tout ce qui est nécessaire pour représenter par programme des éléments. La prochaine étape consiste à écrire une classe qui représente le élément.

Écrire une classe de collection d'éléments

La représentation XML de la L'élément est celui d'une collection d'éléments de fil. De même, la représentation programmatique du element est une collection d'objets FeedElement. Cette classe, appelée FeedElementCollection, dérive de la classe abstraite ConfigurationElementCollection..

La classe ConfigurationElementCollection contient plusieurs membres, mais deux seulement sont marqués comme abstraits. Ainsi, la plus simple implémentation de ConfigurationElementCollection a deux méthodes:

CreateNewElement () - Crée un nouvel objet ConfigurationElement (FeedElement dans ce
Cas).
GetElementKey () - Obtient la clé d’élément pour un élément de configuration spécifié (le
Propriété Name des objets FeedElement dans ce cas).

Dans cet esprit, consultez le code complet de la classe FeedElementCollection ci-dessous:

[ConfigurationCollection (typeof (FeedElement))] classe publique FeedElementCollection: ConfigurationElementCollection protégé substitue ConfigurationElement CreateNewElement () retour new newElementElement ();  objet de substitution protégé GetElementKey (élément ConfigurationElement) return (élément (FeedElement)). .Name;

Un ConfigurationCollectionAttribute décore cette classe de collection. Le premier paramètre de l'attribut est un objet Type - le type des éléments contenus dans la collection. Dans ce cas, il s'agit du type FeedElement. Une fois que le paramètre type contient plusieurs paramètres nommés, vous pouvez les transmettre à l'attribut. Ceux-ci sont énumérés ci-dessous:

AddItemName - Définit le nom du élément de configuration. Par exemple,
définir cela comme "alimentation" nécessiterait la éléments dans le
configuration à changer pour .
ClearItemsName - Définit le nom du élément de configuration (utilisé
pour effacer tous les articles de la collection).
RemoveItemName - Définit le nom de la élément de configuration (utilisé
supprimer un article de la collection).

Laissant ces paramètres nommés vides par défaut, leur , , .

Ecriture de la classe FeedRetreiverSection

La classe finale, appelée FeedRetrieverSection, dérive de ConfigurationSection et représente le élément. C’est la classe la plus simple des classes de configuration, car la seule condition à remplir est de fournir un accès par programme au élément (le FeedElementCollection).

Classe publique FeedRetrieverSection: ConfigurationSection [ConfigurationProperty ("feeds", IsDefaultCollection = true)] public FeedElementCollection Feeds get return (FeedElementCollection) this ["feeds"]];  set this ["feeds"] = valeur;

Une propriété, de type FeedElementCollection et appelée Feeds, est décorée avec un ConfigurationPropertyAttribute - en la mappant à la élément.

Modification de web.config

Une fois le gestionnaire de configuration terminé, vous pouvez ajouter les éléments appropriés à web.config. le section peut aller n’importe où dans le fichier tant qu’il s’agit d’un descendant direct de l’élément racine (le élément). Le placer dans une autre section de configuration entraîne une erreur.

La prochaine étape consiste à ajouter un

élément enfant à . le

L'élément a deux attributs d'intérêt:

name - Nom de l'élément de la section de configuration. Dans ce cas, le nom est feedRetriever.
type - Nom qualifié de la classe associée à la section et, si nécessaire,
le nom de l'assembly dans lequel la classe réside. Dans ce cas, le nom qualifié
est FeedRetriever.Configuration.FeedRetrieverSection. Si il réside dans un séparé
assembly, l'attribut type aurait la valeur "FeedRetriever.Configuration.FeedRetrieverSection,
", où est le nom de l'assemblée
sans les équerres.

Le suivant

élément est ce que vous ajoutez à un fichier web.config, sous , lorsque les classes de configuration ne résident pas dans un assemblage séparé (comme dans le cas du téléchargement de code):

Votre application est maintenant correctement configurée pour utiliser les classes FeedRetrieverSection, FeedElementCollection et FeedElement afin de vous accorder un accès par programme aux paramètres personnalisés contenus dans le fichier. section de configuration dans web.config. Alors, comment accéder à ces paramètres à partir de votre code?

Accéder aux données de configuration à partir du code

L'espace de noms System.Configuration contient une classe statique appelée ConfigurationManager. Si vous utilisez le section pour héberger vos chaînes de connexion, vous connaissez au moins ConfigurationManager. Il a une méthode appelée GetSection (), qui accepte une chaîne contenant le nom de la section de configuration à récupérer. Le code suivant montre ceci (supposons que l'utilisation de System.Configuration se trouve en haut du fichier de code):

FeedRetrieverSection config = ConfigurationManager.GetSection ("feedRetriever") en tant que FeedRetrieverSection;

La méthode GetSection () renvoie une valeur de type Object. Elle doit donc être convertie en un type quelconque utilisé par le gestionnaire pour cette section. Ce code récupère la section nommée feedRetriever et transforme le résultat en tant que FeedRetrieverSection. Une fois que vous avez l'objet, vous pouvez commencer à accéder aux données de configuration par programme.

Pour vous donner une idée de la façon dont les paramètres de configuration peuvent être utilisés dans votre composant ou votre application, le code suivant est une implémentation très basique du composant FeedRetriever..

Classe publique FeedRetriever public static FeedRetrieverSection _Config = ConfigurationManager.GetSection ("feedRetriever") en tant que FeedRetrieverSection;
public statique void GetFeeds () foreach (FeedElement feedEl dans _Config.Feeds) // demande de requête HttpWebRequest request = (HttpWebRequest) WebRequest.Create (feedEl.Url); HttpWebResponse response = (HttpWebResponse) request.GetResponse (); if (response.StatusCode == HttpStatusCode.OK) string feedData = String.Empty; using (lecteur StreamReader = new StreamReader (response.GetResponseStream ())) feedData = reader.ReadToEnd ();  if (feedEl.Cache) // nom de fichier du fichier de cache chaîne filename = String.Format ("0 _ 1 .xml", feedEl.Name, DateTime.Now.Ticks); // fichier de cache utilisant (StreamWriter writer = nouveau StreamWriter (@ "C: \" + nom du fichier)) writer.Write (feedData);

Tout d'abord, une variable statique appelée _Config de type FeedRetreiverSection est déclarée et est affectée à une valeur en appelant ConfigurationManager.GetSection (). Rendre la variable statique est un choix de conception. Ainsi, tous les membres de la classe, qu’il s’agisse d’instance ou de statique, auraient accès aux paramètres de configuration sans avoir à appeler plusieurs fois à GetSection ()..

Une fois que vous avez récupéré le gestionnaire de section avec GetSection (), vous avez un accès complet aux objets créés à partir de vos classes de gestionnaire. La première ligne de GetFeeds () est une boucle pour chaque boucle qui parcourt tous les objets FeedElement contenus avec l'objet FeedElementCollection renvoyé par la propriété Feeds. Cela vous donne un accès direct à ces objets FeedElement, ce qui facilite l'accès au nom, à l'URL et aux paramètres de cache de chaque flux..

Lors de chaque itération de la boucle, la méthode effectue une demande à l'aide de la propriété Url de l'objet FeedElement. Si la requête aboutit, les données du flux sont récupérées et stockées dans la variable feedData. Ensuite, le code vérifie la propriété Cache de l'objet FeedElement pour déterminer si le flux doit être mis en cache ou non. La mise en cache du flux implique la construction d'un nom de fichier en utilisant la propriété Name de l'objet FeedElement et la date et l'heure actuelles. Ensuite, un objet StreamWriter crée le fichier et y écrit les données du flux..

Comme vous pouvez le constater, l’utilisation des classes du gestionnaire de section de configuration est essentielle pour récupérer et utiliser les paramètres personnalisés résidant dans web.config. Cela nécessite certes plus de temps et d’efforts de votre part, mais cela facilite certainement la configuration de votre application ou de votre composant pour vous-même et les autres développeurs..

Vendez vos composants .NET sur CodeCanyon!

Saviez-vous que nous avons une catégorie .NET sur CodeCanyon. Si vous êtes un développeur .NET qualifié, pourquoi ne pas vendre vos scripts / composants / contrôles en tant qu'auteur et gagner entre 40 et 70% du total de vos ventes?

Suivez-nous sur Twitter ou abonnez-vous au fil RSS Nettuts + pour obtenir les meilleurs tutoriels de développement Web sur le Web..

Code