Skip to content

AGENTS.md

Latest commit

 

History

History
213 lines (151 loc) · 6.07 KB

AGENTS.md

File metadata and controls

213 lines (151 loc) · 6.07 KB
Raw

AGENTS.md

This file provides context and instructions for AI coding agents working on the Microsoft Fluent UI Blazor components library.

Project Overview

This is a .NET Blazor component library that provides Fluent UI design system components for Blazor applications. The library wraps Microsoft's official Fluent UI Web Components and provides additional components leveraging the Fluent Design System.

  • Main Package: Microsoft.FluentUI.AspNetCore.Components
  • Target Framework: .NET 8+
  • License: MIT
  • Language: C# with Razor components
  • Documentation: https://www.fluentui-blazor.net

Repository Structure

src/
├── Core/                           # Main component library
├── Core.Scripts/                   # TypeScript/JavaScript for web components
└── Extensions/                     # Additional packages (EF adapter, OData, etc.)

tests/
├── Core/                           # Unit tests (bUnit)
└── Integration/                    # Integration tests

examples/
├── Demo/                           # Demo application
└── Samples/                        # Sample projects

Setup Commands

Prerequisites

  • .NET 8 SDK or later
  • Node.js 22.x (for Core.Scripts project)
  • Visual Studio 2026 (recommended on Windows)

Build Commands

# Build the entire solution
dotnet build Microsoft.FluentUI-v5.slnx

# Build only the core component library
dotnet build src/Core/Microsoft.FluentUI.AspNetCore.Components.csproj

# Build the demo application
dotnet build examples/Demo/FluentUI.Demo/FluentUI.Demo.csproj

# Clean the solution
dotnet clean Microsoft.FluentUI-v5.slnx

# Restore packages
dotnet restore Microsoft.FluentUI-v5.slnx

Run the Demo

# Run demo application
dotnet run --project examples/Demo/FluentUI.Demo/FluentUI.Demo.csproj

# Watch mode (hot reload)
dotnet watch run --project examples/Demo/FluentUI.Demo/FluentUI.Demo.csproj

Testing Instructions

Running Tests

# Run all unit tests
dotnet test tests/Core/Components.Tests.csproj

# Run specific test
dotnet test tests/Core/Components.Tests.csproj --filter "FullyQualifiedName~TestClassName"

Unit Test Guidelines

  • Tests use bUnit for Blazor component testing
  • Tests use Verify for snapshot testing
  • Test file naming: {ComponentName}Tests.cs
  • Test method naming: {MethodName}_{Scenario}_{ExpectedBehavior}
  • Always add or update tests when modifying components
  • Run all tests before submitting a PR

Test File Location

Unit tests are in tests/Core/Components/ mirroring the component structure in src/Core/Components/.

Code Style Guidelines

C# Conventions

  • Nullable: Enabled (<Nullable>enable</Nullable>)
  • Warnings as Errors: Enabled (<TreatWarningsAsErrors>true</TreatWarningsAsErrors>)
  • Code Style: Enforced in build (<EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>)
  • Use C# latest language features
  • Follow Microsoft C# coding conventions

Component Development

  • Components are in src/Core/Components/
  • Each component should have its own folder
  • Include: .razor file, .razor.cs code-behind (if needed), .razor.css styles (if needed)
  • Expose design tokens for customization
  • Ensure accessibility compliance

Razor Component Pattern

// Example component structure
public partial class FluentComponentName : FluentComponentBase
{
    [Parameter]
    public string? Property { get; set; }

    [Parameter]
    public EventCallback<T> OnEvent { get; set; }
}

PR Guidelines

Before Submitting

  1. Rebase your branch from the target branch (do NOT use git merge)
  2. Run all unit tests: dotnet test tests/Core/Components.Tests.csproj
  3. Ensure the build passes: dotnet build Microsoft.FluentUI-v5.sln
  4. Update documentation if needed

Commit Messages

Follow Conventional Commits:

  • feat: - New feature
  • fix: - Bug fix
  • docs: - Documentation changes
  • chore: - Maintenance tasks
  • refactor: - Code refactoring
  • test: - Adding or updating tests

PR Checklist

  • Tests added/updated for changes
  • Changes have been tested locally
  • Documentation updated if needed
  • Follows project coding standards

NPM/JavaScript Setup (Core.Scripts)

If you encounter NPM authentication issues (E401):

cd src/Core.Scripts

# Install vsts-npm-auth
npm install -g vsts-npm-auth --registry https://registry.npmjs.com --always-auth false

# Get authentication token
vsts-npm-auth -config .npmrc -force

# Install packages
npm install

Important Files

  • Directory.Build.props - Central versioning and build configuration
  • Directory.Packages.props - Central package version management
  • .github/CODEOWNERS - Code ownership (@vnbaaij @dvoituron)
  • docs/contributing.md - Contribution guidelines
  • docs/unit-tests.md - Detailed unit testing documentation

Security Considerations

  • Do not commit sensitive data or credentials
  • Review the SECURITY.md file for security policies
  • Report security vulnerabilities through proper channels (not public issues)

Contributing Workflow

This repository uses a fork-based contribution model:

  1. Fork the repository from microsoft/fluentui-blazor
  2. Clone your fork locally
  3. Create a feature branch from the target branch (dev)
  4. Make changes and commit following conventional commit guidelines
  5. Push to your fork
  6. Create a Pull Request targeting the upstream repository microsoft/fluentui-blazor

Remote Configuration

# Add upstream remote (if not already configured)
git remote add upstream https://github.com/microsoft/fluentui-blazor.git

# Fetch upstream changes
git fetch upstream

# Rebase your branch on upstream
git rebase upstream/dev

Additional Resources