ClickOnce e as configurações de aplicativo
As configurações de aplicativo para Windows Forms facilita a criação, o repositório e a manutenção de aplicativos personalizados e preferências do usuário no cliente. O documento a seguir descreve como os arquivos de configurações de aplicativo funcionam em um aplicativo ClickOnce e como o ClickOnce migra as configurações quando o usuário atualiza para a próxima versão.
As informações abaixo se aplicam somente ao provedor de configurações de aplicativo padrão, a classe LocalFileSettingsProvider. Se você fornecer um provedor personalizado, esse provedor determinará como ele armazena seus dados e como ele atualiza suas configurações entre as versões. Para obter mais informações sobre provedores de configurações de aplicativo, consulte Arquitetura de configurações do aplicativo.
Arquivos de configurações de aplicativo
As configurações do aplicativo consomem dois arquivos: <app>.exe.config e user.config, em que app é o nome do aplicativo Windows Forms. user.config é criado no cliente na primeira vez que seu aplicativo armazena configurações no escopo do usuário. Porém, <app>.exe.config existirá antes da implantação se você definir valores padrão para as configurações. O Visual Studio incluirá esse arquivo automaticamente quando você usar o comando Publish. Se você criar seu aplicativo ClickOnce usando Mage.exe ou MageUI.exe, verifique se esse arquivo está incluído nos outros arquivos do aplicativo ao preencher o manifesto do aplicativo.
Observação
No ClickOnce para .NET Core 3.1 e .NET 5 ou posterior, use dotnet-mage.exe em vez de Mage.exe. Para obter mais informações, confira ClickOnce para .NET.
Em um aplicativo Windows Forms não implantado usando o ClickOnce, o arquivo app<.exe.config> de um aplicativo é armazenado no diretório do aplicativo, enquanto o arquivo user.config é armazenado na pasta Documentos e Configurações do usuário. Em um aplicativo ClickOnce, <app>.exe.config reside no diretório do aplicativo dentro do cache do aplicativo ClickOnce, e user.config reside no diretório de dados do ClickOnce para esse aplicativo.
Independentemente de como você implanta seu aplicativo, as configurações do aplicativo garantem o acesso de leitura seguro ao <app>.exe.confige o acesso seguro de leitura/gravação ao user.config.
Em um aplicativo ClickOnce, o tamanho dos arquivos de configuração usados pelas configurações do aplicativo é restrito pelo tamanho do cache ClickOnce. Para obter mais informações, consulte Visão geral do cache do ClickOnce.
.NET Core e .NET 5+
Atualmente, um assembly do .NET Core a ser publicado precisa ser assinado com um arquivo de chave de nome forte. Se não estiver, o método ApplicationSettingsBase.Upgrade não copiará as configurações corretamente após uma nova publicação do ClickOnce. Você pode especificar o uso de um nome forte nas propriedades do projeto do .NET Core, na opção Build > Nomenclatura forte.
Atualizações de versão
Assim como cada versão de um aplicativo ClickOnce é isolada de todas as outras versões, as configurações do aplicativo para um aplicativo ClickOnce também são isoladas das configurações de outras versões. Quando o usuário atualiza para uma versão posterior do aplicativo, as configurações do aplicativo comparam as configurações da versão mais recente (com maior número) com as configurações fornecidas com a versão atualizada e mesclam as configurações em um novo conjunto de arquivos de configurações.
A tabela a seguir descreve como as configurações do aplicativo decidem quais configurações copiar.
| Tipo de alteração | Ação de atualização |
|---|---|
| Configuração adicionada a <app>.exe.config | A nova configuração é mesclada ao app<.exe.configda> da versão atual |
| Configuração removida de <app>.exe.config | A configuração antiga é removida do app<.exe.configda> da versão atual |
| O padrão da configuração foi alterado; configuração local ainda definida como padrão original no user.config | A configuração é mesclada no user.config da versão atual com o novo padrão como o valor |
| O padrão da configuração foi alterado; configuração definida como não padrão original no user.config | A configuração é mesclada no user.config da versão atual com o valor não padrão retido |
Se você criou sua própria classe wrapper de configurações de aplicativo e deseja personalizar a lógica de atualização, poderá substituir o método Upgrade.
Configurações de ClickOnce e roaming
O ClickOnce não funciona com configurações de roaming, o que permite que o arquivo de configurações seja migrado entre computadores em uma rede. Se você precisar de configurações de roaming, precisará implementar um provedor de configurações de aplicativo que armazena configurações pela rede ou desenvolver suas próprias classes de configurações personalizadas para armazenar as configurações em um computador remoto. Para obter mais informações sobre provedores de configurações, consulte Arquitetura de configurações do aplicativo.