|
| 1 | +# .NET Project System for Visual Studio |
| 2 | + |
| 3 | +The .NET Project System for Visual Studio is a Windows-based Visual Studio extension project built with C#, VB.NET, MSBuild, and the Common Project System (CPS) framework. This supports SDK-style .NET (C#, F#, and Visual Basic) and Shared Projects project types. |
| 4 | + |
| 5 | +Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here. |
| 6 | + |
| 7 | +## Working Effectively |
| 8 | + |
| 9 | +### Prerequisites - CRITICAL |
| 10 | +- **WINDOWS ONLY**: This repository requires Windows and Visual Studio. Build WILL FAIL on Linux/macOS. |
| 11 | +- Install [Visual Studio 2022](https://visualstudio.microsoft.com/downloads/) with these workloads: |
| 12 | + - .NET desktop build tools |
| 13 | + - Visual Studio extension development |
| 14 | +- MINIMUM: Visual Studio 16.3 Preview 2 or higher |
| 15 | +- .NET 9.0 SDK (automatically installed with Visual Studio or via [dotnet.microsoft.com](https://dotnet.microsoft.com/download)) |
| 16 | + |
| 17 | +### Build and Test |
| 18 | +- **PRIMARY BUILD COMMAND**: From a Visual Studio Developer Prompt: |
| 19 | + ``` |
| 20 | + build.cmd |
| 21 | + ``` |
| 22 | + - NEVER CANCEL: Build takes 15-45 minutes. Set timeout to 60+ minutes. |
| 23 | + - This builds, runs tests, and deploys to experimental VS instance |
| 24 | + - Creates artifacts in `artifacts/` directory with build logs |
| 25 | + |
| 26 | +- **BUILD OPTIONS**: |
| 27 | + ``` |
| 28 | + build.cmd /p:Test=false # Skip tests (faster build) |
| 29 | + build.cmd /p:SetupProjects=false # Skip VS setup projects |
| 30 | + build.cmd /p:SrcProjects=true /p:TestProjects=false # Source only |
| 31 | + ``` |
| 32 | + |
| 33 | +- **RUN TESTS**: Tests are included in default build. To run separately: |
| 34 | + - Tests execute automatically during `build.cmd` |
| 35 | + - NEVER CANCEL: Test suite takes 10-30 minutes. Set timeout to 45+ minutes. |
| 36 | + - Uses xUnit framework |
| 37 | + - Results appear in artifacts directory |
| 38 | + |
| 39 | +### Visual Studio Development |
| 40 | +- **OPEN SOLUTION**: Open `ProjectSystem.sln` in Visual Studio 2022 |
| 41 | +- **F5 DEBUGGING**: Press F5 to launch experimental VS instance with your changes |
| 42 | +- **FIRST LAUNCH**: Use Ctrl+F5 for first launch to pre-prime and avoid long startup time |
| 43 | +- **BUILD IN VS**: Use Build menu or Ctrl+Shift+B |
| 44 | + |
| 45 | +### Launch and Test Your Changes |
| 46 | +- **COMMAND LINE**: After `build.cmd` completes: |
| 47 | + ``` |
| 48 | + Launch.cmd |
| 49 | + ``` |
| 50 | + - Launches Visual Studio experimental instance with your built bits |
| 51 | + - Default hive is 'Exp' - change with `/rootsuffix` parameter |
| 52 | + |
| 53 | +- **DIFFERENT HIVE**: |
| 54 | + ``` |
| 55 | + set ROOTSUFFIX=RoslynDev |
| 56 | + build.cmd |
| 57 | + Launch.cmd /rootsuffix RoslynDev |
| 58 | + ``` |
| 59 | + |
| 60 | +## Validation |
| 61 | +- **ALWAYS** build and test with `build.cmd` before committing changes |
| 62 | +- **MANUAL TESTING**: Create test projects in the experimental VS instance: |
| 63 | + 1. File → New → Project → C#/VB.NET → Console App (.NET) |
| 64 | + 2. Add/remove references and packages |
| 65 | + 3. Build and run the test project |
| 66 | + 4. Verify project properties work correctly |
| 67 | +- The repository includes both unit tests and integration tests |
| 68 | +- Integration tests require Visual Studio experimental instance |
| 69 | + |
| 70 | +## Repository Structure |
| 71 | + |
| 72 | +### Key Directories |
| 73 | +- `src/Microsoft.VisualStudio.ProjectSystem.Managed/` - Core project system (C#) |
| 74 | +- `src/Microsoft.VisualStudio.ProjectSystem.Managed.VS/` - VS integration layer (C#) |
| 75 | +- `src/Microsoft.VisualStudio.Editors/` - Property pages and designers (VB.NET) |
| 76 | +- `src/Microsoft.VisualStudio.AppDesigner/` - Application designer (VB.NET) |
| 77 | +- `tests/` - Unit tests and integration tests |
| 78 | +- `setup/` - Visual Studio deployment packages (VSIX) |
| 79 | +- `eng/` - Build pipelines and tooling |
| 80 | +- `docs/` - Documentation including architecture guides |
| 81 | + |
| 82 | +### Key Files |
| 83 | +- `ProjectSystem.sln` - Main solution file |
| 84 | +- `build.cmd` - Primary build script (Windows batch file) |
| 85 | +- `Launch.cmd` - Launches experimental VS instance |
| 86 | +- `Directory.Build.props` - MSBuild properties (NetCoreTargetFramework=net9.0) |
| 87 | + |
| 88 | +## Common Issues and Solutions |
| 89 | +- **Build fails with package restore errors**: Requires access to internal Azure DevOps feeds - build from Visual Studio Developer Prompt |
| 90 | +- **"Visual Studio must be installed"**: Ensure Visual Studio with correct workloads is installed |
| 91 | +- **Long build times**: Normal - initial builds take 15-45 minutes, incremental builds are faster |
| 92 | +- **Experimental VS won't start**: Run `Launch.cmd` from same prompt where you ran `build.cmd` |
| 93 | + |
| 94 | +## Architecture Overview |
| 95 | +- Built on [Common Project System (CPS)](https://github.com/microsoft/VSProjectSystem) framework |
| 96 | +- Multi-threaded, MEF-based extensible architecture |
| 97 | +- Supports .NET SDK-style projects (C#, F#, VB.NET) |
| 98 | +- Integrates with MSBuild, Roslyn, and Visual Studio APIs |
| 99 | +- Replaces legacy csproj.dll/msvbproj.dll project systems |
| 100 | + |
| 101 | +## DO NOT attempt to: |
| 102 | +- Build on Linux or macOS (Windows/VS only) |
| 103 | +- Use `dotnet build` directly (requires Visual Studio MSBuild) |
| 104 | +- Skip the Visual Studio Developer Prompt requirement |
| 105 | +- Cancel long-running builds/tests (they may take 45+ minutes) |
| 106 | + |
| 107 | +Always validate changes by launching the experimental VS instance and creating/testing real projects. |
0 commit comments