Connecting to Roslyn

Because MyLittleContentEngine is a .NET application itself, you can integrate it with Roslyn. By adding the Roslyn service, we will use Roslyn to provide enhanced code syntax highlighting and access our application's code directly for documentation.

Most documentation sites include code highlighting that relies on regular expressions or textmate files. These methods can be limited in their capabilities, or they may not support all the features of C#, especially if you are targeting newer versions of C#.

By using Roslyn, you can ensure that if your code is compiling and running, the syntax highlighting will be accurate and up to date because it uses the same tools to highlight are used to compile your code.

Once we have Roslyn added, we can also attach a solution file to the Roslyn Service. This allows you to use your application's demos and unit tests as documentation, ensuring that your content is always up to date with the latest syntax. No longer do you need to copy and paste code snippets into your documentation, instead, you can reference your code directly in your code blocks. Changes to your sample apps will be directly displayed.

In this tutorial, you'll learn how to integrate Roslyn with MyLittleContentEngine to enable enhanced code syntax highlighting and automatic documentation generation from your .NET solution.

What You'll Learn

By the end of this tutorial, you'll be able to:

  • Connect MyLittleContentEngine to a .NET solution using Roslyn
  • Use XML documentation ID syntax to reference code elements
  • Configure file watching for source code changes
  • Create content that automatically updates when your code changes

Prerequisites

Before starting, ensure you have:

  • Completed the Creating Your First Site tutorial
  • A .NET solution with XML documentation comments
  • Familiarity with XML documentation ID syntax
  1. 1

    Start with a Basic Site

    We'll start by copying the MinimalExample to create a new site with Roslyn integration. If you don't have the MinimalExample, follow the Creating Your First Site tutorial first.

  2. 2

    Watch Source Code Changes

    We need to tell dotnet watch to watch our solution for changes. Any files included via the Watch item group in the .csproj file will be monitored for changes, triggering a refresh of the site.

    Update the .csproj file to include source code watching while excluding build artifacts:

    <ItemGroup>
    <Watch Include="Content\**\*.*"/>
    <Watch Include="..\..\src\**\*.cs" Exclude="..\..\src\*\bin\**\*.*;..\..\src\*\obj\**\*.*"/>
</ItemGroup>

    The source path is relative to the host application root, not solution root. Adjust the path based on your project structure.

    This configuration ensures that:

    • Content files are watched for changes (as before)
    • Source code files are watched for changes
    • Build artifacts in bin and obj folders are excluded to prevent unnecessary rebuilds. This is important as we will be building at runtime for certain actions, and we don't want to cause an unneeded refresh.
  3. 3

    Configure Roslyn Service

    Update Program.cs to include Roslyn configuration. Add the required using statement:

    using MyLittleContentEngine.Services.Content.Roslyn;

    Then add the Roslyn service configuration before var app = builder.Build();:

    // Add Roslyn service for code syntax highlighting and documentation
builder.Services.AddRoslynService(_ => new RoslynHighlighterOptions()
{
    ConnectedSolution = new ConnectedDotNetSolution()
    {
        SolutionPath = "../../{path-to-your-solution}.sln",
    }
});

    The SolutionPath should point to your .NET solution file. This is relative to the host application root. Adjust the path based on your project structure.

  4. 4

    Create Content with XML Documentation ID Syntax

    Create a new content file Content/roslyn-integration-demo.md to demonstrate the Roslyn features:

    ---
title: "Roslyn Integration Demo"
description: "Demonstrating code highlighting and documentation with Roslyn integration"
date: 2025-01-15
tags:
  - roslyn
  - code
  - documentation
isDraft: false
---

# Roslyn Integration Demo

This page demonstrates how MyLittleContentEngine integrates with Roslyn to provide enhanced code highlighting and documentation features.

## Code Highlighting

When Roslyn is connected, code blocks get enhanced syntax highlighting:

```csharp
string json = $$"""{"name": "John", "quote": "He said \"Hello!\"", "value": {{DateTime.Now.Year}}}""";
string pattern = """["\$]+""";
var (isValid, _) = ValidateJson(json);
using var stream = new MemoryStream();
Collection<string> items = ["item1", "item2"];
```

## XML Documentation ID Syntax

You can reference specific classes, methods, and properties from your solution using the `xmldocid` syntax:

### Referencing Classes

Reference the main content engine options class:

```csharp:xmldocid
T:MyLittleContentEngine.ContentEngineOptions
```

### Referencing Methods

Reference a specific method from the content service:

```csharp:xmldocid
M:MyLittleContentEngine.Services.Content.MarkdownContentService.GetAllContentPagesAsync
```

### Excluding Declarations Syntax

You can also exclude declarations from the documentation by using the `xmldocid` syntax with the `bodyonly` keyword:

```csharp:xmldocid,bodyonly
M:MyLittleContentEngine.Services.Content.MarkdownContentService.GetAllContentPagesAsync
```

    The key feature here is the XML documentation ID syntax in code blocks:

    ```csharp:xmldocid
T:MyLittleContentEngine.ContentEngineOptions
```

    This syntax allows you to reference specific code elements:

    • T: for types/classes
    • M: for methods

    bodyonly can be added to xmldocid for scenarios where you only want the body of the method or type without the declaration. This can be useful for showing just the implementation details without the full signature.

  5. 6

    Test the Integration

    Run your site in development mode:

    dotnet watch

    Navigate to your site and visit the Roslyn integration demo page. You should see:

    1. Enhanced syntax highlighting - Code blocks get proper colorization
    2. Automatic documentation - XML doc comments are rendered with the code
    3. Live updates - Changes to your source code are reflected immediately

    While the site is running, try:

    • Adding new public methods or properties
    • Updating the code examples in your content

    The changes should be reflected automatically without restarting the server.

Best Practices

When using Roslyn integration:

  • Use meaningful examples - Reference code that's relevant to your content
  • Watch performance - Roslyn analysis is going to be resource-intensive for large solutions
  • Test regularly - Ensure your content updates correctly when code changes
Previous
Next