Enterprise Library Configuration Application Block

1. Enterprise LibraryConfiguration Application Block Scott Densmore Software Design Engineer Ron JacobsProduct Manager

2. Overview What you must know to use the block Defining your config data Creating the meta-config Writing Configuration Reading Configuration Getting beyond the surface Understanding Storage providers and transformers Caching and Change Notifications For really advanced users Key extensibility points Community Extensions Configuration Design Time Agenda

3. Poll: How deep do you want to go? • [Live Meeting Multiple Choice Poll. Use Live Meeting > Edit Slide Properties... to edit.] • Tell me what I need to know to use the block • I'd like to understand the architecture and design as well • I'm thinking about extending the block • I don't really know - just go and I'll hang on for the ride

4. Overview

5. Sound familiar? • Debates about where to store configuration information • Custom in-house configuration components for reading configuration settings, each with different usage models and behaviors • Development of separate tools to allow you to create and modify configuration data in storage • Inexact understanding of how changes in the underlying configuration store will be applied in running application

6. Configuration Scenarios • Application needs to read and/or write complex configuration data at runtime • Application which must store sensitive data (password) in configuration • Application or block with design time support in the form of property pages, wizards and validation to assist developers in getting configuration right • Administrator deploying an application needs to change configuration and you want to provide a better experience than using notepad to edit XML configuration files

7. Configuration Application Block (Runtime) Improves integration Supports pluggable storage providers and transformations Improves ease of use Read & Write Model Supports object graphs Notifications when config store changes Improves Security Supports Encryption Configuration Tool (Design-time) Uses Configuration Application Block Improves ease of use Wizards Property Sheets Validation Improves Security Supports Encryption Masking Configuration Block • Provides a general purpose configuration runtime which allows applications to easily read and write configuration data from configurable storage locations

8. What you must know to use the configuration block

9. Defining Configuration Data • You create a class which defines your configuration data • Must be serializeable (XmlSerializer) • Can be arbitrarily complex Public Class EditorFontData Private fontName As String Private fontSize As Double Private fontStyle As Integer End Class

10. Configuration Sections and Metadata • Configuration settings are grouped together in configuration sections • You configure a transformer and storage provider for each configuration section • Configuration metadata is stored in the application domain configuration file • app.config or web.config • Configuration metadata is used by the AbstractFactory to determine the storage provider and transformer to use for loading the configuration section data

11. Declaring a Configuration Section <configuration> <configurationSections> <configurationSection name="SalesData" encrypt="false"> <storageProvider xsi:type="XmlFileStorageProviderData" name="XML File Storage Provider" path="salesdata.config" /> <dataTransformer xsi:type="XmlSerializerTransformerData" name="Xml Serializer Transformer"> <includeTypes /> </dataTransformer> </configurationSection> </configurationSections> </configuration>

12. Configuration Console • The Configuration Console reads and writes the configuration metadata • Sections can be easily added and deleted • Properties are displayed for easy editing • Validation ensures properties have appropriate values

13. Declaring a Configuration Section • The XML File Storage Provider has a property for the path and filename of the XML file that contains the configuration information • The path is relative to the location of the app.config file

14. View/Application Share: Defining Configuration Data • [Live Meeting View/Application Share. Use Live Meeting > Edit Slide Properties... to edit.]

15. Writing Configuration Information • The application block provides an API to allow you to write configuration section information • Entire section is written (no merge) • The meta-configuration file must contain a configuration section definition for the section to be written • Example: writing a string value string servername = "MyServer"; ConfigurationManager.WriteConfiguration("SalesData", servername);

16. Writing Config Example Public Class EditorFontData Private fontName As String Private fontSize As Double Private fontStyle As Integer End Class Dim configData As EditorFontData = New EditorFontData configData.Name = fontDialog.Font.Name configData.Size = fontDialog.Font.Size configData.Style = Convert.ToInt32(fontDialog.Font.Style) ConfigurationManager.WriteConfiguration("EditorSettings", configData)

