Partilhar via

ApplicationSettingsBase Classe

  • Referência

Definição

Namespace:
System.Configuration
Assembly:
System.Configuration.ConfigurationManager.dll
Assembly:
System.dll
Pacote:
System.Configuration.ConfigurationManager v6.0.0
Pacote:
System.Configuration.ConfigurationManager v7.0.0
Pacote:
System.Configuration.ConfigurationManager v8.0.0
Pacote:
System.Configuration.ConfigurationManager v9.0.0-preview.2.24128.5
Origem:
ApplicationSettingsBase.cs
Origem:
ApplicationSettingsBase.cs
Origem:
ApplicationSettingsBase.cs

Atua como uma classe base para derivar classes de wrapper concretas para implementar o recurso de configurações do aplicativo em aplicativos Windows Forms.

public ref class ApplicationSettingsBase abstract : System::Configuration::SettingsBase, System::ComponentModel::INotifyPropertyChanged
public abstract class ApplicationSettingsBase : System.Configuration.SettingsBase, System.ComponentModel.INotifyPropertyChanged
type ApplicationSettingsBase = class
    inherit SettingsBase
    interface INotifyPropertyChanged
Public MustInherit Class ApplicationSettingsBase
Inherits SettingsBase
Implements INotifyPropertyChanged
Herança
Object
SettingsBase
ApplicationSettingsBase
Implementações
INotifyPropertyChanged

Exemplos

O exemplo de código a seguir demonstra o uso das configurações do aplicativo para persistir os seguintes atributos do formulário main: local, tamanho, cor da tela de fundo e texto da barra de título. Todos esses atributos são mantidos como propriedades de configurações de aplicativo único na FormSettings classe , chamada FormLocation, FormSizeFormBackColor e FormText, respectivamente. Todos, exceto e FormTextSize , são dados associados às propriedades do formulário associadas e têm um valor de configuração padrão aplicado usando DefaultSettingValueAttribute.

O formulário contém quatro controles filho que têm os seguintes nomes e funções:

  • Um botão chamado btnBackColor usado para exibir a caixa de diálogo Cor comum.

  • Um botão chamado btnReload usado para Reload as configurações do aplicativo.

  • Um botão chamado btnReset usado para Reset as configurações do aplicativo.

  • Uma caixa de texto chamada tbStatus usada para exibir status informações sobre o programa.

Observe que, após cada execução do aplicativo, um caractere de período adicional é acrescentado ao texto do título do formulário.

Este exemplo de código requer um Formulário com uma ColorDialog classe chamada colorDialog1e um StatusStrip controle com um ToolStripStatusLabel chamado tbStatus. Além disso, ele requer três Button objetos chamados btnReload, btnResete btnBackColor.


#using <System.dll>
#using <System.Drawing.dll>
#using <System.Windows.Forms.dll>

using namespace System;
using namespace System::ComponentModel;
using namespace System::Drawing;
using namespace System::Configuration;
using namespace System::Windows::Forms;

namespace AppSettingsSample
{
    //Application settings wrapper class
    ref class FormSettings sealed: public ApplicationSettingsBase
    {
    public:
        [UserScopedSettingAttribute()]
        property String^ FormText
        {
            String^ get()
            {
                return (String^)this["FormText"];
            }
            void set( String^ value )
            {
                this["FormText"] = value;
            }
        }

    public:
        [UserScopedSettingAttribute()]
        [DefaultSettingValueAttribute("0, 0")]
        property Point FormLocation
        {
            Point get()
            {
                return (Point)(this["FormLocation"]);
            }
            void set( Point value )
            {
                this["FormLocation"] = value;
            }
        }

    public:
        [UserScopedSettingAttribute()]
        [DefaultSettingValueAttribute("225, 200")]
        property Size FormSize
        {
            Size get()
            {
                return (Size)this["FormSize"];
            }
            void set( Size value )
            {
                this["FormSize"] = value;
            }
        }

    public:
        [UserScopedSettingAttribute()]
        [DefaultSettingValueAttribute("LightGray")]
        property Color FormBackColor
        {
            Color get()
            {
                return (Color)this["FormBackColor"];
            }
            void set(Color value)
            {
                this["FormBackColor"] = value;
            }
        }

    };

