Build an AI-Powered Developer Portal with Backstage and .NET

Want to apply AI, not just read about it? Most tutorials stop at a "Hello World" chatbot. We are going to build something that actually solves a common engineering headache: stale documentation.

Who this is for

This guide is for platform engineers and .NET developers who need to organize a growing software landscape without forcing teams to manually write YAML files.

What you will build

You will build a dynamic developer portal using ) to generate summaries.

• 
  Source repo: with all
  
  the code ready to run!
  
  
  
  

  
  
  
  Prerequisites
  

  
  
  

  Before we start, make sure you have the following installed:

  
  
  
  
  
  • (includes npx and yarn)
  
  
  • 
    to get started immediately.
    
    
    

    To clone the demo:
    
    

    
    
    
    
    

    CODE Kopieren

    git clone https://github.com/bgener/demo-backstage-catalog-generator.git
    
    cd demo-backstage-catalog-generator
    
    

    
    
    
    
    
    
    
    

    To build from scratch, start by downloading and running the LLM model we will use in this guide:
    
    

    
    
    
    
    

    CODE Kopieren

    ollama pull llama3:8b
    
    ollama serve
    
    

    
    
    
    
    
    
    
    

    
    

    Tip:
    
    We use llama3:8b specifically. It is significantly faster for local
    
    inference than the full-size model and produces more consistent, concise
    
    output for our use case. If you have a powerful GPU, feel free to use llama3
    
    instead.

    
    

    
    
    

    Next, scaffold the baseline .NET services. We’ll create one Web API and one MVC project:
    
    

    
    
    
    
    

    CODE Kopieren

    mkdir Backstage-Dev-Portal
    
    cd Backstage-Dev-Portal
    
    
    
    dotnet new webapi -n ServiceA
    
    dotnet new mvc -n ServiceB
    
    
    
    dotnet new sln -n Backstage-Dev-Portal
    
    dotnet sln add ServiceA/ServiceA.csproj
    
    dotnet sln add ServiceB/ServiceB.csproj
    
    

    
    
    
    
    
    
    
    

    You can replace the default controllers with real logic later. These raw services represent the uncataloged microservices in your organization.

    
    
    

    
    
    
    Building a Smart Catalog Generator in .NET
    

    
    
    

    We will build a .NET CLI tool using . Here we focus on the key parts.

    
    
    

    First, set up the Ollama client and configure the system prompt. This is the most fragile part of the chain: the system prompt has to force the model into a YAML-safe format without it hallucinating markdown backticks:
    
    

    
    
    
    
    

    CODE Kopieren

    var ollamaApiClient = new OllamaApiClient(
    
        new Uri("http://localhost:11434")) { SelectedModel = "llama3:8b" };
    
    
    
    var chat = new Chat(ollamaApiClient, systemPrompt:
    
        "You are a technical documentation assistant. " +
    
        "You produce concise, YAML-safe summaries of .NET projects. " +
    
        "Output only plain text, no markdown, no bullet points, no quotes, no colons, no newlines.");
    
    

    
    
    
    
    
    
    
    

    Instead of sending every file to the AI, we only send *.csproj, Program.cs, and the folder structure. This is all the context the model needs.

    
    
    

    
    

    Warning:
    
    Prompt sanitization is critical. If your Program.cs contains complex
    
    string literals or nested colons, the AI might pass them through to your YAML,
    
    breaking the Backstage parser. Always sanitize the output before writing the
    
    file.
    
    

    
    

    
    
    
    
    

    CODE Kopieren

    var sb = new StringBuilder();
    
    sb.AppendLine($"Project: {projectName}");
    
    sb.AppendLine("Folder structure:");
    
    AppendFolderStructure(projectDir, sb, "");
    
    sb.AppendLine(File.ReadAllText(csprojPath));
    
    
    
    var programPath = Directory.GetFiles(projectDir, "Program.cs", SearchOption.AllDirectories)
    
        .FirstOrDefault();
    
    if (programPath != null)
    
        sb.AppendLine(File.ReadAllText(programPath));
    
    

    
    
    
    
    
    
    
    

    The prompt itself uses few-shot examples to guide the model toward the output format we want:
    
    

    
    
    
    
    

    CODE Kopieren

    var prompt = "Summarize the project in 1-2 sentences based on the files provided. " +
    
                 "Do not output anything else. " +
    
                 "Examples of good output: " +
    
                 "REST API service providing weather forecasts with temperature data\n" +
    
                 "ASP.NET MVC application with React frontend for managing todo items\n\n"
    
                 + sb.ToString();
    
    
    
    await foreach (var token in chat.SendAsync(prompt, cts.Token))
    
        summaryBuilder.Append(token);
    
    

    
    
    
    
    
    
    
    

    Finally, each summary is sanitized and assembled into a Backstage-compatible YAML entry:
    
    

    
    
    
    
    

    CODE Kopieren

    var summary = summaryBuilder.ToString().Trim()
    
        .Replace("\n", " ").Replace(":", " -").Replace("\"", "'");
    
    
    
    var yamlEntry = $@"
    
    apiVersion: backstage.io/v1alpha1
    
    kind: Component
    
    metadata:
    
      name: {projectName.ToLowerInvariant()}
    
      description: ""{summary}""
    
    spec:
    
      type: service
    
      lifecycle: production
    
      owner: group:default/engineering";
    
    

    
    
    
    
    
    
    
    

    Run the generator against the target directory (use . if you are already in the project root):
    
    

    
    
    
    
    

    CODE Kopieren

    dotnet run --project ProjectSummarizer -- .
    
    

    
    
    
    
    
    
    
    

    You should see the AI streaming its summaries in real time:

    
    
    
    
    

    
    
    
    Deploying the Portal
    

    
    
    

    To host this, build your portal as a static site:
    
    

    
    
    
    
    

    CODE Kopieren

    yarn build:static
    
    

    
    
    
    
    
    
    
    

    Push the output to GitHub and deploy to any static hosting provider: Netlify, Azure Static Web Apps, Vercel, or even self-hosted on Kubernetes. Set the build command to yarn build:static and the publish directory to dist.

    
    
    

    
    

    Info:
    
    A static Backstage build is great for read-only catalogs. If you need dynamic
    
    features like authentication, real-time plugin backends, or write
    
    operations, you will need to deploy the full Backstage backend as a Node.js
    
    service instead.

    
    

    
    
    

    
    
    
    Automating with CI/CD
    

    
    
    

    The real value comes from running the catalog generator automatically. Here is a GitHub Actions workflow that regenerates summaries on every push to main:
    
    

    
    
    
    
    

    CODE Kopieren

    name: Update Backstage Catalog
    
    on:
    
      push:
    
        branches: [main]
    
    
    
    jobs:
    
      generate-catalog:
    
        runs-on: ubuntu-latest
    
        steps:
    
          - uses: actions/checkout@v4
    
    
    
          - name: Setup .NET
    
            uses: actions/setup-dotnet@v4
    
            with:
    
              dotnet-version: ‘8.0.x’
    
    
    
          - name: Install and start Ollama
    
            run: |
    
              curl -fsSL https://ollama.com/install.sh | sh
    
              ollama serve &
    
              sleep 5
    
              ollama pull llama3:8b
    
    
    
          - name: Generate catalog
    
            run: dotnet run --project ProjectSummarizer -- "$GITHUB_WORKSPACE"
    
    
    
          - name: Commit updated catalog
    
            run: |
    
              git config user.name "github-actions"
    
              git config user.email "[email protected]"
    
              git add catalog-info.yaml
    
              git diff --cached --quiet || git commit -m "chore: regenerate AI catalog summaries"
    
              git push
    
    

    
    
    
    
    
    
    
    

    
    

    Warning:
    
    CI Performance: Running Ollama in CI uses CPU-only inference by default. A
    
    llama3:8b summary takes about 20-30 seconds per project on a standard GitHub
    
    runner. For a large monorepo, your CI bill will spike. Consider using a
    
    persistent self-hosted runner with a GPU if you scale this.

    
    

    
    
    

    
    
    
    Final thoughts
    

    
    
    

    The practical rule is simple: automate the metadata generation where the code lives, but keep the UI (Backstage) as a thin, static client. This prevents the "stale documentation" problem without adding a heavy runtime dependency to your production environment.

    
    
    
    
    
    • 
      Use narrow context: Don't send the whole repo to the AI. Files like Program.cs and *.csproj are usually enough.
    
    
    • 
      Sanitize strictly: AI output is non-deterministic. Always strip colons and newlines before writing to YAML.
    
    
    • 
      Start static: A read-only static portal is 10x easier to maintain than a dynamic one.
    
    
    
    
    

    
    
    
    FAQ
    

    
    
    

    Can I use OpenAI instead of Ollama?
    
    Yes, but you will be sending your source code (or at least your Program.cs) to a third party. Use a local model if security is a concern.

    
    
    

    Does this replace README files?
    
    No. It replaces the "Service Directory" that usually lives in a spreadsheet. It points engineers to the README they actually need.

    
    
    

    How do I handle project renames?
    
    The generator uses the folder or .csproj name. If you rename them, Backstage will see it as a new component unless you map the identity stable-ly.

    
    
    
    
    
    

    I help teams build exactly this kind of internal tooling, from developer portals to platform engineering. .

    Vollständiger Original-Bericht

    Ausführliche Details, Code-Beispiele & Hersteller-Stellungnahme auf dev.to.

    ↗ Original-Artikel auf dev.to lesen