Connecting to Roslyn

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

Once you have Roslyn added, you 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:

  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 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" />
</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
  3. 3

    Configure Roslyn Service

    Update Program.cs to include Roslyn configuration. Chain the Roslyn service configuration to your current AddContentEngineService call:

    // Add Roslyn service for code syntax highlighting and documentation
builder.Services.AddContentEngineService(_ => new ContentEngineOptions
    {
        // existing site config
    })
    .WithConnectedRoslynSolution(_ => new CodeAnalysisOptions()
    {
        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
---

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.ContentEngineExtensions.AddContentEngineService(Microsoft.Extensions.DependencyInjection.IServiceCollection,System.Func{System.IServiceProvider,MyLittleContentEngine.ContentEngineOptions})
```
### 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.ContentEngineExtensions.AddContentEngineService(Microsoft.Extensions.DependencyInjection.IServiceCollection,System.Func{System.IServiceProvider,MyLittleContentEngine.ContentEngineOptions})
```

    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 using XML documentation ID syntax.

    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. 5

    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 can be resource-intensive for large solutions
  • Test regularly - Ensure your content updates correctly when code changes
Previous
Next