# ASP.NET no Plesk Windows: 4 hábitos do Linux que falham

Guia documental para agência que só operou cPanel: os quatro pontos onde o reflexo do Linux quebra, com checklist de entrega e frase pronta para o cliente.

> hospedar ASP.NET no Plesk Windows exige refazer quatro hábitos do Linux: `web.config` no lugar do `.htaccess`, permissões por ACL e pela identidade do pool em vez de chmod, reciclagem do pool a cada deploy, e logs no IIS e no Event Viewer, não em error_log.

João Rizzon · 2026-10-22 · Painéis

---

## Os quatro reflexos do Linux que não funcionam no Windows

Quem só operou Linux com cPanel tem quatro reflexos que não funcionam em Plesk para Windows. Não é questão de aprender comandos novos: é que o equivalente existe, só que em outro lugar e com outra lógica. Abaixo, o mapa que vale colar na parede da agência antes de aceitar a conta.

| Hábito no Linux/cPanel | Equivalente no Plesk Windows |
|---|---||
| `.htaccess` com rewrite e headers | `web.config` (XML lido pelo IIS) |
| `chmod` / `chown` por usuário e grupo | ACL do NTFS, atribuída pelo Plesk e pela identidade do pool de aplicação |
| Reiniciar PHP-FPM ou tocar o arquivo | Reciclar o pool de aplicação do site |
| `tail -f error_log` | Log do IIS, Event Viewer e `<customErrors>` no `web.config` |

Os quatro pontos da tabela cobrem quase todo o atrito das primeiras semanas. O banco fica fora do mapa porque troca de produto inteiro, de MySQL para SQL Server, e tem seção própria mais abaixo. DNS, e-mail, SSL e backup ficam nos mesmos lugares do painel Plesk, independentemente do sistema operacional do servidor.

## Por que o .htaccess fica inerte no IIS, sem erro e sem efeito

O IIS não lê `.htaccess`. Se o cliente herdou um site ASP.NET e você subiu um `.htaccess` com `RewriteRule`, o arquivo fica ali, inerte, sem erro e sem efeito. Esse é o engano mais comum e o mais caro, porque não gera mensagem nenhuma.

A configuração por diretório no IIS vive em `web.config`, um XML na raiz do site (e, se preciso, em subpastas, com herança igual à do `.htaccess`). Regras de reescrita dependem do módulo URL Rewrite instalado no servidor. Antes de escrever qualquer regra, confirme com o provedor se o módulo está presente: sem ele, a seção `<rewrite>` derruba o site com erro de configuração, não com erro 404.

### Exemplo de redirecionamento de www para domínio raiz (fictício)

O bloco abaixo é um **exemplo ilustrativo** de redirecionamento permanente de `www` para domínio raiz. Adapte o host ao projeto e teste em staging antes de aplicar em produção.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="Remove www" stopProcessing="true">
          <match url="(.*)" />
          <conditions>
            <add input="{HTTP_HOST}" pattern="^www\.exemplo\.com\.br$" />
          </conditions>
          <action type="Redirect" url="https://exemplo.com.br/{R:1}"
                  redirectType="Permanent" />
        </rule>
      </rules>
    </rewrite>
  </system.webServer>
