Criar um instalador Windows para um app .NET (WPF, WinForms, console)

O Visual Studio compila seu app WPF ou WinForms, e o dotnet publish entrega uma pasta que roda em qualquer lugar. A peça que falta é o instalador: a entrada no Menu Iniciar, a pasta em Program Files, a entrada de desinstalação nas Configurações do Windows. O velho ClickOnce e o Visual Studio Installer Projects ainda existem, mas os dois já mostram a idade. Este é o caminho direto de um projeto .NET até um Setup.exe.

Passo 1: publicar o app

A publicação gera uma pasta com tudo de que o app precisa. Execute a partir da pasta do projeto:

dotnet publish -c Release -r win-x64 --self-contained true

A saída fica em bin\Release\net8.0-windows\win-x64\publish\ (o framework de destino no caminho varia conforme o projeto). Essa pasta é o que você distribui.

A única decisão que importa:

• Autocontido (--self-contained true) inclui o runtime do .NET. A pasta tem de 70 a 150 MB, mas roda em qualquer máquina Windows sem instalar nada antes. Escolha esta opção para software distribuído ao público.
• Dependente do framework (--self-contained false) tem poucos MB, mas o usuário precisa ter o .NET Desktop Runtime correspondente instalado; caso contrário, o app exibe um aviso de download na primeira execução. Serve para ferramentas internas em máquinas gerenciadas.

Opções úteis:

• -p:PublishReadyToRun=true pré-compila o app para iniciar mais rápido.
• -p:PublishSingleFile=true junta a saída em um único .exe. Funciona, mas um instalador elimina o motivo para usá-lo, e apps de arquivo único descompactam as bibliotecas nativas na primeira execução. A pasta comum é mais simples.
• O trimming (PublishTrimmed) não é suportado em WPF e WinForms; deixe desativado.

Defina o ícone do app no arquivo do projeto para que o .exe publicado o carregue:

<PropertyGroup>
  <ApplicationIcon>app.ico</ApplicationIcon>
</PropertyGroup>

Execute o .exe publicado uma vez a partir da pasta de publicação, de preferência em uma máquina sem Visual Studio, para garantir que não falta nada.

Passo 2: compactar a pasta de publicação

Compacte o conteúdo de publish`: o .exe, as DLLs, .deps.json, .runtimeconfig.json e quaisquer arquivos de conteúdo. Deixe de fora os arquivos .pdb`, a menos que queira símbolos de depuração nas máquinas dos clientes.

Passo 3: gerar o instalador

1. Envie o zip para o ExeTup. Ele seleciona o .exe do seu app como programa principal; confirme, porque uma publicação autocontida inclui o createdump.exe, que não é o principal.
2. Preencha o nome, a versão (mantenha alinhada com <Version> no projeto), o editor e a licença.
3. Escolha todos os usuários para um app desktop clássico em Program Files, ou usuário atual quando os clientes podem não ter direitos de administrador.
4. Mantenha 64 bits para uma publicação win-x64; escolha 32 bits para win-x86.
5. Envie o mesmo app.ico, ative os atalhos e gere o instalador.

Baixe o Setup.exe e teste a instalação e a desinstalação no Windows.

Observações específicas do .NET

• Atualizações. Distribua um novo instalador com uma versão maior. Instalar por cima da versão antiga substitui os arquivos; o instalador não inclui um canal de atualização automática.
• Configurações e dados. Grave os dados do usuário em %APPDATA% ou %LOCALAPPDATA%, não ao lado do .exe. Program Files é somente leitura para usuários comuns, e o desinstalador remove apenas o que instalou.
• Pré-requisitos. Publicações autocontidas não precisam de mais nada. Se o seu app precisa do runtime do Visual C++ ou de um driver de banco de dados, documente isso; o instalador não encadeia outros instaladores.
• Assinatura de código. Assine o .exe publicado antes de compactar e depois assine o Setup.exe baixado. Veja o guia sobre o SmartScreen.

Alternativas

• Visual Studio Installer Projects gera arquivos MSI de dentro do Visual Studio. Ainda disponível como extensão, limitado e incômodo com publicações autocontidas.
• ClickOnce oferece instalações por usuário com atualização automática, vinculadas a um servidor web que você mantém.
• WiX Toolset gera arquivos MSI a partir de XML e é o padrão para empacotamento MSI de nível corporativo. Poderoso, com uma curva de aprendizado à altura.
• MSIX é o formato de pacote mais recente da Microsoft, ideal quando o alvo é a Microsoft Store.

Veja Instaladores MSI vs EXE para saber quando o formato faz diferença.

Perguntas frequentes

Devo publicar dependente do framework ou autocontido?

Autocontido para tudo o que você entrega ao público, para que o app rode sem baixar um runtime. Dependente do framework para ferramentas internas em máquinas em que a TI gerencia o runtime do .NET.

O instalador inclui o runtime do .NET?

Se você publicar autocontido, sim, porque ele faz parte da pasta de publicação. O instalador distribui o que estiver no zip.

Posso gerar um MSI para a Política de Grupo?

O ExeTup gera um Setup.exe. Ele instala silenciosamente com /S, o que cobre a maioria das implantações por script. Para políticas que só aceitam MSI, o WiX é a ferramenta certa.

Com quais versões do .NET isso funciona?

Com qualquer uma que gere uma pasta de publicação: .NET 6, 7, 8, 9 e posteriores, além de apps .NET Framework compilados com o Visual Studio (use a saída de bin\Release).