Desenvolvendo com ASP.NET Framework 4.x no macOS usando o ServBay

O ServBay simplifica o desenvolvimento e testes do ASP.NET Framework 1.1/2.0/3.x/4.x (com suporte até 4.7.x) no macOS, graças ao seu ambiente Mono integrado e altamente compatível.

A partir da versão v1.12.0, o ServBay inclui o Mono 6.14.0, já acompanhando o servidor de desenvolvimento XSP e a ferramenta fastcgi-mono-server, apresentando duas principais formas para executar aplicativos ASP.NET Framework 4.x:

1. Usando o XSP para desenvolvimento e testes rápidos: O XSP é um servidor web leve, projetado especialmente para o Mono, ideal para fases de desenvolvimento e testes rápidos.
2. Implantação com Nginx + FastCGI: Esta configuração oferece maior estabilidade, desempenho aprimorado e simula ambientes de produção, com o Nginx do ServBay encaminhando solicitações para o backend Mono.

Este guia vai mostrar como configurar e rodar seu projeto ASP.NET Framework 4.x no ambiente do ServBay.

Sobre .NET Framework e .NET

Atenção: este documento se refere ao desenvolvimento com ASP.NET Framework 4.x usando o Mono, que corresponde a uma stack .NET de tecnologias mais antigas.

O ServBay também possui suporte total para as versões mais recentes do .NET (incluindo .NET Core, .NET 5/6/7/8+), tanto para desenvolvimento quanto para deploy. Se você está criando novos projetos ou deseja migrar para versões mais modernas do .NET, recomendamos utilizar o suporte oficial SDK/runtime da Microsoft fornecido pelo ServBay, ao invés do método baseado em Mono abordado neste material.

Pré-requisitos

1. Instalar o ServBay: Certifique-se de estar com o ServBay v1.12.0 ou superior instalado no seu macOS.
2. Instalar o Mono:
   • Abra o aplicativo ServBay.
   • No menu à esquerda, acesse “Pacotes”.
   • Na lista, expanda a categoria “.NET”.
   • Localize o “Mono 6” (versão mínima 6.14.0) e clique em “Instalar”. Aguarde até a instalação ser concluída.

Preparando seu projeto ASP.NET

1. Arquivos do Projeto: Confirme que você possui um projeto ASP.NET Framework 4.x (Web Application ou Web Site) contendo o arquivo web.config.
2. Localização recomendada: Recomendamos fortemente armazenar seu projeto web no diretório unificado www, gerenciado pelo ServBay: /Applications/ServBay/www/. Crie um subdiretório para cada projeto.
   • Exemplo: Se seu projeto se chama MyWebApp, o caminho raiz recomendado é /Applications/ServBay/www/MyWebApp.
   • Nos exemplos abaixo, usaremos /Applications/ServBay/www/MyWebApp como caminho. Lembre-se de substituir pelo caminho real do seu projeto.

Método 1: Usando XSP (servidor de desenvolvimento integrado)

O XSP, incluso no pacote Mono 6 do ServBay, é um web server leve, ideal para desenvolvimento local e testes rápidos de aplicações ASP.NET Framework. O XSP4 corresponde à versão do .NET Framework 4.x.

Dica

• Para projetos ASP.NET 1.1, use o comando xsp.
• Para ASP.NET 2.0/3.x, use xsp2.
• Para ASP.NET 4.x, utilize xsp4.

Passo a passo:

1. Abra o Terminal: No macOS, execute o aplicativo Terminal.

2. Navegue até o diretório do projeto: Use o comando cd para acessar a raiz do seu projeto ASP.NET (a pasta do web.config).

   # Exemplo: acessando o diretório MyWebApp
   cd /Applications/ServBay/www/MyWebApp

3. Inicie o servidor XSP: No diretório raiz do projeto, execute o comando abaixo para iniciar o XSP4. Escolha uma porta livre (como 8080 ou 9000), evitando conflitos com outros serviços do ServBay.

   # Inicia o projeto na porta 9000
   xsp4 --port 9000

   • xsp4: Inicia o servidor XSP específico para .NET Framework 4.x.
   • --port 9000: Define a porta TCP onde o servidor irá escutar.

4. Acesse sua aplicação: No navegador, abra http://localhost:9000 ou http://127.0.0.1:9000. Seu aplicativo ASP.NET deve estar em execução.

5. Parando o servidor: Ao finalizar o desenvolvimento ou teste, volte à janela do terminal em que o XSP está rodando e pressione Ctrl + C ou Enter para encerrar o servidor.

Vantagens:

• Configuração fácil e inicialização rápida.
• Excelente para desenvolvimento e depuração local.

Desvantagens:

• Desempenho inferior a servidores web de produção como Nginx.
• Recursos limitados; não simula totalmente o ambiente de produção.
• Terminal deve permanecer aberto.

Método 2: Utilizando Nginx + FastCGI

