Blazor WASM Template

A comprehensive full-stack template for Blazor WebAssembly applications built with .NET 10 (preview), featuring a clean waterfall architecture and modern UI components.

Features

• Modern Stack: Built on .NET 10 (preview) with the latest Blazor WebAssembly
• Clean Architecture: Implements waterfall architecture with clear separation of concerns
• MVVM Pattern: Client-side MVVM design pattern with dependency injection
• Rich UI: Pre-configured with MudBlazor for beautiful, responsive components
• Fast APIs: Powered by FastEndpoints for high-performance API development
• Local Storage: Integrated Blazored LocalStorage for client-side data persistence
• Ready to Use: Comes pre-configured and ready for development

Project Structure

blazor-wasm-template/
├── .github/                # GitHub Actions workflows
│   └── workflows/
│       └── deploy.yaml     # Automated deployment workflow
├── .vscode/                # VS Code configuration
│   ├── launch.json         # Debug configurations
│   ├── settings.json       # Workspace settings
│   └── tasks.json          # Build and run tasks
├── src/                    # Source code directory
│   ├── API/                # Web API layer with FastEndpoints
│   ├── BlazorApp.Client/   # Blazor WebAssembly client application
│   ├── BlazorApp.Shared/   # Shared contracts and DTOs
│   ├── BlazorApp.Utils/    # Shared business logic utilities
│   ├── BLL/                # Business Logic Layer
│   ├── DAL/                # Data Access Layer
│   └── Models/             # Domain models and entities
└── BlazorApp.sln           # Solution file (located in src/)

Architecture Overview

This template implements a waterfall architecture pattern with clear separation of concerns:

• API Layer: Handles HTTP requests and routing using FastEndpoints
• BLL (Business Logic Layer): Contains business rules and application logic
• DAL (Data Access Layer): Manages data persistence and retrieval
• Client Layer: Blazor WebAssembly frontend with MudBlazor components using MVVM pattern
• Shared Layer: Common contracts, DTOs, and utilities used across layers
• Utils Layer: Cross-cutting concerns and shared utilities
• CI/CD: Automated deployment via GitHub Actions and Azure Pipelines
• Development: Enhanced VS Code integration with pre-configured tasks and debugging

Data Flow Architecture

The application follows a structured data flow pattern that ensures clean separation of concerns and maintainable code:

Client-Side Flow (MVVM with DI)

The client uses the Model-View-ViewModel (MVVM) pattern with dependency injection for clean architecture:

1. View (Blazor Component) → ViewModel

@page "/weather"
@inject IWeatherViewModel viewModel

<MudButton OnClick="LoadWeather">Get Today's Weather</MudButton>

@code {
    private async Task LoadWeather()
    {
        TodaysWeatherResponse weatherResponse = await viewModel.GetTodaysWeather();
        // Handle response...
    }
}

2. ViewModel → HTTP Service

public class WeatherViewModel(IHttpService httpService) : IWeatherViewModel
{
    private readonly IHttpService _httpService = httpService;

    public async Task<TodaysWeatherResponse> GetTodaysWeather()
    {
        TodaysWeatherResponse response = await _httpService.Get<TodaysWeatherResponse>("/weather/today");
        return response;
    }
}

Server-Side Flow (API → BLL → DAL)

3. API Endpoint → Business Logic Layer

public class GetTodaysWeather(IWeatherService weatherService) : EndpointWithoutRequest<TodaysWeatherResponse>
{
    private readonly IWeatherService _weatherService = weatherService;

    public override void Configure()
    {
        Get("/weather/today");
        AllowAnonymous();
    }

    public override async Task HandleAsync(CancellationToken ct)
    {
        TodaysWeatherResponse response = await _weatherService.GetTodaysWeather();
        await SendAsync(response, cancellation: ct);
    }
}

4. Business Logic Layer → Data Access Layer

public class WeatherService(IWeatherRepository weatherRepository) : IWeatherService
{
    private readonly IWeatherRepository _weatherRepository = weatherRepository;

    public async Task<TodaysWeatherResponse> GetTodaysWeather()
    {
        WeatherData weatherData = await _weatherRepository.GetCurrentWeatherAsync();
        
        // Apply business logic, transformations, validations
        return new TodaysWeatherResponse
        {
            Temperature = weatherData.Temperature,
            Description = weatherData.Description,
            // ... other mappings
        };
    }
}

5. Data Access Layer → Database/External APIs

public class WeatherRepository : IWeatherRepository
{
    public async Task<WeatherData> GetCurrentWeatherAsync()
    {
        // Fetch from database, external API, or other data source
        // Return raw data model
    }
}

Complete Request Flow

