Guia de configuração do ambiente de desenvolvimento do Windsurf

Visão geral

Os workspaces do Windsurf dependem exclusivamente de ferramentas open source para compilação, linting e depuração. Os componentes proprietários do Visual Studio, da Microsoft, não podem ser redistribuídos; por isso, integramos servidores de linguagem, depuradores e compiladores mantidos pela comunidade. Este guia aborda duas stacks:
  1. .NET / C# – com suporte tanto ao .NET Core quanto ao .NET Framework (via Mono)
  2. C / C++ – usando ferramentas baseadas em clang
Você pode instalar uma ou ambas no mesmo workspace.
⚠️ Importante: Os exemplos abaixo são modelos que você deve ajustar ao seu projeto. Será necessário editar caminhos de arquivos, nomes de projetos e comandos de build para corresponder ao seu codebase.

1. Desenvolvimento em .NET / C#

Escolha a variante que corresponde ao seu código.

.NET Core / .NET 6+

Extensões:
  • C# (muhammad-sammy.csharp) – inclui OmniSharp LS e NetCoreDbg, para você poder apertar F5 imediatamente
  • .NET Install Tool (ms-dotnettools.vscode-dotnet-runtime) – instala automaticamente runtimes/SDKs ausentes
  • Solution Explorer (fernandoescolar.vscode-solution-explorer) – navegue e gerencie soluções e projetos .NET
Depurador: Nada mais é necessário — a extensão já inclui o servidor de linguagem e um depurador open source adequado para .NET Core. Build: dotnet build

.NET Framework via Mono

Extensões:
  • Mono Debug (chrisatwindsurf.mono-debug) – adaptador de depuração para Mono (Open VSX)
  • C# (muhammad-sammy.csharp) para recursos da linguagem
Depurador: Você também deve instalar a toolchain do Mono dentro do workspace. Siga o guia de instalação no repositório do Mono. A extensão do depurador se conecta a esse runtime no momento da depuração.
⚠️ Configuração do .NET Framework: Após instalar o Mono, para usar a extensão C# com projetos .NET Framework, é preciso alterar uma configuração específica nas configurações do IDE. Acesse Settings (na seção da extensão C#) e desative “Omnisharp: Use Modern Net”. Essa configuração usa o build do OmniSharp para .NET 6, que oferece melhorias significativas de desempenho para projetos no estilo SDK, .NET Core e .NET 5+. Observe que essa versão não oferece suporte a projetos .NET Framework que não sejam no estilo SDK, incluindo Unity.
Build: mcs Program.cs

Configure tasks.json para o seu projeto

Você deve criar/editar .vscode/tasks.json na raiz do seu workspace e personalizar os seguintes templates:
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build-dotnet",
      "type": "shell",
      "command": "dotnet",
      "args": ["build", "YourProject.csproj"], // ← Edite isso
      "group": "build",
      "problemMatcher": "$msCompile"
    },
    {
      "label": "build-mono",
      "type": "shell",
      "command": "mcs",
      "args": ["YourProgram.cs"], // ← Edite isso
      "group": "build"
    }
  ]
}

Configurar o launch.json para depuração

Você deve criar/editar .vscode/launch.json na raiz do seu workspace e atualizar os caminhos:
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": ".NET Core Launch",
      "type": "coreclr",
      "request": "launch",
      "preLaunchTask": "build-dotnet",
      "program": "${workspaceFolder}/bin/Debug/net6.0/YourApp.dll", // ← Edite este caminho
      "cwd": "${workspaceFolder}",
      "args": [] // Adicione argumentos de linha de comando se necessário
    },
    {
      "name": "Mono Launch",
      "type": "mono",
      "request": "launch",
      "preLaunchTask": "build-mono",
      "program": "${workspaceFolder}/YourProgram.exe", // ← Edite este caminho
      "cwd": "${workspaceFolder}"
    }
  ]
}

Equivalentes na CLI

# .NET Core
$ dotnet build
$ dotnet run

# Mono / .NET Framework
$ mcs Program.cs
$ mono Program.exe

Limitações do .NET Framework

⚠️ Importante: Codebases em .NET Framework com assemblies mistos (C++/CLI) ou dependências complexas do Visual Studio têm limitações significativas no Windsurf. Essas codebases normalmente exigem o sistema de build proprietário do Visual Studio e não podem ser totalmente compiladas ou depuradas no Windsurf devido a dependências em ferramentas específicas da Microsoft e à resolução de referências de assemblies. Abordagens recomendadas para projetos .NET Framework:
  • Use o Windsurf em conjunto com o Visual Studio para geração e edição de código
  • Migre partes compatíveis para o .NET Core sempre que possível

2. Desenvolvimento em C / C++

Extensões necessárias:
ExtensãoFinalidade
Windsurf C++ Tools (Codeium.windsurf-cpptools)Conjunto com as três extensões que recomendamos para começar. Pacote que inclui suporte LSP para C/C++, depuração e CMake.
Observação: Ao instalar o pacote Windsurf C++ Tools, as extensões individuais abaixo serão instaladas automaticamente; portanto, basta instalar o pacote.
ExtensãoFinalidade
clangd (llvm-vs-code-extensions.vscode-clangd)Integração com o servidor de linguagem clangd. Se clangd não estiver instalado, será oferecido o download do binário correto para sua plataforma.
CodeLLDB (vadimcn.vscode-lldb)Depurador nativo baseado em LLDB para código C/C++ e Rust.
CMake Tools (ms-vscode.cmake-tools)Integração de configuração de projeto, compilação, testes e depuração para projetos baseados em CMake.
Para fluxos de trabalho sem CMake, você ainda pode chamar make, ninja, etc. por meio de alvos personalizados em tasks.json.

Configurar tarefas de build de C/C++

Crie/edite .vscode/tasks.json para o seu projeto em C/C++:
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build-cpp",
      "type": "shell",
      "command": "clang++",
      "args": ["-g", "main.cpp", "-o", "main"], // ← Edite para os seus arquivos
      "group": "build",
      "problemMatcher": "$gcc"
    }
  ]
}

3. Observações e cuidados

  • Somente open‑source – recuse qualquer solicitação para instalar ferramentas proprietárias da Microsoft; os contêineres do Windsurf não podem incluí‑las.
  • Contêiner vs host – SDKs/compiladores devem estar presentes dentro do contêiner de workspace do Windsurf.
  • Atalhos de teclado
    • Ctrl/⌘ + Shift + B → compilar usando a tarefa de build ativa
    • F5 → depurar usando a configuração launch.json selecionada

4. Lista de verificação de configuração

  • Instale as extensões necessárias para sua stack de linguagem
  • Crie e personalize .vscode/tasks.json com os comandos de build do seu projeto
  • Crie e personalize .vscode/launch.json com os caminhos corretos para seus executáveis
  • Para Mono: instale o runtime e verifique mono --version
  • Atualize caminhos de arquivos, nomes de projeto e argumentos de build para corresponder ao seu codebase
  • Teste sua configuração: pressione Ctrl/⌘ + Shift + B para compilar e depois F5 para depurar
💡 Dica: Os arquivos de configuração são específicos do projeto. Você precisará adaptar os exemplos acima para cada workspace.