</configuration>
```

Duas armadilhas de XML que não existiam no `.htaccess`: um caractere inválido ou uma tag não fechada invalida o arquivo inteiro e o site responde erro 500 de configuração, não apenas ignora a linha errada. E `&` precisa virar `&amp;` dentro de atributos. Sempre valide o XML antes de salvar.

Quando um site é hospedado com PHP no Windows, a mesma lógica vale: as regras de reescrita de um WordPress ou Laravel precisam estar em `web.config`, não em `.htaccess`.

## Por que não existe chmod e quem manda é a ACL do NTFS

No Linux você pensa em dono, grupo e três dígitos. No Windows, cada arquivo e pasta carrega uma lista de controle de acesso (ACL), com entradas por usuário ou grupo e permissões granulares (leitura, escrita, modificação, controle total). O Plesk para Windows cria e administra as contas de sistema e aplica as ACLs das pastas do site automaticamente quando você cria o domínio. O comportamento está descrito no guia de administração avançada do Plesk for Windows, versão 12.5 ([documentação do fabricante](https://docs.plesk.com/en-US/12.5/advanced-administration-guide-win_sitemap.xml)). É uma versão antiga do painel: o princípio continua valendo, mas nomes de menu e caminhos de tela mudaram nas versões atuais, então confira na interface que você tem em mãos antes de seguir o passo a passo ao pé da letra.

A consequência prática: **não mexa na ACL à mão se o Plesk pode fazer por você**. Reconfigurar permissões pelo painel, ou recriar a hospedagem do domínio, costuma restaurar o conjunto correto. Ajuste manual no Explorer tende a quebrar a herança da pasta e produzir erros intermitentes que só aparecem no deploy seguinte.

### Quando mexer na ACL à mão é inevitável

Um app ASP.NET que grava em disco (upload, cache, log em arquivo, `App_Data`) precisa que a **identidade do pool de aplicação** tenha permissão de escrita naquela pasta específica, e só nela. Esse é o análogo do `chown www-data:www-data uploads/`. Conceda no nível da subpasta, nunca na raiz do site, e nunca conceda controle total a grupos amplos.

Sintoma típico de ACL faltando: a aplicação responde erro de acesso negado ao gravar, ou o upload falha silenciosamente enquanto o resto do site funciona. Se a falha é só em escrita e só em uma pasta, é ACL. Se é o site inteiro, provavelmente é `web.config` ou o pool parado.

## Por que o deploy não muda nada até reciclar o pool

Um aplicativo ASP.NET roda dentro de um pool de aplicação do IIS, um processo que mantém o código compilado e o estado em memória entre requisições. É o conceito mais ausente do repertório de quem veio do Apache com PHP: lá o bytecode também fica em cache (OPcache, padrão desde o PHP 5.5), mas cada requisição nasce e morre sem guardar estado da aplicação no processo. No IIS, o processo continua vivo com o que você publicou carregado dentro dele.

O que isso implica no dia a dia da agência:

- Depois de substituir DLLs em `bin/`, o pool precisa ser reciclado para o código novo entrar em vigor. Alterar `web.config` normalmente já dispara reinício da aplicação, mas não conte com isso como procedimento.
- Reciclar o pool **derruba o estado em memória**: sessões em memória se perdem, cache em processo esvazia. Em loja, avise antes. Em aplicação com sessão em banco ou em servidor de estado, o impacto é menor.
- Pool parado faz o site inteiro responder erro de servidor, sem nenhuma pista no código. Antes de investigar aplicação, confirme no Plesk se o pool do domínio está rodando.
- O Plesk expõe o gerenciamento do pool de aplicação por domínio no painel, incluindo ligar, desligar e reciclar, de acordo com a documentação do produto para Windows.

Padronize no runbook da agência: **toda publicação termina com reciclar o pool e validar uma URL de saúde**. Duas linhas no checklist evitam a chamada de "subi e não mudou nada".

## As três fontes de log que substituem o error_log

Não existe `error_log` na raiz do site. O diagnóstico no Windows se divide em três fontes, e cada uma responde uma pergunta diferente.

| Fonte | Responde | Onde |
|---|---|---||
| Log de acesso do IIS | Qual URL, qual status HTTP, qual horário | Pasta de logs do domínio, acessível pelo Plesk |
| Event Viewer (logs de Aplicativo e Sistema) | Exceção não tratada, falha do pool, erro de configuração | Console do Windows no servidor |
| Erro detalhado da aplicação | Stack trace do ASP.NET | Controlado por `<customErrors>` no `web.config` |

Fluxo que funciona: comece pelo log do IIS para achar a requisição e o código de status. `500` manda você ao Event Viewer. `404` em URL amigável aponta para reescrita ausente ou módulo URL Rewrite faltando. `403` quase sempre é ACL ou documento padrão.

Sobre `<customErrors>`: o atributo `mode` aceita três valores, `On` (erro amigável para todo mundo), `Off` (erro detalhado para todo mundo, inclusive visitante anônimo) e `RemoteOnly` (erro detalhado só para quem acessa pelo navegador do próprio servidor, amigável para o resto). Não existe filtro por IP dentro do `customErrors`. Em produção, deixe `RemoteOnly` e leia o stack trace entrando no servidor por RDP e abrindo o site em `http://localhost`, ou reproduza a falha em staging com `Off`. Se o acesso ao console não for possível e você precisar de `Off` em produção, a restrição por endereço tem que vir de outro mecanismo, o módulo IP and Domain Restrictions do IIS aplicado ao site, e ainda assim ligue, colete e volte para `RemoteOnly` no mesmo dia. Deixe isso explícito no checklist, porque é o item que todo mundo esquece.