graph TD
    A[Blazor Component] --> B[ViewModel]
    B --> C[HTTP Service]
    C --> D[API Endpoint]
    D --> E[Business Service]
    E --> F[Repository/DAL]
    F --> G[Database/External API]
    
    G --> F
    F --> E
    E --> D
    D --> C
    C --> B
    B --> A

Loading

Flow Summary:

1. View triggers an action and calls the ViewModel
2. ViewModel uses IHttpService to make HTTP requests to the API
3. API Endpoint receives the request and delegates to the Business Logic Layer
4. BLL Service applies business rules and calls the Data Access Layer
5. DAL Repository retrieves/persists data from the database or external services
6. Response flows back up the chain: DAL → BLL → API → Client → ViewModel → View

This architecture ensures:

• Single Responsibility: Each layer has a clear purpose
• Dependency Inversion: Higher layers depend on abstractions, not implementations
• Testability: Each layer can be unit tested independently
• Maintainability: Changes in one layer don't cascade to others
• Scalability: Easy to extend and modify individual components

Getting Started

Prerequisites

• .NET 10 SDK (preview) installed on your machine
• Visual Studio Code with C# Dev Kit extension, or Visual Studio 2026 (Insiders)

Note: This project requires .NET 10 preview and is only supported in VS Code or Visual Studio 2026 (Insiders). Earlier versions of Visual Studio are not supported.

Installation

1. Clone the repository

   git clone https://github.com/deans-bradley/blazor-wasm-template.git
   cd blazor-wasm-template

2. Restore dependencies

   dotnet restore src/

3. Build the solution

   dotnet build src/

Running the Application

The API and client run simultaneously - no need to start them separately.

Using Visual Studio 2026 (Insiders)

• Press F5 to start debugging, or
• Use Ctrl + F5 to run without debugging

Using VS Code

The project includes pre-configured VS Code tasks for easy development:

Tasks

• Build API: Builds the API project

• App (Dev): Builds and runs the app in Development, launches the app in the browser

• In the Run and Debug panel, select App (Dev) in the dropdown.

• Press F5** to start debugging (uses the configured launch profile).

Using Command Line

# From the root directory
dotnet run --project src/API

Once running, navigate to https://localhost:{port} in your browser (the exact port will be displayed in the console).

Deployment

This template includes automated deployment via GitHub Actions:

GitHub Actions Workflow

The project includes a deploy.yaml workflow in .github/workflows/ that provides:

• Automated CI/CD: Builds and deploys your application on code changes
• Multi-environment support: Configure different deployment targets
• Dependency caching: Faster build times with NuGet package caching
• Security: Uses GitHub secrets for secure deployment credentials

To set up deployment:

1. Configure your deployment target (Azure, AWS, etc.) in the deploy.yaml file
2. Add required secrets to your GitHub repository settings
3. Push changes to trigger automatic deployment

Note: Review and customize the deployment workflow according to your hosting requirements.

Recommended VS Code Extensions

For the best development experience, install these extensions:

• C# Dev Kit - Essential C# support and debugging
• C# - Language support for C#

Customization

Updating Template Name

To customize the template for your project:

1. Use your IDE's "Find and Replace in Files" feature
2. Search for BlazorApp throughout the entire solution
3. Replace with your desired project name
4. Update namespaces and assembly names accordingly

Tip: Make sure to update folder names, project files (.csproj), and namespace declarations.

Contributing

I am open to contributions. Please follow these steps:

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/your-feature-name

3. Make your changes and commit

   git commit -m 'Add: your feature description'

4. Push to your branch

   git push origin feature/your-feature-name

5. Open a Pull Request

Please ensure your code follows the existing patterns and includes appropriate tests where applicable.

Technologies Used

• Blazor WebAssembly - Client-side web UI framework
• FastEndpoints - High-performance API framework
• MudBlazor - Material Design component library
• Blazored LocalStorage - Browser local storage wrapper
• .NET 10 (preview) - Latest .NET framework preview

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Special thanks to the creators and maintainers of these excellent frameworks and libraries that make this template possible.

Changelog

Version 1.1.0

• Update project to .NET 10 (preview)
• Update all project dependencies to latest versions
• Add automated deployment with GitHub Actions (deploy.yaml)
• Add comprehensive VS Code configuration (.vscode/ directory)
  • launch.json: Debug configurations for API and client
  • tasks.json: Build and run tasks for streamlined development
  • settings.json: Optimized workspace settings for .NET development
• Reorganize project structure: move source code to src/ directory
• Enhanced development workflow with pre-configured debugging and build tasks

Version 1.0.1

• Update README with corrections and add acknowledgment message

Version 1.0.0

• Initial release with core functionality
• API project with fastendpoints
• Blazor WASM client project with MudBlazor
• DAL, BLL, Models, Utils, and Shared libraries