    ref class AppSettingsForm : Form
    {
        /// <summary>
        /// Required designer variable.
        /// </summary>
    private:
        System::ComponentModel::IContainer^ components;

        /// <summary>
        /// Clean up any resources being used. The Dispose(true) 
        /// pattern for embedded objects is implemented with this
        /// code that just contains a destructor 
        /// </summary>
    public:
        ~AppSettingsForm()
        {
            if (components != nullptr)
            {
                delete components;
            }
        }

#pragma region Windows Form Designer generated code

        /// <summary>
        /// Required method for Designer support - do not modify
        /// the contents of this method with the code editor.
        /// </summary>
    private:
        void InitializeComponent()
        {
            this->components = nullptr;
            this->colorDialog = gcnew System::Windows::Forms::ColorDialog();
            this->backColorButton = gcnew System::Windows::Forms::Button();
            this->resetButton = gcnew System::Windows::Forms::Button();
            this->statusDisplay = gcnew System::Windows::Forms::TextBox();
            this->reloadButton = gcnew System::Windows::Forms::Button();
            this->SuspendLayout();
            //
            // backColorButton
            //
            this->backColorButton->Location = System::Drawing::Point(26, 24);
            this->backColorButton->Name = "backColorButton";
            this->backColorButton->Size = System::Drawing::Size(159, 23);
            this->backColorButton->TabIndex = 0;
            this->backColorButton->Text = "Change Background Color";
            this->backColorButton->Click += gcnew System::EventHandler
                (this,&AppSettingsForm::BackColorButton_Click);
            //
            // resetButton
            //
            this->resetButton->Location = System::Drawing::Point(26, 90);
            this->resetButton->Name = "resetButton";
            this->resetButton->Size = System::Drawing::Size(159, 23);
            this->resetButton->TabIndex = 1;
            this->resetButton->Text = "Reset to Defaults";
            this->resetButton->Click += gcnew System::EventHandler
                (this,&AppSettingsForm::ResetButton_Click);
            //
            // statusDisplay
            //
            this->statusDisplay->Location = System::Drawing::Point(26, 123);
            this->statusDisplay->Name = "statusDisplay";
            this->statusDisplay->Size = System::Drawing::Size(159, 20);
            this->statusDisplay->TabIndex = 2;
            //
            // reloadButton
            //
            this->reloadButton->Location = System::Drawing::Point(26, 57);
            this->reloadButton->Name = "reloadButton";
            this->reloadButton->Size = System::Drawing::Size(159, 23);
            this->reloadButton->TabIndex = 3;
            this->reloadButton->Text = "Reload from Storage";
            this->reloadButton->Click += gcnew System::EventHandler
                (this,&AppSettingsForm::ReloadButton_Click);
            //
            // AppSettingsForm
            //
            this->ClientSize = System::Drawing::Size(217, 166);
            this->Controls->Add(this->reloadButton);
            this->Controls->Add(this->statusDisplay);
            this->Controls->Add(this->resetButton);
            this->Controls->Add(this->backColorButton);
            this->Name = "AppSettingsForm";
            this->Text = "App Settings";
            this->FormClosing += gcnew
                System::Windows::Forms::FormClosingEventHandler
                (this,&AppSettingsForm::AppSettingsForm_FormClosing);
            this->Load += gcnew System::EventHandler(this,
                &AppSettingsForm::AppSettingsForm_Load);
            this->ResumeLayout(false);
            this->PerformLayout();

        }

#pragma endregion

    private:
        System::Windows::Forms::ColorDialog^ colorDialog;

        System::Windows::Forms::Button^ backColorButton;

        System::Windows::Forms::Button^ resetButton;

        System::Windows::Forms::TextBox^ statusDisplay;

        System::Windows::Forms::Button^ reloadButton;



        FormSettings ^ formSettings;

    public:
        AppSettingsForm()
        {
            formSettings = gcnew FormSettings;
            InitializeComponent();
        }

    private:
        void AppSettingsForm_Load(Object^ sender, EventArgs^ e)
        {
            //Associate settings property event handlers.
            formSettings->SettingChanging += gcnew SettingChangingEventHandler(
                this, &AppSettingsForm::FormSettings_SettingChanging);
            formSettings->SettingsSaving += gcnew SettingsSavingEventHandler(
                this,&AppSettingsForm::FormSettings_SettingsSaving);

            //Data bind settings properties with straightforward associations.
            Binding^ backColorBinding = gcnew Binding("BackColor", 
                formSettings, "FormBackColor", true, 
                DataSourceUpdateMode::OnPropertyChanged);
            this->DataBindings->Add(backColorBinding);
            Binding^ sizeBinding = gcnew Binding("Size", formSettings,
                "FormSize", true, DataSourceUpdateMode::OnPropertyChanged);
            this->DataBindings->Add(sizeBinding);
            Binding^ locationBinding = gcnew Binding("Location", formSettings,
                "FormLocation", true, DataSourceUpdateMode::OnPropertyChanged);
            this->DataBindings->Add(locationBinding);

            //For more complex associations, manually assign associations.
            String^ savedText = formSettings->FormText;
            //Since there is no default value for FormText.
            if (savedText != nullptr)
            {
                this->Text = savedText;
            }
        }

    private:
        void AppSettingsForm_FormClosing(Object^ sender,
            FormClosingEventArgs^ e)
        {
            //Synchronize manual associations first.
            formSettings->FormText = this->Text + '.';
            formSettings->Save();
        }

    private:
        void BackColorButton_Click(Object^ sender, EventArgs^ e)
        {
            if (::DialogResult::OK == colorDialog->ShowDialog())
            {
                Color color = colorDialog->Color;
                this->BackColor = color;
            }
        }

    private:
        void ResetButton_Click(Object^ sender, EventArgs^ e)
        {
            formSettings->Reset();
            this->BackColor = SystemColors::Control;
        }

    private:
        void ReloadButton_Click(Object^ sender, EventArgs^ e)
        {
            formSettings->Reload();
        }

    private:
        void FormSettings_SettingChanging(Object^ sender,
            SettingChangingEventArgs^ e)
        {
            statusDisplay->Text = e->SettingName + ": " + e->NewValue;
        }

    private:
        void FormSettings_SettingsSaving(Object^ sender,
            CancelEventArgs^ e)
        {
            //Should check for settings changes first.
            ::DialogResult^ dialogResult = MessageBox::Show(
                "Save current values for application settings?",
                "Save Settings", MessageBoxButtons::YesNo);
            if (::DialogResult::No == dialogResult)
            {
                e->Cancel = true;
            }
        }
    };

partial class Form1 : Form
{
    private FormSettings frmSettings1 = new FormSettings();

