.NET: Fixing issue with invalid node Ids when visualizing dotnet workflows. by alliscode · Pull Request #4269 · microsoft/agent-framework

alliscode · 2026-02-25T19:06:27Z

This pull request improves the generation of Mermaid diagrams for workflows by ensuring node identifiers are always safe for Mermaid syntax, even when workflow executor IDs contain spaces, special characters, or non-ASCII characters. It introduces a new sanitization method for node IDs, updates the diagram generation logic to use these sanitized aliases, and significantly expands unit tests to cover these cases and verify Mermaid compatibility.

Key changes include:

Mermaid Node ID Safety and Generation:

Added the SanitizeMermaidNodeId method to convert raw workflow node IDs into Mermaid-safe ASCII-only aliases, handling spaces, special characters, and non-ASCII text, and guaranteeing uniqueness with suffixes if needed. (dotnet/src/Microsoft.Agents.AI.Workflows/Visualization/WorkflowVisualizer.cs)
Updated all Mermaid diagram generation logic to use these sanitized node IDs instead of raw IDs, ensuring that all nodes and edges in the output are Mermaid-compliant. (dotnet/src/Microsoft.Agents.AI.Workflows/Visualization/WorkflowVisualizer.cs) [1] [2] [3] [4]

Unit Test Improvements:

Expanded and updated unit tests to verify that Mermaid diagrams contain only safe node IDs, check for correct edge syntax (especially for conditional/dotted edges), and ensure display labels remain readable. Tests now specifically cover edge cases such as IDs with spaces, pipes, newlines, and Unicode characters. (dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/WorkflowVisualizerTests.cs) [1] [2] [3] [4] [5] [6]

Bug Fixes (Mermaid Syntax Compliance):

Fixed conditional edge rendering to use the correct Mermaid syntax (-. label .-> instead of the invalid .-->). (dotnet/src/Microsoft.Agents.AI.Workflows/Visualization/WorkflowVisualizer.cs, dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/WorkflowVisualizerTests.cs) [1] [2] [3] [4]

Display Label Handling:

Ensured that display labels for nodes are always preserved in quotes, even when the underlying node IDs are sanitized, so the diagrams remain human-readable. (dotnet/src/Microsoft.Agents.AI.Workflows/Visualization/WorkflowVisualizer.cs, dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/WorkflowVisualizerTests.cs) [1] [2]

Regression and Issue Coverage:

Added targeted tests for issues reported in .NET: Rendering errors occur in the output of the WorkflowVisualizer.ToMermaidString method. #1406, covering both Mermaid syntax for conditional edges and node ID safety with spaces and Unicode. (dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/WorkflowVisualizerTests.cs)

These changes together make Mermaid diagram output robust and compatible in all cases, preventing rendering errors due to problematic node identifiers or edge syntax.

Closes #1406

The code builds clean without any errors or warnings
The PR follows the Contribution Guidelines
All unit tests pass, and I have added new tests where possible
Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

Fix two bugs in the Mermaid diagram output: 1. Use safe node aliases (node_0, node_1, ...) instead of raw executor IDs as Mermaid node identifiers. Raw IDs containing spaces, dots, or non-ASCII characters (e.g. Japanese) caused Mermaid parse errors. 2. Fix conditional edge arrow syntax from '.--> ' (invalid) to '.-> ' (valid Mermaid dotted arrow syntax). Fixes microsoft#1406 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…e generic node_0/node_1 aliases with IDs derived from the original\nexecutor names. ASCII letters, digits, and underscores are preserved;\nother characters become underscores (collapsed, trimmed). Leading digits\nget an n_ prefix. Collisions are resolved with a numeric suffix.\n\nThis keeps node IDs readable in the Mermaid source while the display\nlabels continue to show the full original names."

Copilot

Pull request overview

This pull request fixes issue #1406 by improving the robustness of Mermaid diagram generation for workflows. The PR addresses two critical problems: (1) node identifiers containing spaces, special characters, or Unicode causing Mermaid rendering errors, and (2) incorrect conditional edge syntax using .--> instead of the valid ..-> format.

Changes:

