Como desenvolver aplicações ASP.NET Framework 4.x no macOS

O ServBay, através de seu poderoso ambiente Mono integrado, torna o desenvolvimento e a testagem de aplicações ASP.NET Framework 1.1/2.0/3.x/4.x (suportado até 4.7.x) no macOS simples e viável.

A partir da versão 1.12.0 do ServBay, integramos o Mono 6.14.0, que inclui o servidor de desenvolvimento XSP, proporcionando duas maneiras principais de rodar aplicações ASP.NET Framework 4.x:

• Usando XSP para desenvolvimento e teste rápidos
• E utilizando Nginx + FastCGI para implantações mais estáveis e próximas do ambiente de produção.

Este documento guiará você na configuração e execução de seu projeto ASP.NET Framework 4.x no ambiente ServBay.

Pré-requisitos

1. Instalar o ServBay: Certifique-se de que você tenha o ServBay v1.12.0 ou uma versão superior instalada no macOS.
2. Instalar o Mono:
   • Abra o aplicativo ServBay.
   • No menu de navegação à esquerda, selecione “Pacotes”.
   • Na lista de pacotes, encontre a categoria “.NET” e clique para expandir.
   • Localize “Mono 6” (a versão deve ser 6.14.0 ou superior), clique no botão “Instalar” à direita e aguarde a conclusão da instalação.

Preparando seu projeto ASP.NET

1. Arquivo do projeto: Certifique-se de ter um projeto de Aplicação Web ou Site Web do ASP.NET Framework 4.x.
2. Local recomendado: Nós recomendamos fortemente que você coloque seu projeto de site no diretório www do ServBay, que fica em /Applications/ServBay/www/. Crie um subdiretório separado para cada projeto.
   • Exemplo: Se o nome do seu projeto for MyWebApp, o caminho recomendado seria /Applications/ServBay/www/MyWebApp.
   • Nos passos seguintes, utilizaremos /Applications/ServBay/www/MyWebApp como caminho de exemplo. Certifique-se de substituí-lo pelo caminho real do seu projeto.

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

XSP é um servidor web ASP.NET leve, projetado especificamente para o Mono, ideal para as fases de desenvolvimento e testes rápidos. O pacote Mono 6 instalado pelo ServBay já inclui o XSP4 (compatível com ASP.NET 4.x).

Dica

• Se você precisa rodar um projeto ASP.NET 1.1, use o comando xsp.
• Se você precisa rodar um projeto ASP.NET 2.0, use o comando xsp2.

Passos:

1. Abra o terminal: Abra o aplicativo Terminal no macOS.

2. Navegue até o diretório do projeto: Use o comando cd para entrar no diretório raiz do seu projeto ASP.NET (o diretório que contém o arquivo web.config).

   # Exemplo: entre no diretório de um projeto chamado MyWebApp
   cd /Applications/ServBay/www/MyWebApp

3. Inicie o servidor XSP: No diretório raiz do projeto, execute o seguinte comando para iniciar o servidor XSP4. Você pode especificar um número de porta (por exemplo, 8080 ou 9000) para evitar conflitos com outros serviços no ServBay.

   # Inicie o projeto no diretório atual na porta 9000
   xsp4 --port 9000

   • xsp4: chama o servidor XSP para .NET 4.x.
   • --port 9000: especifica o número da porta que o servidor deverá escutar.

4. Acesse a aplicação: Abra seu navegador e acesse http://localhost:9000 ou http://127.0.0.1:9000. Você deverá ver sua aplicação ASP.NET em funcionamento.

5. Pare o servidor: Quando terminar o desenvolvimento ou testes, volte ao terminal e pressione Ctrl + C ou Enter para parar o servidor XSP.

Vantagens:

• Configuração simples e inicialização rápida.
• Ideal para desenvolvimento e depuração locais.

Desvantagens:

• Desempenho inferior ao de servidores de produção como Nginx.
• Funcionalidade mais limitada, não simula completamente um ambiente de produção.

Método 2: Usando Nginx + FastCGI

Esse método utiliza o Nginx gerenciado pelo ServBay como servidor web front-end, encaminhando requisições dinâmicas para o processo de backend Mono (fastcgi-mono-server4) por meio do protocolo FastCGI. Isso proporciona uma implantação mais próxima do ambiente de produção, com desempenho superior.

