Partilhar via


Gerenciar configurações de aplicativo (.NET)

As configurações de aplicativo permitem armazenar informações do aplicativo dinamicamente. Com as configurações de aplicativo, você pode usar um computador cliente para armazenar informações que não devem ser incluídas no código do aplicativo em runtime. As configurações de aplicativo podem incluir cadeias de conexão, preferências do usuário, entre outros.

Observação

As configurações de aplicativo substituem as propriedades dinâmicas usadas em versões anteriores do Visual Studio.

Cada configuração de aplicativo deve ter um nome exclusivo. O nome pode ser qualquer combinação de letras, números ou um sublinhado. O nome não pode começar com um número e não pode ter espaços. O nome é alterado por meio da propriedade Name.

As configurações de aplicativo são armazenadas como qualquer tipo de dados que pode ser serializado para XML ou que tem um TypeConverter que implementa ToString/FromString. Os tipos mais comuns são String, Integere Boolean. Você também pode armazenar valores como Color, Object ou como uma cadeia de conexão.

As configurações de aplicativo também contêm um valor. O valor é definido com a propriedade Valor e deve corresponder ao tipo de dados da configuração.

Além disso, as configurações de aplicativo podem ser associadas a uma propriedade de um formulário ou controle em tempo de design.

Há dois tipos de configurações de aplicativo, com base no escopo:

  • As configurações no escopo do aplicativo podem ser usadas para informações, como uma URL para um serviço Web ou uma cadeia de conexão de banco de dados. Esses valores são associados ao aplicativo. Portanto, os usuários não podem alterá-los no runtime.

  • As configurações no escopo do usuário podem ser usadas para informações, como persistir a última posição de um formulário ou uma preferência de fonte. Os usuários podem alterar esses valores no runtime.

Você pode alterar o tipo de uma configuração usando a propriedade Escopo.

O sistema do projeto armazena configurações de aplicativo em dois arquivos XML:

  • Um arquivo app.config, que é criado em tempo de design quando você cria a primeira configuração de aplicativo

  • Um arquivo user.config, criado em runtime quando o usuário que executa o aplicativo altera o valor de qualquer configuração de usuário

As alterações nas configurações de usuário não são gravadas em disco, a menos que o aplicativo especificamente chame um método para fazer isso.

Criar configurações de aplicativo no tempo de design

Em tempo de design, você pode criar configurações de aplicativo de duas maneiras:

  • Use a página Configurações do Designer de Projeto.

  • Use a janela Propriedades para um formulário ou um controle, o que permite associar uma configuração a uma propriedade.

Quando você cria uma configuração no escopo do aplicativo (por exemplo, uma cadeia de conexão de banco de dados ou uma referência aos recursos de servidor), o Visual Studio a salva no arquivo app.config com a tag <applicationSettings>. As cadeias de conexão são salvas na tag <connectionStrings>.

Quando você cria uma configuração no escopo do usuário (por exemplo, fonte padrão, home page ou tamanho da janela), o Visual Studio a salva no arquivo app.config com a marca <userSettings>.

Importante

Ao armazenar cadeias de conexão no app.config, você deve tomar precauções para evitar revelar informações confidenciais como senhas ou caminhos de servidor na cadeia de conexão.

Se você obtiver as informações de cadeia de conexão de uma fonte externa, como um usuário que fornece uma ID de usuário e uma senha, certifique-se de que os valores usados para construir a cadeia de conexão não contenham parâmetros de cadeia de conexão adicionais que alteram o comportamento da conexão.

Considere usar o recurso Configuração Protegida para criptografar informações confidenciais no arquivo de configuração. Para obter mais informações, confira Proteger informações de conexão.

Observação

Como não há nenhum modelo de arquivo de configuração para bibliotecas de classes, as configurações de aplicativo não se aplicam a projetos da biblioteca de classes. A exceção é um projeto de DLL do Visual Studio Tools para Office, que pode ter um arquivo de configuração.

Usar arquivos de configurações personalizadas