Introduced node ID sanitization logic that converts problematic identifiers into Mermaid-safe ASCII aliases while preserving original names in display labels
Fixed conditional edge rendering to use correct Mermaid syntax (-. label .-> instead of -. label .-->)
Added comprehensive unit tests covering edge cases including spaces, Unicode characters, and special characters in node IDs

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
dotnet/src/Microsoft.Agents.AI.Workflows/Visualization/WorkflowVisualizer.cs	Added SanitizeMermaidNodeId method and GetSafeId local function to generate Mermaid-safe node aliases with collision handling; updated edge rendering to use correct conditional arrow syntax
dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/WorkflowVisualizerTests.cs	Expanded test coverage with new tests for issue #1406 scenarios (spaces, Unicode, conditional syntax); updated existing tests to validate sanitized node IDs and display labels

dotnet/src/Microsoft.Agents.AI.Workflows/Visualization/WorkflowVisualizer.cs

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/WorkflowVisualizerTests.cs

dotnet/src/Microsoft.Agents.AI.Workflows/Visualization/WorkflowVisualizer.cs

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/WorkflowVisualizerTests.cs

…rd to SanitizeMermaidNodeId\n- Add safety limit (10,000) to collision resolution loop\n- Restore missing edge assertions (middle1/middle2 --> end)\n- Fix comment to show actual sanitized ID (n_1_User_input)\n- Use stricter regex in Unicode test (must start with letter/underscore)"

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

dotnet/src/Microsoft.Agents.AI.Workflows/Visualization/WorkflowVisualizer.cs

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/WorkflowVisualizerTests.cs

…abels via EscapeMermaidLabel to handle quotes,\n brackets, and newlines in executor IDs\n- Fix XML doc on SanitizeMermaidNodeId to accurately describe that\n existing consecutive underscores in input are preserved\n- Restore specific edge assertion (mid --> end) in conditional edge test\n- Restore fan-in routing assertions (s1/s2 through intermediate node,\n no direct edges to t) in fan-in test"

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/WorkflowVisualizerTests.cs

alliscode and others added 2 commits February 25, 2026 09:05

Copilot AI review requested due to automatic review settings February 25, 2026 19:06

markwallace-microsoft added .NET workflows Related to Workflows in agent-framework labels Feb 25, 2026

alliscode had a problem deploying to integration February 25, 2026 19:07 — with GitHub Actions Error

Remove issue number references from test names and comments"

d73fd3e

Copilot started reviewing on behalf of alliscode February 25, 2026 19:07 View session

github-actions bot changed the title ~~Fixing issue with invalid node Ids when visualizing dotnet workflows.~~ .NET: Fixing issue with invalid node Ids when visualizing dotnet workflows. Feb 25, 2026

alliscode temporarily deployed to integration February 25, 2026 19:10 — with GitHub Actions Inactive

alliscode had a problem deploying to integration February 25, 2026 19:10 — with GitHub Actions Error

Copilot AI reviewed Feb 25, 2026

View reviewed changes

alliscode requested a review from Copilot February 25, 2026 19:23

alliscode temporarily deployed to integration February 25, 2026 19:23 — with GitHub Actions Inactive

Copilot started reviewing on behalf of alliscode February 25, 2026 19:24 View session

Copilot AI reviewed Feb 25, 2026

View reviewed changes

alliscode temporarily deployed to integration February 25, 2026 19:54 — with GitHub Actions Inactive

alliscode requested a review from Copilot February 25, 2026 19:54

Copilot started reviewing on behalf of alliscode February 25, 2026 19:55 View session

Copilot AI reviewed Feb 25, 2026

View reviewed changes

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/WorkflowVisualizerTests.cs Show resolved Hide resolved

alliscode enabled auto-merge February 25, 2026 20:35

TaoChenOSU approved these changes Feb 25, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

.NET: Fixing issue with invalid node Ids when visualizing dotnet workflows.#4269

.NET: Fixing issue with invalid node Ids when visualizing dotnet workflows.#4269
alliscode wants to merge 5 commits intomicrosoft:mainfrom
alliscode:investigation/issue-1406-1772038360

alliscode commented Feb 25, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

alliscode commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

alliscode commented Feb 25, 2026 •

edited

Loading