    public Form1()
    {
        InitializeComponent();
    }

    private void Form1_Load(object sender, EventArgs e)
    {
        this.FormClosing += new FormClosingEventHandler(Form1_FormClosing);

        //Associate settings property event handlers.
        frmSettings1.SettingChanging += new SettingChangingEventHandler(
                                            frmSettings1_SettingChanging);
        frmSettings1.SettingsSaving += new SettingsSavingEventHandler(
                                            frmSettings1_SettingsSaving);

        //Data bind settings properties with straightforward associations.
        Binding bndBackColor = new Binding("BackColor", frmSettings1,
            "FormBackColor", true, DataSourceUpdateMode.OnPropertyChanged);
        this.DataBindings.Add(bndBackColor);
        Binding bndLocation = new Binding("Location", frmSettings1,
            "FormLocation", true, DataSourceUpdateMode.OnPropertyChanged);
        this.DataBindings.Add(bndLocation);

        // Assign Size property, since databinding to Size doesn't work well.
         this.Size = frmSettings1.FormSize;

        //For more complex associations, manually assign associations.
        String savedText = frmSettings1.FormText;
        //Since there is no default value for FormText.
        if (savedText != null)
            this.Text = savedText;
    }

    private void Form1_FormClosing(object sender, FormClosingEventArgs e)
    {
        //Synchronize manual associations first.
        frmSettings1.FormText = this.Text + '.';
        frmSettings1.FormSize = this.Size;
        frmSettings1.Save();
    }