Neste método, o Nginx gerenciado pelo ServBay atua como frontend, recebendo solicitações e servindo arquivos estáticos; já os pedidos dinâmicos (ex: .aspx, .ashx) são enviados via FastCGI para o backend Mono (fastcgi-mono-server4). O resultado é um ambiente mais próximo da produção, com desempenho superior e acesso a recursos avançados do Nginx (SSL, cache, compressão, etc.).

Dica

• Para projetos ASP.NET 1.1, use fastcgi-mono-server.
• Para ASP.NET 2.0/3.x, use fastcgi-mono-server2.
• Para ASP.NET 4.x, utilize fastcgi-mono-server4.

Passo a passo:

1. Garanta que Mono e Nginx estão instalados e ativos:

   • No menu “Pacotes” do ServBay, instale Mono 6 e Nginx.
   • Em “Serviços”, verifique que o Nginx está em execução.

2. Preparando o projeto: Tenha seu projeto no caminho sugerido, como /Applications/ServBay/www/MyWebApp.

3. Inicie o FastCGI Mono Server:

   • Abra uma nova janela do terminal.
   • Execute o processo fastcgi-mono-server4 — este ficará ouvindo solicitações FastCGI vindas do Nginx, processando páginas ASP.NET e a lógica do negócio.

     # Exemplo: iniciando o FastCGI para o projeto MyWebApp
     fastcgi-mono-server4 --applications=/:/Applications/ServBay/www/MyWebApp \
                          --socket=tcp:127.0.0.1:9001 \
                          --loglevels=Standard \
                          --printlog

     • fastcgi-mono-server4: Inicializa o servidor FastCGI para .NET Framework 4.x.
     • --applications=/:/Applications/ServBay/www/MyWebApp: Mapeia a URL raiz / para o caminho físico do projeto. Quando o Nginx encaminha um pedido para /alguma/pagina.aspx, o Mono procurará dentro de /Applications/ServBay/www/MyWebApp/alguma/pagina.aspx. Ajuste para o caminho real do seu projeto.
     • --socket=tcp:127.0.0.1:9001: Configura o endereço e porta TCP para escuta FastCGI. Use uma porta livre e coordene com a configuração correspondente no Nginx (fastcgi_pass).
     • --loglevels=Standard --printlog: (Opcional) exibe logs padrão no terminal, facilitando o debug e acompanhamento do Mono.
   • Observação: Mantenha a janela do terminal aberta enquanto o fastcgi-mono-server4 estiver rodando. Para execução em segundo plano, considere usar nohup, screen ou tmux.

4. Configurar o site no Nginx:

   • No ServBay, acesse a seção “Sites”.

   • Clique em “Adicionar site” ou edite um já existente.

   • Configure o domínio: Exemplo: mywebapp.servbay.demo. O ServBay adicionará este domínio no arquivo hosts do macOS, direcionando para o 127.0.0.1.

   • Configure o diretório raiz do site: Muito importante! Defina o caminho físico correspondente ao seu projeto ASP.NET, como /Applications/ServBay/www/MyWebApp. Isso é fundamental para o parâmetro root do Nginx, que será usado no serviço de arquivos estáticos.

   • Ative e edite configurações customizadas: Marque a caixa “Configuração personalizada” nas opções do site. O ServBay irá gerar um arquivo base de configuração do Nginx conforme seu domínio e raiz; modifique conforme o exemplo abaixo para encaminhar requisições dinâmicas ao FastCGI Mono Server.

     Um exemplo baseado na configuração automática do ServBay, com trechos a serem revisados, adicionados ou alterados:

     server {
         listen 80; # Escuta na porta HTTP
         listen 443 ssl http2; # Porta HTTPS, SSL e HTTP/2 habilitados
     
         # Configuração automatizada de SSL do ServBay
         ssl_protocols TLSv1.2 TLSv1.3;
         ssl_ciphers 'TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384';
         ssl_prefer_server_ciphers on;
         ssl_session_timeout 1d;
         ssl_session_cache shared:ServBay:10m;
         ssl_session_tickets off;
     
         # Caminhos dos certificados, gerenciados pelo ServBay
         ssl_certificate /Applications/ServBay/ssl/private/tls-certs/mywebapp.servbay.demo/mywebapp.servbay.demo.crt; # Certifique-se que está correto para o seu domínio
         ssl_certificate_key /Applications/ServBay/ssl/private/tls-certs/mywebapp.servbay.demo/mywebapp.servbay.demo.key; # Certifique-se que está correto para o seu domínio
     
         server_name mywebapp.servbay.demo; # Igual ao domínio configurado
         root /Applications/ServBay/www/MyWebApp; # **Certifique-se** que corresponde à raiz do projeto
     
         # Documentos padrão do ASP.NET, tentados caso index.html/htm não sejam encontrados
         index index.html index.htm default.aspx Default.aspx;
     
         # Lógica principal de roteamento
         location / {
             # Procura sequencialmente por arquivo ou diretório; se não for estático, repassa ao @mono
             try_files $uri $uri/ @mono;
         }
     
         # (Opcional, mas recomendado) Manuseio eficiente de arquivos estáticos comuns no Nginx
         # Permite uso de cache de navegador via 'expires'
         location ~* \.(ico|css|js|gif|jpe?g|png|svg|woff|woff2|ttf|eot)$ {
             expires max; # Cache máximo no navegador
             log_not_found off; # Não loga erros de arquivos estáticos ausentes
             access_log off; # Não loga acesso a arquivos estáticos
         }
     
         # Bloco 'location' nomeado @mono para tratar requisições dinâmicas
         location @mono {
             # Encaminha via FastCGI para o Mono Server (mesmo endereço/porta de --socket)
             fastcgi_pass 127.0.0.1:9001;
     
             # Inclui parâmetros padrão FastCGI
             include fastcgi_params;
             # Parâmetro essencial: caminho completo do arquivo, que será resolvido pelo Mono
             fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
             # PATH_INFO geralmente não usado aqui, então mantido vazio
             fastcgi_param PATH_INFO "";
     
             # (Opcional) Adicione outros parâmetros FastCGI como HOST se necessário
             # fastcgi_param HOST $host;
         }
     
         # O ServBay pode incluir outras configurações por padrão, como caminhos de log
         # access_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.access.log;
         # error_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.error.log;
     }

   • Salve e recarregue/reinicie o Nginx: Após editar, salve a configuração. O ServBay tentará recarregar o Nginx automaticamente e avisará em caso de erro de sintaxe. Se necessário, reinicie manualmente o serviço Nginx em “Serviços”.