## O que muda ao trocar MySQL por SQL Server

O stack ASP.NET clássico usa Microsoft SQL Server. No Plesk para Windows, o banco é criado e administrado pelo painel, com usuário próprio, e a aplicação se conecta por uma connection string no `web.config` (ou em `appsettings.json`, em projetos mais recentes).

O que muda para quem só fez dump de MySQL:

- Backup e restauração usam o formato do SQL Server, não `mysqldump`. Exportar pelo Plesk é o caminho curto.
- A connection string fica no arquivo de configuração versionado. Trate credencial de banco como segredo: não suba `web.config` com senha para repositório público.
- Erro de login do banco aparece como exceção no Event Viewer, não como mensagem amigável na página, a menos que a aplicação trate.

## Checklist para herdar um site ASP.NET em Plesk Windows

- Confirmar com o provedor a versão do .NET disponível e se o módulo URL Rewrite está instalado.
- Levantar a árvore de arquivos e localizar todos os `web.config` (raiz e subpastas), porque herança explica comportamento estranho.
- Verificar no painel se o pool de aplicação do domínio está ativo e anotar como reciclá-lo.
- Listar as pastas de escrita da aplicação (upload, cache, `App_Data`) e validar permissão da identidade do pool apenas nelas.
- Localizar a pasta de logs do IIS do domínio e abrir o Event Viewer uma vez, para saber onde procurar antes de ter urgência.
- Conferir `<customErrors>` em produção: `mode` deve estar em `On` ou `RemoteOnly`, nunca em `Off`.
- Exportar um backup completo (arquivos e banco SQL Server) antes de qualquer alteração.
- Replicar o site em staging e testar a primeira publicação lá, incluindo a reciclagem do pool.
- Documentar no runbook do cliente: onde fica o `web.config`, como reciclar o pool, onde ficam os logs.
- Se o site for PHP rodando em Windows, migrar as regras do `.htaccess` para `web.config` e testar cada rota amigável.

## Duas frases prontas para explicar ao cliente

Quando o cliente mandar "o arquivo de redirecionamento sumiu", não explique IIS. Use isto:

> **** "O seu site roda em servidor Windows, e nesse tipo de servidor o arquivo de regras se chama `web.config`, não `.htaccess`. O `.htaccess` existe só no Apache, do mundo Linux. As regras que você tinha continuam valendo, mas precisam ser escritas no formato do `web.config`. Já fiz a conversão e testei os endereços antigos: nenhum link quebra."

E quando ele perguntar por que o deploy "não mudou nada":

> **** "O aplicativo fica carregado na memória do servidor. Depois de publicar arquivos novos, o processo precisa ser reciclado para ler a versão nova. Isso leva alguns segundos e faz parte do procedimento de publicação."

Duas frases que poupam uma reunião. Guarde no modelo de e-mail da agência junto com o checklist acima, e o próximo site Windows que cair no seu colo deixa de ser evento.