Dica

• Se você precisa rodar um projeto ASP.NET 1.1, use o comando fastcgi-mono-server.
• Se você precisa rodar um projeto ASP.NET 2.0, use o comando fastcgi-mono-server2.

Passos:

1. Certifique-se de que Mono e Nginx estão instalados e rodando:

   • Instale o Mono 6 e o Nginx através dos pacotes do ServBay.
   • Na seção de “Serviços” do ServBay, verifique se o serviço Nginx está ativo.

2. Prepare seu projeto ASP.NET: Garanta que seu projeto esteja no caminho recomendado, como /Applications/ServBay/www/MyWebApp.

3. Inicie o servidor FastCGI Mono:

   • Abra uma nova janela de terminal.
   • Execute o processo fastcgi-mono-server4. Este processo será responsável por escutar requisições FastCGI do Nginx e executar seu código ASP.NET.

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

     • --applications=/:/Applications/ServBay/www/MyWebApp: mapeia o caminho raiz do site (/) para o caminho físico do seu projeto. Certifique-se de substituir /Applications/ServBay/www/MyWebApp pelo caminho real do seu projeto.
     • --socket=tcp:127.0.0.1:9001: define o endereço e porta TCP que o servidor FastCGI irá escutar. Certifique-se de que esta porta (por exemplo, 9001) não esteja sendo usada por outra aplicação e corresponda à direção fastcgi_pass na configuração do Nginx abaixo.
     • --loglevels=Standard --printlog: (opcional) imprime logs de nível padrão no terminal para facilitar a depuração.
   • Nota: Esta janela de terminal precisará permanecer aberta para o funcionamento do serviço FastCGI. Para execuções prolongadas, você pode usar nohup ou ferramentas como screen/tmux para mantê-lo em segundo plano.

4. Configure o site Nginx:

   • No ServBay, vá para a seção “Sites”.

   • Clique em “Adicionar Site” ou selecione um site existente para editar.

   • Defina o nome de domínio: por exemplo, mywebapp.test. O ServBay irá adicioná-lo automaticamente ao arquivo Hosts.

   • Defina o diretório raiz do site: extremamente importante! Configure-o para o caminho real do seu projeto ASP.NET, como /Applications/ServBay/www/MyWebApp. Isso irá configurar corretamente a diretiva root na configuração do Nginx.

   • Chave: verifique/edite o arquivo de configuração do Nginx: Clique na caixa de seleção “Configuração personalizada” no canto superior direito das configurações do site. O ServBay gerará uma configuração básica com base no caminho raiz que você definiu. Você deverá garantir que as configurações para location / e @mono (ou outros blocos de localização com nomes semelhantes) estejam corretas para encaminhar as requisições ao servidor FastCGI Mono.

     Uma parte do exemplo de configuração que precisa ser verificada ou adicionada baseando-se na configuração gerada automaticamente pelo ServBay está apresentada abaixo:

     server {
         listen 443;
         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;
     
         ssl_certificate /Applications/ServBay/ssl/private/tls-certs/mywebapp.test/mywebapp.test.crt; # Certifique-se de que o certificado corresponde ao caminho real
         ssl_certificate_key /Applications/ServBay/ssl/private/tls-certs/mywebapp.test/mywebapp.test.key; # Certifique-se de que o certificado corresponde ao caminho real
     
         server_name mywebapp.test; # Deve ser consistente com o nome de domínio configurado no ServBay
         root /Applications/ServBay/www/MyWebApp; # **Certifique-se** de que isto corresponde ao diretório que você definiu para o site
         index index.html index.htm default.aspx Default.aspx; # Adicione documentos padrão do ASP.NET
     
         location / {
             try_files $uri $uri/ @mono; # Tente arquivos estáticos, caso contrário, passe para @mono
         }
     
         # (opcional, mas recomendado) O Nginx lida diretamente com arquivos estáticos comuns
         # location ~* \.(ico|css|js|gif|jpe?g|png|svg|woff|woff2|ttf|eot)$ {
         #     expires max;
         #     log_not_found off;
         #     access_log off;
         # }
     
         location @mono {
             # Encaminha a requisição para o FastCGI Mono Server
             # **A porta deve** corresponder à porta especificada no parâmetro --socket ao iniciar o fastcgi-mono-server4
             fastcgi_pass 127.0.0.1:9001;
     
             # Parâmetros necessários do FastCGI
             include fastcgi_params;
             # SCRIPT_FILENAME será definido corretamente com base na diretiva root e $fastcgi_script_name
             fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
             fastcgi_param PATH_INFO "";
         }
     
         # O ServBay pode incluir outras configurações padrão, como logs, controle de acesso, etc.
         # access_log /Applications/ServBay/logs/nginx/mywebapp.test.access.log;
         # error_log /Applications/ServBay/logs/nginx/mywebapp.test.error.log;
     }

   • Salve a configuração e reinicie o Nginx: Salve o arquivo de configuração do Nginx. O ServBay irá recarregar automaticamente as configurações do Nginx após a salvamento. Se houver um erro na configuração, o ServBay irá exibir uma mensagem de erro. Se necessário, você pode reiniciar manualmente o Nginx na página de serviços do ServBay.