5. Acesse sua aplicação: No navegador, acesse o domínio configurado (ex: https://mywebapp.servbay.demo). Com SSL ativado na porta 443, prefira sempre HTTPS. O Nginx irá tratar arquivos estáticos e encaminhar as requisições dinâmicas ao fastcgi-mono-server4, que executará seu código ASP.NET.

Vantagens:

• Desempenho elevado e maior estabilidade, simulando um ambiente real;
• Permite uso de recursos avançados do Nginx (serviço eficiente de arquivos estáticos, SSL, balanceamento, etc.);
• Alta integração com o gerenciamento de sites, domínios e hosts do ServBay.

Desvantagens:

• Requer configuração mais detalhada que o uso direto do XSP.
• O processo do fastcgi-mono-server4 deve ser gerenciado manualmente (ou via ferramentas de gerenciamento de processos).

Qual método escolher?

• Para desenvolvimento rápido, debug e testes simples, o XSP é o caminho mais prático e veloz — tudo pronto com um comando.
• Quando se precisa de desempenho superior, ambiente próximo à produção, utilização de recursos do Nginx (HTTPS, domínios customizados, otimização de estáticos), ou integração máxima com a gestão de sites do ServBay, o modo Nginx + FastCGI é o recomendável.

Atenção e Solução de Problemas

• Permissões de arquivo: Verifique se o usuário do processo Nginx (gerenciado pelo ServBay) e o usuário do fastcgi-mono-server4 possuem permissão de leitura adequada sobre seu projeto (/Applications/ServBay/www/NomeDoProjeto). Ajuste permissões usando chmod ou chown se necessário.
• Consistência de caminhos: Confirme que o diretório do projeto nos parâmetros root (Nginx) e --applications (fastcgi-mono-server4) está correto — ambos devem apontar para a raiz do projeto contendo o web.config.
• Conflito de portas: Certifique-se de que as portas usadas (ex: 9000 ou 9001) não estão ocupadas por outros serviços do ServBay ou aplicações do sistema.
• Logs:
  • Analise os logs exibidos no terminal pelo fastcgi-mono-server4 (o parâmetro --printlog ajuda na depuração).
  • Confira os logs de erro do Nginx (indicados nas configurações do site no ServBay, tipicamente em /Applications/ServBay/logs/nginx/seu-dominio.error.log). Eles são úteis para investigar falhas de configuração ou comunicação com o backend Mono.
• Compatibilidade da versão Mono: O Mono 6.14.0 do ServBay é amplamente compatível com .NET Framework 1.1 até 4.7.2. Para recursos de versões superiores ou em casos de problemas de compatibilidade, utilize o SDK/runtime oficial Microsoft via ServBay ou adapte seu projeto para uma versão do Framework suportada pelo Mono.
• Gestão do processo FastCGI: No modo Nginx + FastCGI, o fastcgi-mono-server4 precisa estar sempre ativo. Para ambientes de produção ou longa duração, considere configurá-lo como serviço de segundo plano (usando process managers como systemd, supervisord, ou similares).

---

Com o Mono 6 integrado ao ServBay e a estrutura de projetos recomendada, desenvolver e executar aplicações ASP.NET Framework 4.x tradicionais no macOS ficou mais simples e padronizado. Esperamos que este guia facilite o início dos seus trabalhos!