17. Reading Configuration Data • Single line of code to read configuration data • The transformer and/or storage provider are responsible for returning the expected type • XML Serializer Transformer deserializes XmlNodes into the object types Read a string Dim conString As String conString = DirectCast(ConfigurationManager.GetConfiguration("connectionstring", String ) // Read an object with multiple properties Dim configData As EditorFontData = _ DirectCast( ConfigurationManager.GetConfiguration("EditorSettings"), _ EditorFontData)

18. View/Application Share: Writing / Reading Configuration Data • [Live Meeting View/Application Share. Use Live Meeting > Edit Slide Properties... to edit.]

19. Getting beyond the surface

20. Storage Providers and Transformers • Decouples reading and writing of configuration data from the specifics of the underlying data store • Uses storage providers and transformers to transfer data between the application and the physical store • AbstractFactory pattern is used to instantiate providers • Storage providers are objects that can read or write to a particular physical store, such as an XML file or a SQL database • Transformersare objects which convert the configuration data between the storage format and the application format.

21. Configuration Sections and Metadata

22. Included Providers The application block includes a storage provider for XML file storage, which reads and writes XML files Each configuration section is corresponds to a different XML file The XML storage provider returns an XmlNode object The application block includes a transformer for serializing/deserializing XmlNode objects

23. Example Configuration Data <?xml version="1.0" encoding="utf-8"?> <EditorSettings> <xmlSerializerSection type="ConfigurationQuickStart.EditorFontData, ConfigurationRuntimeData, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"> <EditorFontData xmlns:xsd="http://www.w3.org/2001/XMLSchema“ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Name>Microsoft Sans Serif</Name> <Size>8.25</Size> <Style>2</Style> </EditorFontData> </xmlSerializerSection> </EditorSettings>

24. Managing XML Configuration Files • All XML configuration files must be deployed to the correct location for application execution • Recommendations • During development, add configuration section file to the project directory • Use Configuration Console to open and modify the app.config file in the project directory • Use Visual Studio post-build event to copy the file to the appropriate executable directory • Check the QuickStarts for other post-build options • http://www.ronjacobs.com/TipPostBuild.htm copy "$(ProjectDir)*.config" "$(ProjectDir)$(OutDir)."

25. Caching Configuration Data • Configuration information is cached by the application block • The cache is cleared when the storage provider detects that configuration settings have changed • Always use ConfigurationManager.GetConfig for retrieving configuration settings • Do not cache configuration data elsewhere

26. Responding to Configuration Change Notifications • The application block provides an event mechanism to allow applications to be notified when changes occur to configuration settings in storage • This capability is dependent upon the storage provider being able to recognize configuration changes • Some providers may not support this • The XML File Storage Provider detects changes and supports notification

27. Responding to Configuration Change Notifications • Create an event handler private void OnConfigurationChanged(object sender, ConfigurationChangedEventArgs args) { // Take appropriate action, e.g. refresh settings } Register for event ConfigurationManager.ConfigurationChanged += new ConfigurationChangedEventHandler(OnConfigurationChanged);

28. Protecting Configuration Information • XML configuration files are saved as plain text by default • The application block supports encryption/decryption of configuration section settings in storage • You select a platform symmetric encryption provider to use for encrypting the configuration data • The keys are saved in plain text files by default • You can use ACLS, DPAPI or other means to protect the keys

29. Protecting Configuration Information • The encryption configuration information is used for any configuration section to be encrypted

30. Securing Connection Strings

31. Securing Connection Strings

32. Securing Connection Strings • Each configuration section has a property which determines if that section’s configuration information will be encrypted

33. View/Application Share: Caching and Change Notifications • [Live Meeting View/Application Share. Use Live Meeting > Edit Slide Properties... to edit.]

34. For really advanced users

35. Key Extensibility Points • Custom storage provider • Derive from StorageProvider • If writing, implement IStorageProviderWriter • Custom transformer • Derive from TransformerProvider • Download patch 1462 from community site • Plus… • Anything and everything – you have the source code! • Please post extensions and suggestions to the community

36. Other providers • App.config provider • Stores settings in your app.config or web.config • SQL Server provider • Registry provider • Available at the community site • http://workspaces.gotdotnet.com/entlib

37. Exposing Configuration Settings to the Configuration Console

38. Configuration Console Configuration nodes Reference to another node Properties for Client Settings configuration node displayed in property pane Validation errors Property description

39. Enterprise Library v1 Caching Exceptions Legend Security Data Access Logging Dependency Plug-in Crypto Configuration Config Tool

40. Announcing: Enterprise Library 1.0 Download it Today! http://www.microsoft.com/practices

41. http://www.microsoft.com/practices • [Live Meeting Web Page. Use Live Meeting > Edit Slide Properties... to edit.]