Você pode adicionar arquivos de configurações personalizadas ao seu projeto para um gerenciamento conveniente de grupos de configurações. As configurações contidas em um único arquivo são carregadas e salvas como uma unidade. Armazenar as configurações em arquivos separados para grupos usados com frequência e usados raramente pode economizar tempo ao carregar e salvar as configurações.

Por exemplo, você pode adicionar um arquivo SpecialSettings.settings ao seu projeto. Embora a classe SpecialSettings não seja exposta no namespace My, Exibir Código pode ler o arquivo de configurações personalizadas que contém Partial Class SpecialSettings.

Primeiro, o Designer de Configurações pesquisa o arquivo Settings.settings que o sistema do projeto cria. O arquivo Settings.settings é o arquivo padrão que o Designer de Projeto exibe na guia Configurações. O arquivo Settings.settings está localizado na pasta Meu Projeto, no caso de projetos do Visual Basic, e na pasta Propriedades, no caso de projetos do Visual C#. Em seguida, o Designer de Projeto pesquisa outros arquivos de configurações na pasta raiz do projeto. Portanto, você deve colocar o arquivo de configurações personalizado lá. Se você adicionar um arquivo .settings em outro lugar no projeto, o Designer de Projeto não conseguirá localizá-lo.

Acessar ou alterar as configurações de aplicativo no runtime em Visual Basic

Em projetos do Visual Basic, você pode acessar as configurações de aplicativo no runtime usando o objeto My.Settings. Na página Configurações, selecione o botão Exibir código para ver o arquivo Settings.vb. Settings.vb define a classe Settings, que permite manipular esses eventos na classe de configurações:

A classe Settings em Settings.vb é uma classe parcial que mostra apenas o código de propriedade do usuário e não toda a classe gerada. Para obter mais informações sobre como acessar as configurações de aplicativo usando o objeto My.Settings, confira Acessar configurações de aplicativo (.NET Framework).

Os valores das configurações no escopo do usuário que o usuário altera no runtime, por exemplo, a posição de um formulário, são armazenadas em um arquivo user.config. Os valores padrão ainda são salvos em app.config.

Se as configurações no escopo do usuário forem alteradas durante o runtime, por exemplo, no teste do aplicativo, e você desejar redefinir essas configurações para os valores padrão, selecione o botão Sincronizar.

Recomendamos usar o objeto My.Settings e o arquivo .settings padrão para acessar as configurações. Você pode usar o Designer de Configurações para atribuir propriedades às configurações. Além disso, as configurações de usuário são salvas automaticamente antes do desligamento do aplicativo. No entanto, seu aplicativo do Visual Basic pode acessar as configurações diretamente. Nesse caso você precisa acessar a classe MySettings e usar um arquivo .settings personalizado na raiz do projeto. É necessário salvar as configurações de usuário antes de encerrar o aplicativo, como faria em um aplicativo em C#, conforme descrito na próxima seção.

Acessar ou alterar as configurações de aplicativo no runtime em C#

Em linguagens diferentes do Visual Basic, como C#, você deve acessar a classe Settings diretamente, conforme mostrado no exemplo de Visual C# a seguir.

Properties.Settings.Default.FirstUserSetting = "abc";

Você deve chamar explicitamente o método Save dessa classe wrapper para persistir as configurações do usuário. Geralmente, isso é feito no manipulador de eventos Closing do formulário principal. O exemplo C# a seguir mostra uma chamada para o método Save.

Properties.Settings.Default.Save();

Para obter informações gerais sobre como acessar as configurações de aplicativo por meio da classe Settings, confira Visão geral sobre configurações de aplicativo (.NET Framework).

Como migrar aplicativos do .NET Framework para o .NET

O .NET Framework usa o arquivo app.config para carregar configurações do aplicativo, como configuração de cadeias de conexão e de provedores de log. O .NET moderno usa o arquivo appsettings.json para configurações de aplicativo. Para saber mais sobre como converter arquivos app.config em appsettings.json, consulte Modernizar após atualizar para o .NET do .NET Framework.