Links: .NET Desktop - framework\winforms (#108)

dotnet-desktop-guide/framework/winforms/advanced/application-settings-architecture.md

@@ -9,6 +9,7 @@ helpviewer_keywords:
 ms.assetid: c8eb2ad0-fac6-4ea2-9140-675a4a44d562
 ---
 # Application Settings Architecture
+
 This topic describes how the Application Settings architecture works, and explores advanced features of the architecture, such as grouped settings and settings keys.
 
  The application settings architecture supports defining strongly typed settings with either application or user scope, and persisting the settings between application sessions. The architecture provides a default persistence engine for saving settings to and loading them from the local file system. The architecture also defines interfaces for supplying a custom persistence engine.
@@ -16,6 +17,7 @@ This topic describes how the Application Settings architecture works, and explor
  Interfaces are provided that enable custom components to persist their own settings when they are hosted in an application. By using settings keys, components can keep settings for multiple instances of the component separate.
 
 ## Defining Settings
+
  The application settings architecture is used within both ASP.NET and Windows Forms, and it contains a number of base classes that are shared across both environments. The most important is <xref:System.Configuration.SettingsBase>, which provides access to settings through a collection, and provides low-level methods for loading and saving settings. Each environment implements its own class derived from <xref:System.Configuration.SettingsBase> to provide additional settings functionality for that environment. In a Windows Forms-based application, all application settings must be defined on a class derived from the <xref:System.Configuration.ApplicationSettingsBase> class, which adds the following functionality to the base class:
 
 - Higher-level loading and saving operations
@@ -36,6 +38,7 @@ This topic describes how the Application Settings architecture works, and explor
  [!code-vb[ApplicationSettings.Create#1](~/samples/snippets/visualbasic/VS_Snippets_Winforms/ApplicationSettings.Create/VB/MyAppSettings.vb#1)]
 
 ## Settings Persistence
+
  The <xref:System.Configuration.ApplicationSettingsBase> class does not itself persist or load settings; this job falls to the settings provider, a class that derives from <xref:System.Configuration.SettingsProvider>. If a derived class of <xref:System.Configuration.ApplicationSettingsBase> does not specify a settings provider through the <xref:System.Configuration.SettingsProviderAttribute>, then the default provider, <xref:System.Configuration.LocalFileSettingsProvider>, is used.
 
  The configuration system that was originally released with the .NET Framework supports providing static application configuration data through either the local computer's machine.config file or within an `app.`exe.config file that you deploy with your application. The <xref:System.Configuration.LocalFileSettingsProvider> class expands this native support in the following ways:
@@ -82,9 +85,10 @@ This topic describes how the Application Settings architecture works, and explor
 </configuration>
 ```
 
- For a definition of the elements within the application settings section of a configuration file, see [Application Settings Schema](https://docs.microsoft.com/dotnet/framework/configure-apps/file-schema/application-settings-schema).
+ For a definition of the elements within the application settings section of a configuration file, see [Application Settings Schema](/dotnet/framework/configure-apps/file-schema/application-settings-schema).
 
 ### Settings Bindings
+
  Application settings uses the Windows Forms data binding architecture to provide two-way communication of settings updates between the settings object and components. If you use Visual Studio to create application settings and assign them to component properties, these bindings are generated automatically.
 
  You can only bind an application setting to a component that supports the <xref:System.Windows.Forms.IBindableComponent> interface. Also, the component must implement a change event for a specific bound property, or notify application settings that the property has changed through the <xref:System.ComponentModel.INotifyPropertyChanged> interface. If the component does not implement <xref:System.Windows.Forms.IBindableComponent> and you are binding through Visual Studio, the bound properties will be set the first time, but will not update. If the component implements <xref:System.Windows.Forms.IBindableComponent> but does not support property change notifications, the binding will not update in the settings file when the property is changed.
@@ -92,6 +96,7 @@ This topic describes how the Application Settings architecture works, and explor
  Some Windows Forms components, such as <xref:System.Windows.Forms.ToolStripItem>, do not support settings bindings.
 
 ### Settings Serialization
+
  When <xref:System.Configuration.LocalFileSettingsProvider> must save settings to disk, it performs the following actions:
 
 1. Uses reflection to examine all of the properties defined on your <xref:System.Configuration.ApplicationSettingsBase> derived class, finding those that are applied with either <xref:System.Configuration.ApplicationScopedSettingAttribute> or <xref:System.Configuration.UserScopedSettingAttribute>.
@@ -103,6 +108,7 @@ This topic describes how the Application Settings architecture works, and explor
  If you implement your own settings class, you can use the <xref:System.Configuration.SettingsSerializeAsAttribute> to mark a setting for either binary or custom serialization using the <xref:System.Configuration.SettingsSerializeAs> enumeration. For more information on creating your own settings class in code, see [How to: Create Application Settings](how-to-create-application-settings.md).
 
 ### Settings File Locations
+
  The location of the `app`.exe.config and *user*.config files will differ based on how the application is installed. For a Windows Forms-based application copied onto the local computer, `app`.exe.config will reside in the same directory as the base directory of the application's main executable file, and *user*.config will reside in the location specified by the <xref:System.Windows.Forms.Application.LocalUserAppDataPath%2A?displayProperty=nameWithType> property. For an application installed by means of ClickOnce, both of these files will reside in the ClickOnce Data Directory underneath %InstallRoot%\Documents and Settings\\*username*\Local Settings.
 
  The storage location of these files is slightly different if a user has enabled roaming profiles, which enables a user to define different Windows and application settings when they are using other computers within a domain. In that case, both ClickOnce applications and non-ClickOnce applications will have their `app`.exe.config and *user*.config files stored under %InstallRoot%\Documents and Settings\\*username*\Application Data.
@@ -110,11 +116,13 @@ This topic describes how the Application Settings architecture works, and explor
  For more information about how the Application Settings feature works with the new deployment technology, see [ClickOnce and Application Settings](/visualstudio/deployment/clickonce-and-application-settings). For more information about the ClickOnce Data Directory, see [Accessing Local and Remote Data in ClickOnce Applications](/visualstudio/deployment/accessing-local-and-remote-data-in-clickonce-applications).
 
 ## Application Settings and Security
+
  Application settings are designed to work in partial trust, a restricted environment that is the default for Windows Forms applications hosted over the Internet or an intranet. No special permissions beyond partial trust are needed to use application settings with the default settings provider.
 
  When application settings are used in a ClickOnce application, the `user`.config file is stored in the ClickOnce data directory. The size of the application's `user`.config file cannot exceed the data directory quota set by ClickOnce. For more information, see [ClickOnce and Application Settings](/visualstudio/deployment/clickonce-and-application-settings).
 
 ## Custom Settings Providers
+
  In the Application Settings architecture, there is a loose coupling between the applications settings wrapper class, derived from <xref:System.Configuration.ApplicationSettingsBase>, and the associated settings provider or providers, derived from <xref:System.Configuration.SettingsProvider>. This association is defined only by the <xref:System.Configuration.SettingsProviderAttribute> applied to the wrapper class or its individual properties. If a settings provider is not explicitly specified, the default provider, <xref:System.Configuration.LocalFileSettingsProvider>, is used. As a result, this architecture supports creating and using custom settings providers.
 
  For example, suppose that you want to develop and use `SqlSettingsProvider`, a provider that will store all settings data in a Microsoft SQL Server database. Your <xref:System.Configuration.SettingsProvider>-derived class would receive this information in its `Initialize` method as a parameter of type <xref:System.Collections.Specialized.NameValueCollection?displayProperty=nameWithType>. You would then implement the <xref:System.Configuration.SettingsProvider.GetPropertyValues%2A> method to retrieve your settings from the data store, and <xref:System.Configuration.SettingsProvider.SetPropertyValues%2A> to save them. Your provider can use the <xref:System.Configuration.SettingsPropertyCollection> supplied to <xref:System.Configuration.SettingsProvider.GetPropertyValues%2A> to determine the property's name, type, and scope, as well as any other settings attributes defined for that property.
@@ -148,4 +156,4 @@ This topic describes how the Application Settings architecture works, and explor
 - [Application Settings Overview](application-settings-overview.md)
 - [Application Settings for Custom Controls](application-settings-for-custom-controls.md)
 - [ClickOnce and Application Settings](/visualstudio/deployment/clickonce-and-application-settings)
-- [Application Settings Schema](https://docs.microsoft.com/dotnet/framework/configure-apps/file-schema/application-settings-schema)
+- [Application Settings Schema](/dotnet/framework/configure-apps/file-schema/application-settings-schema)