    private void btnBackColor_Click(object sender, EventArgs e)
    {
        if (DialogResult.OK == colorDialog1.ShowDialog())
        {
            Color c = colorDialog1.Color;
            this.BackColor = c;
        }
    }

    private void btnReset_Click(object sender, EventArgs e)
    {
        frmSettings1.Reset();
        this.BackColor = SystemColors.Control;
    }

    private void btnReload_Click(object sender, EventArgs e)
    {
        frmSettings1.Reload();
    }

    void frmSettings1_SettingChanging(object sender, SettingChangingEventArgs e)
    {
        tbStatus.Text = e.SettingName + ": " + e.NewValue;
    }

    void frmSettings1_SettingsSaving(object sender, CancelEventArgs e)
    {
        //Should check for settings changes first.
        DialogResult dr = MessageBox.Show(
                        "Save current values for application settings?",
                        "Save Settings", MessageBoxButtons.YesNo);
        if (DialogResult.No == dr)
        {
            e.Cancel = true;
        }
    }
}

//Application settings wrapper class
sealed class FormSettings : ApplicationSettingsBase
{
    [UserScopedSettingAttribute()]
    public String FormText
    {
        get { return (String)this["FormText"]; }
        set { this["FormText"] = value; }
    }

    [UserScopedSettingAttribute()]
    [DefaultSettingValueAttribute("0, 0")]
    public Point FormLocation
    {
        get { return (Point)(this["FormLocation"]); }
        set { this["FormLocation"] = value; }
    }

    [UserScopedSettingAttribute()]
    [DefaultSettingValueAttribute("225, 200")]
    public Size FormSize
    {
        get { return (Size)this["FormSize"]; }
        set { this["FormSize"] = value; }
    }

    [UserScopedSettingAttribute()]
    [DefaultSettingValueAttribute("LightGray")]
    public Color FormBackColor
    {
        get { return (Color)this["FormBackColor"]; }
        set { this["FormBackColor"] = value; }
    }
}

Imports System.Configuration
Imports System.ComponentModel

Public Class Form1

    Private WithEvents frmSettings1 As New FormSettings

    Private Sub Form1_Load(ByVal sender As Object, ByVal e As EventArgs) _
            Handles MyBase.Load
        'Settings property event handlers are associated through WithEvents 
        '  and Handles combination.

        'Data bind settings properties with straightforward associations.
        Dim bndBackColor As New Binding("BackColor", frmSettings1, "FormBackColor", _
                True, DataSourceUpdateMode.OnPropertyChanged)
        Me.DataBindings.Add(bndBackColor)
        Dim bndLocation As New Binding("Location", frmSettings1, "FormLocation", _
                True, DataSourceUpdateMode.OnPropertyChanged)
        Me.DataBindings.Add(bndLocation)

        ' Assign Size property, since databinding to Size doesn't work well.
        Me.Size = frmSettings1.FormSize

        'For more complex associations, manually assign associations.
        Dim savedText As String = frmSettings1.FormText
        'Since there is no default value for FormText.
        If (savedText IsNot Nothing) Then
            Me.Text = savedText
        End If
    End Sub

    Private Sub Form1_FormClosing_1(ByVal sender As Object, ByVal e As _
            FormClosingEventArgs) Handles MyBase.FormClosing
        'Synchronize manual associations first.
        frmSettings1.FormText = Me.Text + "."c

        ' Save size settings manually.
        frmSettings1.FormSize = Me.Size

        frmSettings1.Save()
    End Sub

    Private Sub btnBackColor_Click(ByVal sender As Object, ByVal e As EventArgs) _
            Handles btnBackColor.Click
        If System.Windows.Forms.DialogResult.OK = colorDialog1.ShowDialog() Then
            Dim c As Color = colorDialog1.Color
            Me.BackColor = c
        End If
    End Sub

