From a1c647ed55fc545220c8c99884112ad1c7a0d2ea Mon Sep 17 00:00:00 2001 From: Tianqi Zhang Date: Sat, 1 Apr 2017 11:03:37 +0800 Subject: [PATCH] test config change --- .openpublishing.publish.config.json | 3 - docfx.json | 42 +- .../ConfigurationManager.xml | 953 ++++++++++++++++++ 3 files changed, 982 insertions(+), 16 deletions(-) create mode 100644 xml/System.Configuration/ConfigurationManager.xml diff --git a/.openpublishing.publish.config.json b/.openpublishing.publish.config.json index 281bf09120f43..51264a776f283 100644 --- a/.openpublishing.publish.config.json +++ b/.openpublishing.publish.config.json @@ -21,9 +21,6 @@ }, "build_entry_point": "docs", "template_folder": "_themes", - "customized_template_paths": [ - "_dependentPackages/memberpage.plugins/content" - ], "customized_tasks": { "docset_prebuild": [ "_dependentPackages/ECMA2Yaml/tools/Run.ps1", diff --git a/docfx.json b/docfx.json index cc81a0ff8f6d6..7aca2deca65c6 100644 --- a/docfx.json +++ b/docfx.json @@ -1,21 +1,16 @@ { - "merge": { - "content": [ - { - "files": [ - "api/**/*.yml" - ] - } - ], - "dest": ".", - "tocMetadata": "version" - }, "build": { "content": [ { "files": [ "api/**/*.yml", "api/**/*.md" + ], + "exclude": [ + "api/overwrites/**", + "samples/**/*.*", + "**/includes/**", + "***/contributing.md" ] }, { @@ -25,6 +20,8 @@ "src": "docs", "dest": "articles", "exclude": [ + "api/overwrites/**", + "samples/**/*.*", "**/includes/**", "***/contributing.md" ] @@ -50,12 +47,31 @@ "dest": "articles", "exclude": [ "**/obj/**", - "add/codesnippet/**/*.*", + "samples/**/*.*", "_themes/DocPacker/**" ] + }, + { + "files": [ + "**/*.png", + "**/*.svg", + "**/*.jpg", + "**/*.gif", + "**/*.bmp" + ], + "src": "add", + "dest": "articles", + "exclude": [ + "metadata/**/*.*" + ] } ], - "overwrite": "apidoc/*.md", + "overwrite": { + "files": [ + "api/overwrites/**/*.md", + "apidoc/*.md" + ] + }, "externalReference": [], "globalMetadata": { "breadcrumb_path": "/dotnet/toc.json", diff --git a/xml/System.Configuration/ConfigurationManager.xml b/xml/System.Configuration/ConfigurationManager.xml new file mode 100644 index 0000000000000..31e23e3839965 --- /dev/null +++ b/xml/System.Configuration/ConfigurationManager.xml @@ -0,0 +1,953 @@ + + + + + + System.Configuration + 4.0.0.0 + + + System.Object + + + + Provides access to configuration files for client applications. This class cannot be inherited. + + class enables you to access machine, application, and user configuration information. This class replaces the class, which is deprecated. For web applications, use the class. + + To use the class, your project must reference the `System.Configuration` assembly. By default, some project templates, like Console Application, do not reference this assembly so you must manually reference it. + +> [!NOTE] +> The name and location of the application configuration file depend on the application's host. For more information, see [NIB: Application Configuration Files](http://msdn.microsoft.com/en-us/0d05b1b8-b18b-43d8-bb3c-526ff0c44fe0). + + You can use the built-in types or derive from them to handle configuration information. By using these types, you can work directly with configuration information and you can extend configuration files to include custom information. + + The class includes members that enable you to perform the following tasks: + +- Read a section from a configuration file. To access configuration information, call the method. For some sections such as `appSettings` and `connectionStrings`, use the and classes. These members perform read-only operations, use a single cached instance of the configuration, and are multithread aware. + +- Read and write configuration files as a whole. Your application can read and write configuration settings at any level, for itself or for other applications or computers, locally or remotely. Use one of the methods provided by the class to open a configuration file such as SampleApp.exe.config. These methods return a object that in turn exposes methods and properties you can use to work with the associated configuration files. The methods perform read or write operations and create the configuration data every time that a file is written. + +- Support configuration tasks. The following types are used to support various configuration tasks: + + - + + - + + - + + - + + - + + - + + - + + In addition to working with existing configuration information, you can create and work with custom configuration elements by extending the built-in configuration types such as the , , , and classes. For an example of how to extend a built-in configuration type programmatically, see . For an example of how to extend a built-in configuration type that uses the attribute-based model, see . + + + +## Examples + The first example shows a simple console application that reads application settings, adds a new setting, and updates an existing setting. + +```csharp +using System; +using System.Configuration; + +namespace ConsoleApplication1 +{ + class Program + { + static void Main(string[] args) + { + ReadAllSettings(); + ReadSetting("Setting1"); + ReadSetting("NotValid"); + AddUpdateAppSettings("NewSetting", "May 7, 2014"); + AddUpdateAppSettings("Setting1", "May 8, 2014"); + ReadAllSettings(); + } + + static void ReadAllSettings() + { + try + { + var appSettings = ConfigurationManager.AppSettings; + + if (appSettings.Count == 0) + { + Console.WriteLine("AppSettings is empty."); + } + else + { + foreach (var key in appSettings.AllKeys) + { + Console.WriteLine("Key: {0} Value: {1}", key, appSettings[key]); + } + } + } + catch (ConfigurationErrorsException) + { + Console.WriteLine("Error reading app settings"); + } + } + + static void ReadSetting(string key) + { + try + { + var appSettings = ConfigurationManager.AppSettings; + string result = appSettings[key] ?? "Not Found"; + Console.WriteLine(result); + } + catch (ConfigurationErrorsException) + { + Console.WriteLine("Error reading app settings"); + } + } + + static void AddUpdateAppSettings(string key, string value) + { + try + { + var configFile = ConfigurationManager.OpenExeConfiguration(ConfigurationUserLevel.None); + var settings = configFile.AppSettings.Settings; + if (settings[key] == null) + { + settings.Add(key, value); + } + else + { + settings[key].Value = value; + } + configFile.Save(ConfigurationSaveMode.Modified); + ConfigurationManager.RefreshSection(configFile.AppSettings.SectionInformation.Name); + } + catch (ConfigurationErrorsException) + { + Console.WriteLine("Error writing app settings"); + } + } + } +} +``` + +```vb +Imports System.Configuration +Module Module1 + + Sub Main() + ReadAllSettings() + ReadSetting("Setting1") + ReadSetting("NotValid") + AddUpdateAppSettings("NewSetting", "May 7, 2014") + AddUpdateAppSettings("Setting1", "May 8, 2014") + ReadAllSettings() + End Sub + + Sub ReadAllSettings() + Try + Dim appSettings = ConfigurationManager.AppSettings + + If appSettings.Count = 0 Then + Console.WriteLine("AppSettings is empty.") + Else + For Each key As String In appSettings.AllKeys + Console.WriteLine("Key: {0} Value: {1}", key, appSettings(key)) + Next + End If + Catch e As ConfigurationErrorsException + Console.WriteLine("Error reading app settings") + End Try + End Sub + + Sub ReadSetting(key As String) + Try + Dim appSettings = ConfigurationManager.AppSettings + Dim result As String = appSettings(key) + If IsNothing(result) Then + result = "Not found" + End If + Console.WriteLine(result) + Catch e As ConfigurationErrorsException + Console.WriteLine("Error reading app settings") + End Try + End Sub + + Sub AddUpdateAppSettings(key As String, value As String) + Try + Dim configFile = ConfigurationManager.OpenExeConfiguration(ConfigurationUserLevel.None) + Dim settings = configFile.AppSettings.Settings + If IsNothing(settings(key)) Then + settings.Add(key, value) + Else + settings(key).Value = value + End If + configFile.Save(ConfigurationSaveMode.Modified) + ConfigurationManager.RefreshSection(configFile.AppSettings.SectionInformation.Name) + Catch e As ConfigurationErrorsException + Console.WriteLine("Error writing app settings") + End Try + End Sub + +End Module +``` + + The previous example assumes your project has an App.config file as shown below. + +```xml + + + + + + + + + + +``` + + The following example shows how to use a connection string to read data from a database. + +```csharp +using System; +using System.Configuration; +using System.Data.SqlClient; + +namespace ConsoleApplication1 +{ + class Program + { + static void Main(string[] args) + { + ReadProducts(); + } + + static void ReadProducts() + { + var connectionString = ConfigurationManager.ConnectionStrings["WingtipToys"].ConnectionString; + string queryString = "SELECT Id, ProductName FROM dbo.Products;"; + using (var connection = new SqlConnection(connectionString)) + { + var command = new SqlCommand(queryString, connection); + connection.Open(); + using (var reader = command.ExecuteReader()) + { + while (reader.Read()) + { + Console.WriteLine(String.Format("{0}, {1}", reader[0], reader[1])); + } + } + } + } + } +} +``` + +```vb +Imports System.Configuration +Imports System.Data.SqlClient +Module Module1 + + Sub Main() + ReadProducts() + End Sub + + Sub ReadProducts() + Dim connectionString = ConfigurationManager.ConnectionStrings("WingtipToys").ConnectionString + Dim queryString = "SELECT Id, ProductName FROM dbo.Products;" + Using connection As New SqlConnection(connectionString) + Dim command = New SqlCommand(queryString, connection) + connection.Open() + + Using reader As SqlDataReader = command.ExecuteReader() + While reader.Read() + Console.WriteLine(String.Format("{0}, {1}", reader(0), reader(1))) + End While + End Using + End Using + End Sub + +End Module +``` + + The previous example assumes your project has an App.config as shown below. + +```xml + + + + + + + + + +``` + + ]]> + + + The class enables programmatic access for editing configuration files. You use one of the Open methods provided by . These methods return a object, which in turn provides the required methods and properties to handle the underlying configuration files. You can access these files for reading or writing. + + To read the configuration files, use or to read configuration information. The user or process that reads must have the following permissions: + +- Read permission on the configuration file at the current configuration hierarchy level. + +- Read permissions on all the parent configuration files. + + If your application needs read-only access to its own configuration, we recommend that you use the method. This method provides access to the cached configuration values for the current application, which has better performance than the class. + + To write to the configuration files, use one of the methods. The user or process that writes must have the following permissions: + +- Write permission on the configuration file and directory at the current configuration hierarchy level. + +- Read permissions on all the configuration files. + + + + + + + + Property + + System.Configuration + 4.0.0.0 + + + System.Collections.Specialized.NameValueCollection + + + Gets the data for the current application's default configuration. + Returns a object that contains the contents of the object for the current application's default configuration. + + object contains the contents of the configuration file's `appSettings` section. + + + +## Examples + The first example shows a simple console application that reads application settings, adds a new setting, and updates an existing setting. + +```csharp +using System; +using System.Configuration; + +namespace ConsoleApplication1 +{ + class Program + { + static void Main(string[] args) + { + ReadAllSettings(); + ReadSetting("Setting1"); + ReadSetting("NotValid"); + AddUpdateAppSettings("NewSetting", "May 7, 2014"); + AddUpdateAppSettings("Setting1", "May 8, 2014"); + ReadAllSettings(); + } + + static void ReadAllSettings() + { + try + { + var appSettings = ConfigurationManager.AppSettings; + + if (appSettings.Count == 0) + { + Console.WriteLine("AppSettings is empty."); + } + else + { + foreach (var key in appSettings.AllKeys) + { + Console.WriteLine("Key: {0} Value: {1}", key, appSettings[key]); + } + } + } + catch (ConfigurationErrorsException) + { + Console.WriteLine("Error reading app settings"); + } + } + + static void ReadSetting(string key) + { + try + { + var appSettings = ConfigurationManager.AppSettings; + string result = appSettings[key] ?? "Not Found"; + Console.WriteLine(result); + } + catch (ConfigurationErrorsException) + { + Console.WriteLine("Error reading app settings"); + } + } + + static void AddUpdateAppSettings(string key, string value) + { + try + { + var configFile = ConfigurationManager.OpenExeConfiguration(ConfigurationUserLevel.None); + var settings = configFile.AppSettings.Settings; + if (settings[key] == null) + { + settings.Add(key, value); + } + else + { + settings[key].Value = value; + } + configFile.Save(ConfigurationSaveMode.Modified); + ConfigurationManager.RefreshSection(configFile.AppSettings.SectionInformation.Name); + } + catch (ConfigurationErrorsException) + { + Console.WriteLine("Error writing app settings"); + } + } + } +} +``` + +```vb +Imports System.Configuration +Module Module1 + + Sub Main() + ReadAllSettings() + ReadSetting("Setting1") + ReadSetting("NotValid") + AddUpdateAppSettings("NewSetting", "May 7, 2014") + AddUpdateAppSettings("Setting1", "May 8, 2014") + ReadAllSettings() + End Sub + + Sub ReadAllSettings() + Try + Dim appSettings = ConfigurationManager.AppSettings + + If appSettings.Count = 0 Then + Console.WriteLine("AppSettings is empty.") + Else + For Each key As String In appSettings.AllKeys + Console.WriteLine("Key: {0} Value: {1}", key, appSettings(key)) + Next + End If + Catch e As ConfigurationErrorsException + Console.WriteLine("Error reading app settings") + End Try + End Sub + + Sub ReadSetting(key As String) + Try + Dim appSettings = ConfigurationManager.AppSettings + Dim result As String = appSettings(key) + If IsNothing(result) Then + result = "Not found" + End If + Console.WriteLine(result) + Catch e As ConfigurationErrorsException + Console.WriteLine("Error reading app settings") + End Try + End Sub + + Sub AddUpdateAppSettings(key As String, value As String) + Try + Dim configFile = ConfigurationManager.OpenExeConfiguration(ConfigurationUserLevel.None) + Dim settings = configFile.AppSettings.Settings + If IsNothing(settings(key)) Then + settings.Add(key, value) + Else + settings(key).Value = value + End If + configFile.Save(ConfigurationSaveMode.Modified) + ConfigurationManager.RefreshSection(configFile.AppSettings.SectionInformation.Name) + Catch e As ConfigurationErrorsException + Console.WriteLine("Error writing app settings") + End Try + End Sub + +End Module +``` + + The previous example assumes your project has an App.config file as shown below. + +```xml + + + + + + + + + + +``` + + ]]> + + Could not retrieve a object with the application settings data. + + + + + + + Property + + System.Configuration + 4.0.0.0 + + + System.Configuration.ConnectionStringSettingsCollection + + + Gets the data for the current application's default configuration. + Returns a object that contains the contents of the object for the current application's default configuration. + + object contains the contents of the configuration file's `connectionStrings` section. + + + +## Examples + The following example shows how to use a connection string to read data from a database. + +```csharp +using System; +using System.Configuration; +using System.Data.SqlClient; + +namespace ConsoleApplication1 +{ + class Program + { + static void Main(string[] args) + { + ReadProducts(); + } + + static void ReadProducts() + { + var connectionString = ConfigurationManager.ConnectionStrings["WingtipToys"].ConnectionString; + string queryString = "SELECT Id, ProductName FROM dbo.Products;"; + using (var connection = new SqlConnection(connectionString)) + { + var command = new SqlCommand(queryString, connection); + connection.Open(); + using (var reader = command.ExecuteReader()) + { + while (reader.Read()) + { + Console.WriteLine(String.Format("{0}, {1}", reader[0], reader[1])); + } + } + } + } + } +} +``` + +```vb +Imports System.Configuration +Imports System.Data.SqlClient +Module Module1 + + Sub Main() + ReadProducts() + End Sub + + Sub ReadProducts() + Dim connectionString = ConfigurationManager.ConnectionStrings("WingtipToys").ConnectionString + Dim queryString = "SELECT Id, ProductName FROM dbo.Products;" + Using connection As New SqlConnection(connectionString) + Dim command = New SqlCommand(queryString, connection) + connection.Open() + + Using reader As SqlDataReader = command.ExecuteReader() + While reader.Read() + Console.WriteLine(String.Format("{0}, {1}", reader(0), reader(1))) + End While + End Using + End Using + End Sub + +End Module +``` + + The previous example assumes your project has an App.config as shown below. + +```xml + + + + + + + + + +``` + + ]]> + + Could not retrieve a object. + + + + + + + Method + + System.Configuration + 4.0.0.0 + + + System.Object + + + + + + The configuration section path and name. + Retrieves a specified configuration section for the current application's default configuration. + The specified object, or if the section does not exist. + + method accesses run-time configuration information that it cannot change. To change the configuration, you use the method on the configuration file that you obtain by using one of the following Open methods: + +- + +- + +- + +- + + + +## Examples + The following example shows how to use the method. The example is part of a larger example that is provided for the class. + + [!code-csharp[System.Configuration.ConfigurationManager#7](~/samples/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/CS/configurationmanager.cs#7)] + [!code-vb[System.Configuration.ConfigurationManager#7](~/samples/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/VB/configurationmanager.vb#7)] + + ]]> + + A configuration file could not be loaded. + + You must cast the return value to the expected configuration type. To avoid possible casting exceptions, you should use a conditional casting operation such as the operator in C# or the function in Visual Basic. + + + + + + + + Method + + System.Configuration + 4.0.0.0 + + + System.Configuration.Configuration + + + + + + The for which you are opening the configuration. + Opens the configuration file for the current application as a object. + A object. + + object that applies to all users, set `userLevel` to . + +- To get the local object that applies to the current user, set `userLevel` to . + +- To get the roaming object that applies to the current user, set `userLevel` to . + + > [!NOTE] + > To get the object for a resource, your code must have read permissions on all the configuration files from which it inherits settings. To update a configuration file, your code must additionally have write permissions for both the configuration file and the directory in which it exists. + + + +## Examples + The following code example shows how to use the method. + + [!code-csharp[System.Configuration.ConfigurationManager#5](~/samples/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/CS/configurationmanager.cs#5)] + [!code-vb[System.Configuration.ConfigurationManager#5](~/samples/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/VB/configurationmanager.vb#5)] + + ]]> + + A configuration file could not be loaded. + + + + + + + Method + + System.Configuration + 4.0.0.0 + + + System.Configuration.Configuration + + + + + + The path of the executable (exe) file. + Opens the specified client configuration file as a object. + A object. + + overload with the `preLoad` parameter set to `false`. + + + +## Examples + The following code example shows how to use the method. + + [!code-csharp[System.Configuration.ConfigurationManager#6](~/samples/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/CS/configurationmanager.cs#6)] + [!code-vb[System.Configuration.ConfigurationManager#6](~/samples/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/VB/configurationmanager.vb#6)] + + ]]> + + A configuration file could not be loaded. + + + + + + + Method + + System.Configuration + 4.0.0.0 + + + System.Configuration.Configuration + + + + Opens the machine configuration file on the current computer as a object. + A object. + + [!NOTE] +> To obtain the object for a resource, your code must have read permissions on all the configuration files from which it inherits settings. To update a configuration file, your code must additionally have write permissions for both the configuration file and the directory in which it exists. It is not possible to access the Machine.config file for other versions of the .NET Framework that might be installed on the computer. + + + +## Examples + The following code example shows how to use the method to obtain all sections that are contained in the configuration file. + + [!code-csharp[System.Configuration.ConfigurationManager#4](~/samples/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/CS/configurationmanager.cs#4)] + [!code-vb[System.Configuration.ConfigurationManager#4](~/samples/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/VB/configurationmanager.vb#4)] + + ]]> + + A configuration file could not be loaded. + + + + + + + Method + + System.Configuration + 4.0.0.0 + + + System.Configuration.Configuration + + + + + + + An object that references configuration file to use instead of the application default configuration file. + The object for which you are opening the configuration. + Opens the specified client configuration file as a object that uses the specified file mapping and user level. + The configuration object. + + object determines the location of the configuration file being opened. It indicates whether the file has no user level (the configuration file is in the same directory as the application) or has a per-user level (the configuration file is in an application settings path determined by `userLevel`). + +> [!NOTE] +> To obtain the object for a resource, your code must have read permissions on all the configuration files from which it inherits settings. To update a configuration file, your code must additionally have write permissions for both the configuration file and the directory in which it exists. + + + +## Examples + The following code example shows how to use the method to obtain all sections that are contained by the configuration file. + + [!code-csharp[System.Configuration.ConfigurationManager#9](~/samples/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/CS/configurationmanager.cs#9)] + [!code-vb[System.Configuration.ConfigurationManager#9](~/samples/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/VB/configurationmanager.vb#9)] + + ]]> + + A configuration file could not be loaded. + + + + + + + Method + + System.Configuration + 4.0.0.0 + + + System.Configuration.Configuration + + + + + + + + An object that references the configuration file to use instead of the default application configuration file. + The object for which you are opening the configuration. + + to preload all section groups and sections; otherwise, . + Opens the specified client configuration file as a object that uses the specified file mapping, user level, and preload option. + The configuration object. + + object determines the location of the configuration file that is being opened. It indicates whether the file has no user level (the configuration file is in the same directory as the application) or has a per-user level (the configuration file is in an application settings path that is determined by `userLevel`). + +> [!NOTE] +> To obtain the object for a resource, your code must have read permissions on all the configuration files from which it inherits settings. To update a configuration file, your code must additionally have write permissions for both the configuration file and the directory in which it exists. + + For a code example, see the overload. + + ]]> + + A configuration file could not be loaded. + + + + + + + Method + + System.Configuration + 4.0.0.0 + + + System.Configuration.Configuration + + + + + + An object that references configuration file to use instead of the application default configuration file. + Opens the machine configuration file as a object that uses the specified file mapping. + A object. + + [!NOTE] +> To obtain the object for a resource, your code must have read permissions on all the configuration files from which it inherits settings. To update a configuration file, your code must additionally have write permissions for both the configuration file and the directory in which it exists. It is not possible to access the Machine.config file for other versions of the .NET Framework that might be installed on the computer. + + + +## Examples + The following code example shows how to use the method to obtain all sections in the configuration file. + + [!code-csharp[System.Configuration.ConfigurationManager#4](~/samples/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/CS/configurationmanager.cs#4)] + [!code-vb[System.Configuration.ConfigurationManager#4](~/samples/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/VB/configurationmanager.vb#4)] + + ]]> + + A configuration file could not be loaded. + + + + + + + Method + + System.Configuration + 4.0.0.0 + + + System.Void + + + + + + The configuration section name or the configuration path and section name of the section to refresh. + Refreshes the named section so the next time that it is retrieved it will be re-read from disk. + + method to refresh the application settings configuration section. + + [!code-csharp[System.Configuration.ConfigurationManager#7](~/samples/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/CS/configurationmanager.cs#7)] + [!code-vb[System.Configuration.ConfigurationManager#7](~/samples/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationManager/VB/configurationmanager.vb#7)] + + ]]> + + + + + \ No newline at end of file