Installation and Setup

Start by finding the latest release to get all the necessary files.

Install the Language Server

Parsing, source generation, and syntax highlighting are performed by a service which runs on the local machine. This language server runs outside of Visual Studio and accepts commands via the loopback network interface to analyze and compile sources.

1. If you have previously installed the server, uninstall the old version.
   a. Search for "Add or remove programs" in the Start menu.
   b. Find and uninstall "SourceGenerator.Installer" from the list.

2. Download the language server installer (.msi) or binaries (.zip).
   a. If you opt for the installer, run and complete the installation process.
   b. If you opt for the binaries, extract the files to a convenient location.

3. Keep the language server running any time Visual Studio is open.

Note: Running Visual Studio while the language server is not active will result in timeout-related compilation errors and frozen editor screens within Visual Studio. Solutions which do not involve .view or .model files are unaffected.

Install the Syntax Highlighting Extension

To increase readability and semantic significance of code structure, this extension translates classified spans of source text for display in Visual Studio.

Source is submitted to the language server for classification within the language's parser.

4. If you have previously installed the extension, uninstall the old version.
   a. In Visual Studio, open "Extensions -> Manage Extensions..."
   b. Select "Installed."
   c. Find and uninstall "SourceGenerator.VsEditor" from the list.

5. Download and install the latest .vsix.

Project Setup Without a Template

If attempting to attach an existing project to the generator, or create a new generated project in an existing Solution, ensure the source analyzer and .Includes DLLs are present in the project config.

These instructions are for Class Libraries and expect .NET 8. Later .NET versions should work just fine, assuming DI interfaces remain the same.

6. If there isn't already a project, Create a new .NET Class Library for generated content.

7. Create a folder within that project named .\Tools\SourceGenerator.VsAdapter\.
   a. Extract the latest .VsAdapter.zip into the folder.

8. Create another folder named .\Tools\SourceGenerator.Includes\.
   a Download and place the latest .Includes.dll into the folder.

9. In Visual Studio, right click on the Project and click "Edit Project File."
   a. Replace the <Project> node with <Project Sdk="Microsoft.NET.Sdk">.
   b. In <PropertyGroup>, add <Nullable>disable</Nullable>.
   c. Create the following nodes inside of <Project>:

<ItemGroup>
  <AdditionalFiles Include="**\*.model" />
  <AdditionalFiles Include="**\*.view" />
</ItemGroup>

<ItemGroup>
  <Analyzer Include="Tools\SourceGenerator.VsAdapter\SourceGenerator.VsAdapter.dll" />
</ItemGroup>

<ItemGroup>
  <PackageReference Include="Asp.Versioning.Mvc" Version="8.1.0" PrivateAssets="all" />
  <PackageReference Include="Asp.Versioning.Mvc.ApiExplorer" Version="8.1.0" PrivateAssets="all" />
</ItemGroup>

<ItemGroup>
  <PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="8.0.0" />
</ItemGroup>

<ItemGroup>
  <Reference Include="SourceGenerator.Includes">
    <HintPath>Tools\SourceGenerator.Includes\SourceGenerator.Includes.dll</HintPath>
  </Reference>
</ItemGroup>

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

<ItemGroup>
  <FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>

Now any .model or .view files in the project will be compiled, and the generated sources can be used by other projects in the Solution.

Model Adapter Interfaces

Projects Which Reference .Includes