    Private Sub btnReset_Click(ByVal sender As Object, ByVal e As EventArgs) _
            Handles btnReset.Click
        frmSettings1.Reset()
        Me.BackColor = SystemColors.Control
    End Sub

    Private Sub btnReload_Click(ByVal sender As Object, ByVal e As EventArgs) _
            Handles btnReload.Click
        frmSettings1.Reload()
    End Sub

    Private Sub frmSettings1_SettingChanging(ByVal sender As Object, ByVal e As _
            SettingChangingEventArgs) Handles frmSettings1.SettingChanging
        tbStatus.Text = e.SettingName & ": " & e.NewValue.ToString
    End Sub

    Private Sub frmSettings1_SettingsSaving(ByVal sender As Object, ByVal e As _
            CancelEventArgs) Handles frmSettings1.SettingsSaving
        'Should check for settings changes first.
        Dim dr As DialogResult = MessageBox.Show( _
            "Save current values for application settings?", "Save Settings", _
            MessageBoxButtons.YesNo)
        If (System.Windows.Forms.DialogResult.No = dr) Then
            e.Cancel = True
        End If
    End Sub
End Class

'Application settings wrapper class. This class defines the settings we intend to use in our application.
NotInheritable Class FormSettings
    Inherits ApplicationSettingsBase

    <UserScopedSettingAttribute()> _
    Public Property FormText() As String
        Get
            Return CStr(Me("FormText"))
        End Get
        Set(ByVal value As String)
            Me("FormText") = value
        End Set
    End Property

    <UserScopedSettingAttribute(), DefaultSettingValueAttribute("0, 0")> _
    Public Property FormLocation() As Point
        Get
            Return CType(Me("FormLocation"), Point)
        End Get
        Set(ByVal value As Point)
            Me("FormLocation") = value
        End Set
    End Property

    <UserScopedSettingAttribute(), DefaultSettingValueAttribute("225, 200")> _
    Public Property FormSize() As Size
        Get
            Return CType(Me("FormSize"), Size)
        End Get
        Set(ByVal value As Size)
            Me("FormSize") = value
        End Set
    End Property

    <UserScopedSettingAttribute(), DefaultSettingValueAttribute("LightGray")> _
    Public Property FormBackColor() As Color
        Get
            Return CType(Me("FormBackColor"), Color)
        End Get
        Set(ByVal value As Color)
            Me("FormBackColor") = value
        End Set
    End Property
End Class

Comentários

ApplicationSettingsBase adiciona a seguinte funcionalidade à SettingsBase classe , que é usada por aplicativos baseados na Web:

  • A capacidade de detectar atributos em uma classe wrapper derivada de configurações. ApplicationSettingsBase dá suporte ao modelo declarativo usado para propriedades da classe wrapper, conforme descrito posteriormente.

  • Métodos e Reload de nível Save superior.

  • Eventos de validação adicionais que você pode manipular para garantir a correção das configurações individuais.

Na arquitetura de configurações do aplicativo, para acessar um grupo de propriedades de configurações, você precisa derivar uma classe wrapper concreta de ApplicationSettingsBase. A classe wrapper é personalizada das seguintes ApplicationSettingsBase maneiras:

  • Para que cada propriedade de configurações seja acessada, uma propriedade pública fortemente tipada correspondente é adicionada à classe wrapper. Essa propriedade tem get e set acessadores para configurações de aplicativo de leitura/gravação, mas apenas um get acessador para configurações somente leitura.

  • Os atributos apropriados devem ser aplicados às propriedades públicas da classe wrapper para indicar características da propriedade settings, como o escopo da configuração (aplicativo ou usuário), se a configuração deve dar suporte a roaming, o valor padrão para a configuração, o provedor de configurações a ser usado e assim por diante. Cada propriedade é necessária para especificar seu escopo, usando ou ApplicationScopedSettingAttributeUserScopedSettingAttribute. As configurações no escopo do aplicativo serão somente leitura se o padrão LocalFileSettingsProvider for usado.

A ApplicationSettingsBase classe usa reflexão para detectar esses atributos em tempo de execução. A maioria dessas informações é passada para a camada do provedor de configurações, que é responsável pelo armazenamento, formato de persistência e assim por diante.

Quando um aplicativo tem várias classes wrapper de configurações, cada classe define um grupo de configurações. Cada grupo tem as seguintes características:

