component-development

Component Development Skill

This skill covers creating new Blazor components that emulate ASP.NET Web Forms controls.

Related Guides

• [HTML Output Matching Guide](HTML_OUTPUT_MATCHING.md) - How to ensure Blazor components render identical HTML to Web Forms controls

Quick Reference

Creating a New Component

1. Identify the Web Forms control from System.Web.UI.WebControls
2. Research the HTML output using the [HTML Output Matching Guide](HTML_OUTPUT_MATCHING.md)
3. Create component files:
4. src/BlazorWebFormsComponents/{ComponentName}.razor
5. src/BlazorWebFormsComponents/{ComponentName}.razor.cs
6. Inherit from appropriate base class:
7. BaseWebFormsComponent - Basic components
8. BaseStyledComponent - Components with styling
9. DataBoundComponent<T> - Data-bound components
10. Add unit tests in src/BlazorWebFormsComponents.Test/{ComponentName}/
11. Add sample page in samples/AfterBlazorServerSide/Components/Pages/ControlSamples/{ComponentName}/
12. Add integration tests using Playwright in samples/AfterBlazorServerSide.Tests/
13. Create documentation in docs/{Category}/{ComponentName}.md
14. Update navigation:
15. Add to samples/AfterBlazorServerSide/Components/Layout/NavMenu.razor (TreeView)
16. Add to samples/AfterBlazorServerSide/Components/Pages/ComponentList.razor (home page catalog)
17. Update mkdocs.yml and README.md

Base Class Selection

| Base Class | Use When | |------------|----------| | BaseWebFormsComponent | Simple components without styling (Literal, PlaceHolder) | | BaseStyledComponent | Components with visual styling (Label, Panel, Button) | | ButtonBaseComponent | Button-like components (Button, LinkButton, ImageButton) | | DataBoundComponent<T> | Components binding to collections (Repeater, GridView) | | BaseValidator | Validation controls |

Property Naming Convention

Match Web Forms property names exactly:

• Text not Label or Content
• CssClass not Class or ClassName
• NavigateUrl not Href or Url
• ImageUrl not Src or Source

Event Naming Convention

Prefix with On:

• OnClick for click events
• OnCommand for command events
• OnSelectedIndexChanged for selection changes
• OnDataBinding for data binding events

Integration Testing Requirements

Every component must have integration tests in samples/AfterBlazorServerSide.Tests/ using Playwright:

1. Page load test in ControlSampleTests.cs:
2. Add route to the appropriate [Theory] test (EditorControl, DataControl, etc.)
3. Verifies page loads without console errors or page errors

1. Interactive test in InteractiveComponentTests.cs (for interactive components):
2. Test user interactions (clicks, input, selection changes)
3. Verify component responds correctly to user actions
4. Assert no console errors during interaction

Example page load test entry:

[Theory]
[InlineData("/ControlSamples/YourComponent")]
public async Task EditorControl_Loads_WithoutErrors(string path)

Example interactive test:

[Fact]
public async Task YourComponent_Interaction_Works()
{
    var page = await _fixture.NewPageAsync();
    try
    {
        await page.GotoAsync($"{_fixture.BaseUrl}/ControlSamples/YourComponent");
        // Test interactions...
        // Assert expected behavior...
    }
    finally
    {
        await page.CloseAsync();
    }
}

Run integration tests with:

dotnet test samples/AfterBlazorServerSide.Tests