5. Acesse a aplicação: Abra o navegador e acesse o domínio que você configurou no Nginx (por exemplo, https://mywebapp.test, observe que aqui é utilizado o protocolo HTTPS). O Nginx irá encaminhar a requisição para o fastcgi-mono-server4, que executará seu código ASP.NET.

Vantagens:

• Melhor desempenho e maior estabilidade.
• Mais próxima da forma de implantação em ambientes de produção.
• Pode aproveitar funcionalidades avançadas do Nginx, como manipulação de arquivos estáticos, balanceamento de carga, SSL, entre outras.
• Maior integração com a administração de sites e gerenciamento de domínio e Hosts do ServBay.

Desvantagens:

• Configuração um pouco mais complexa do que a do XSP.
• Necessidade de gerenciar manualmente o processo fastcgi-mono-server4.

Como escolher

• Para desenvolvimento rápido, depuração e testes simples, usar XSP é o caminho mais rápido.
• Para testes ou implantações internas que requerem maior desempenho e maior proximidade com ambientes de produção, ou para aproveitar os recursos avançados do Nginx e as funcionalidades de gerenciamento de sites do ServBay, a escolha do modo Nginx + FastCGI é mais apropriada.

Considerações e resolução de problemas

• Permissões de arquivo: Assegure-se de que o processo do Nginx (geralmente gerido pelo ServBay) e o usuário do macOS que executa o fastcgi-mono-server4 tenham permissão de leitura sobre os arquivos de seu projeto (localizados em /Applications/ServBay/www/YourProjectName). Pode ser necessário ajustar as permissões do diretório (chmod ou chown).
• Caminho: Verifique cuidadosamente se o caminho do projeto na configuração do Nginx (root directive) e na linha de comando do fastcgi-mono-server4 (--applications parameter) estão corretos e apontam para o diretório que contém web.config.
• Conflito de porta: Certifique-se de que a porta utilizada pelo XSP ou fastcgi-mono-server4 (exemplos: 9000 ou 9001) não está em uso por outro aplicativo.
• Logs:
  • Verifique os logs de saída do terminal quando o fastcgi-mono-server4 é iniciado.
  • Confira os logs de erro do Nginx. Você pode encontrar o caminho do log de erro correspondente ao site nas configurações do site no ServBay (geralmente localizado em /Applications/ServBay/logs/nginx/mywebapp.test.error.log).
• Compatibilidade de versões do Mono: O Mono 6.14.0 é compatível com o .NET Framework desde a versão 1.1 até aproximadamente a versão 4.7.2. Se você estiver utilizando recursos de uma versão superior do .NET Framework, considere instalar o .NET Core ou .NET da Microsoft pelo ServBay.

---

Com o ambiente Mono 6 integrado no ServBay e a estrutura de projeto recomendada, desenvolver e executar aplicações ASP.NET Framework 4.x no macOS se torna mais padrão e conveniente. Esperamos que este documento ajude você a iniciar seu trabalho de desenvolvimento com sucesso!