  • Um grupo pode conter qualquer número ou tipo de configurações de propriedade.

  • Se o nome do grupo não for definido explicitamente pela decoração da classe wrapper com um SettingsGroupNameAttribute, um nome será gerado automaticamente.

Por padrão, todos os aplicativos baseados em cliente usam o LocalFileSettingsProvider para fornecer armazenamento. Se um provedor de configurações alternativo for desejado, a classe ou propriedade wrapper deverá ser decorada com um correspondente SettingsProviderAttribute.

Para obter mais informações sobre como usar as configurações do aplicativo, consulte Configurações do aplicativo para Windows Forms.

Construtores

ApplicationSettingsBase()

Inicializa uma instância da classe ApplicationSettingsBase com seu estado padrão.
ApplicationSettingsBase(IComponent)

Inicializa uma instância da classe ApplicationSettingsBase usando o componente proprietário fornecido.
ApplicationSettingsBase(IComponent, String)

Inicializa uma instância da classe ApplicationSettingsBase usando o componente proprietário e a chave de configurações fornecidos.
ApplicationSettingsBase(String)

Inicializa uma instância da classe ApplicationSettingsBase usando a chave de configurações fornecida.

Propriedades

Context

Obtém o contexto das configurações de aplicativo associado ao grupo de configurações.
IsSynchronized

Obtém um valor que indica se o acesso ao objeto é sincronizado (thread-safe).

(Herdado de SettingsBase)
Item[String]

Obtém ou define o valor da propriedade especificada das configurações do aplicativo.
Properties

Obtém a coleção de propriedades de configurações no wrapper.
PropertyValues

Obtém uma coleção de valores de propriedade.
Providers

Obtém a coleção de provedores de configurações de aplicativo usado pelo wrapper.
SettingsKey

Obtém ou define a chave de configurações para o grupo de configurações do aplicativo.

Métodos

Equals(Object)

Determina se o objeto especificado é igual ao objeto atual.

(Herdado de Object)
GetHashCode()

Serve como a função de hash padrão.

(Herdado de Object)
GetPreviousVersion(String)

Retorna o valor da propriedade de configuração nomeada para a versão anterior do mesmo aplicativo.
GetType()

Obtém o Type da instância atual.

(Herdado de Object)
Initialize(SettingsContext, SettingsPropertyCollection, SettingsProviderCollection)

Inicializa as propriedades internas usadas pelo objeto SettingsBase.

(Herdado de SettingsBase)
MemberwiseClone()

Cria uma cópia superficial do Object atual.

(Herdado de Object)
OnPropertyChanged(Object, PropertyChangedEventArgs)

Aciona o evento PropertyChanged.
OnSettingChanging(Object, SettingChangingEventArgs)

Aciona o evento SettingChanging.
OnSettingsLoaded(Object, SettingsLoadedEventArgs)

Aciona o evento SettingsLoaded.
OnSettingsSaving(Object, CancelEventArgs)

Aciona o evento SettingsSaving.
Reload()

Atualiza os valores de propriedade das configurações do aplicativo do armazenamento persistente.
Reset()

Restaura os valores de configurações de aplicativo persistentes para suas propriedades padrão correspondentes.
Save()

Armazena os valores atuais das propriedades de configurações do aplicativo.
ToString()

Retorna uma cadeia de caracteres que representa o objeto atual.

(Herdado de Object)
Upgrade()

Atualiza as configurações do aplicativo para refletir uma instalação mais recente do aplicativo.

Eventos

PropertyChanged

Ocorre antes do valor de uma propriedade de configurações do aplicativo ser alterado.
SettingChanging

Ocorre antes que o valor de uma propriedade de configurações do aplicativo é alterado.
SettingsLoaded

Ocorre após as configurações de aplicativo serem recuperadas do armazenamento.
SettingsSaving

Ocorre antes de os valores serem salvos no armazenamento de dados.

Aplica-se a

Confira também