installation

Installation Guide

Complete guide to installing and configuring CheapAvaloniaBlazor for cross-platform desktop development.

System Requirements

Before getting started, ensure your system meets these requirements.

Runtime Requirements

Requirement	Minimum	Recommended	Status
.NET Runtime	10.0	Latest 10.0+	Required
Windows	10	11	✅ Fully Tested
Linux	Ubuntu 20.04+	Ubuntu 22.04+	⚠️ Untested
macOS	10.15+	Latest	⚠️ Untested

Development Requirements

Tool	Minimum	Recommended	Purpose
.NET SDK	10.0	Latest 10.0+	Development & Building
Visual Studio	2022 (17.8+)	2022 Latest	GUI Development (optional)
VS Code	Latest	Latest	Terminal & Code Development
C# Support	C# 13	C# 13+	Language Features

Disk Space

SDK Installation: 500 MB
Package Installation: 150-300 MB
Project Build Cache: 200-500 MB
Recommended Free Space: 2 GB

Verification Before Installation

Verify your system is ready before proceeding.

Check .NET SDK Version

dotnet --version

Expected Output:

10.0.x (or higher)

If you see a lower version or "not found", you need to install .NET 10.0 SDK.

Verify C# Language Support

dotnet --info

Look for .NET 10.0 in the SDKs section. Your system is ready if version 10.0+ is listed.

Installation Methods

Choose the installation method that best matches your development environment.

Option A: Command Line (VS Code, Terminal, or PowerShell)

Best for: VS Code users, developers comfortable with terminal commands, cross-platform workflows.

Step 1: Create New Console Project

dotnet new console -n MyDesktopApp
cd MyDesktopApp

This creates:

MyDesktopApp.csproj - Project file
Program.cs - Application entry point
.gitignore - Git ignore file

Step 2: Add CheapAvaloniaBlazor Package

dotnet add package CheapAvaloniaBlazor

This will:

Download the NuGet package
Add package reference to .csproj
Download all dependencies automatically
Cache packages for future builds

Expected Output:

Writing C:\Users\...\MyDesktopApp\MyDesktopApp.csproj
info : Adding PackageReference for package 'CheapAvaloniaBlazor' into project '...'
info : Restoring packages for C:\Users\...\MyDesktopApp\MyDesktopApp.csproj
info : Package 'CheapAvaloniaBlazor' is compatible with all the specified frameworks in...
info : RestoreOperationCompleted in XXXms for...

Step 3: Verify Installation

dotnet restore
dotnet build

Both commands should complete without errors. If you see errors, check the troubleshooting section below.

Option B: Visual Studio 2022 GUI

Best for: Visual Studio users, developers who prefer graphical interfaces, integrated debugging.

Step 1: Create New Project

Open Visual Studio 2022
Click File → New → Project
Search for "Console App" (.NET)
Select "Console App" template
Click Next

Step 2: Configure Project

Project name: Enter MyDesktopApp
Location: Choose your desired folder
Solution name: Auto-filled as project name
Click Next

Step 3: Select Framework

Framework: Select .NET 10.0 from dropdown
Click Create

Visual Studio will:

Create the project structure
Generate default Program.cs
Create .csproj file
Load solution in IDE

Step 4: Install CheapAvaloniaBlazor Package

Right-click Project in Solution Explorer
Select Manage NuGet Packages
Click Browse tab (if not already selected)
Search for "CheapAvaloniaBlazor"
Select the package from results
Click Install

During Installation:

Review license terms
Click I Accept in NuGet License Acceptance dialog
Wait for "Restoration succeeded" message

Step 5: Verify Installation

After installation completes:

Right-click Project → Build Project
Check Output window for build success
Look for message: "Build succeeded"

Common Issues During Installation:

If NuGet fails to restore, try: Tools → Options → NuGet Package Manager → Clear All NuGet Cache(s)
If build fails, ensure you selected .NET 10.0 framework in Step 3

Option C: Avalonia Template (Advanced Users)

Best for: Developers wanting full Avalonia control, integrating with existing Avalonia projects, advanced customization.

Prerequisites

This approach requires familiarity with Avalonia. Only recommended if:

You're already using Avalonia
You need specific Avalonia features beyond CheapAvaloniaBlazor defaults
You're integrating CheapAvaloniaBlazor into existing Avalonia application

Step 1: Install Avalonia Templates

dotnet new install Avalonia.ProjectTemplates

Expected output includes Avalonia templates being added to your system.

Step 2: Create Avalonia Project

dotnet new avalonia.app -n MyDesktopApp
cd MyDesktopApp

This creates a complete Avalonia application structure.

Step 3: Add CheapAvaloniaBlazor

dotnet add package CheapAvaloniaBlazor

Step 4: Update Project File

Edit MyDesktopApp.csproj to use Razor SDK:

<Project Sdk="Microsoft.NET.Sdk.Razor">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
    <PackageReference Include="CheapAvaloniaBlazor" Version="3.3.1" />
  </ItemGroup>
</Project>

Step 5: Integrate with Program.cs

Replace existing Program.cs with CheapAvaloniaBlazor configuration (see Quick Start guide).

Package Dependencies

CheapAvaloniaBlazor automatically installs all required dependencies.

Primary Dependencies

Package	Version	Purpose
Avalonia	12.0.4+	Cross-platform desktop framework, window management
MudBlazor	9.5.0+	Material Design components for Blazor UI
Photino.NET	4.0.16+	WebView hosting, renders Blazor in native window

Secondary Dependencies (Auto-Installed)

These are installed automatically by the above packages:

Package	Purpose
Microsoft.AspNetCore.Components	Blazor components framework
Microsoft.AspNetCore.Components.Web	Web component rendering
Microsoft.JSInterop	JavaScript-C# interoperability
Avalonia.Desktop	Desktop-specific Avalonia features

What Gets Installed

When you run dotnet add package CheapAvaloniaBlazor, you get:

C:\Users\...\MyDesktopApp\.nuget\packages
├── avalonia/               (Desktop framework)
├── mudbla zor/             (UI components)
├── photino.net/            (WebView hosting)
└── [dependencies]/         (Supporting packages)

Total Size: ~200-300 MB (first installation only, cached for future projects)

Version Compatibility

CheapAvaloniaBlazor targets .NET 10.0 with C# 13 language features.

Earlier .NET versions: Not supported
Later .NET versions: Compatible with 10.0+ (forward compatible)
C# earlier versions: Not supported (uses C# 13 syntax)

Post-Installation Verification

After installation, verify everything is working correctly.

Verification Checklist

.NET SDK 10.0+ installed (dotnet --version)
Project created successfully
CheapAvaloniaBlazor package installed
dotnet restore completes without errors
dotnet build succeeds with no errors
Project structure intact (.csproj file present)

Verify Package Installation

dotnet list package

Expected output includes:

CheapAvaloniaBlazor        (latest version)

Test Build

dotnet build

Success indicators:

No red error messages
Output shows: Build succeeded
No warnings about missing dependencies

Quick Runtime Test

// Add to Program.cs
Console.WriteLine("CheapAvaloniaBlazor is ready!");

Then run:

dotnet run

Should output the message and exit cleanly.

Troubleshooting Installation

Error: ".NET 10.0 SDK not found"

Problem: Your system doesn't have .NET 10.0 SDK installed.

Solution:

Go to dotnet.microsoft.com
Download .NET 10.0 SDK (not just Runtime)
Run the installer
Restart your terminal/Visual Studio
Verify: dotnet --version

Expected version: 10.0.x or higher

Error: "Package 'CheapAvaloniaBlazor' not found"

Problem: NuGet cannot find the CheapAvaloniaBlazor package.

Causes & Solutions:

Cause	Solution
NuGet cache corrupted	Run: `dotnet nuget locals all --clear`
Network connectivity	Check internet connection, verify firewall
Package server down	Try again in a few minutes, check nuget.org status
Wrong package name	Verify spelling: `CheapAvaloniaBlazor` (exact case)

Manual Fix:

# Clear all NuGet cache
dotnet nuget locals all --clear

# Restore packages
dotnet restore

# Try installation again
dotnet add package CheapAvaloniaBlazor

Error: "SDK Version 10.0 required, but X.X is installed"

Problem: Your .csproj file specifies .NET 10.0, but you have a different version installed.

Solution Option 1: Upgrade .NET SDK

# Download and install .NET 10.0 from dotnet.microsoft.com
# Then verify
dotnet --version

Solution Option 2: Use installed version (not recommended)

Edit .csproj
Find: <TargetFramework>net10.0</TargetFramework>
Change to your installed version (e.g., net9.0)
Note: Some features may not work with older .NET versions

Error: "Project file is invalid"

Problem: .csproj file has syntax errors.

Common Causes:

Incomplete XML tags
Incorrect SDK declaration
Invalid characters

Solution:

Open MyDesktopApp.csproj in text editor
Verify the structure matches this template:

<Project Sdk="Microsoft.NET.Sdk.Razor">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
    <PackageReference Include="CheapAvaloniaBlazor" Version="3.3.1" />
  </ItemGroup>
</Project>

Save file
Run: dotnet restore

Error: "Avalonia/MudBlazor/Photino dependency resolution failed"

Problem: Package manager cannot resolve transitive dependencies.

Causes & Solutions:

Cause	Solution
Conflicting package versions	Delete `obj/` and `bin/` folders, run `dotnet restore`
Corrupted package cache	Run: `dotnet nuget locals all --clear`
Incomplete .csproj	Ensure Razor SDK is specified: `Sdk="Microsoft.NET.Sdk.Razor"`

Nuclear Option (last resort):

# Remove all caches and intermediate files
dotnet clean
del bin -r
del obj -r
del packages.lock.json

# Reinstall
dotnet restore
dotnet build

Error: "Terminal/Command not found: dotnet"

Problem: Terminal cannot find the dotnet command.

Causes & Solutions:

Platform	Solution
Windows (PowerShell)	Restart PowerShell after SDK installation
Windows (CMD)	Restart Command Prompt after SDK installation
Windows (Git Bash)	Add .NET to PATH manually or use PowerShell
macOS/Linux	Run: `source ~/.bashrc` (or restart terminal)

Manual PATH Setup:

Find where .NET SDK is installed
Add SDK bin folder to system PATH
Restart terminal and verify: dotnet --version

Error: "Visual Studio won't recognize .NET 10.0"

Problem: Visual Studio 2022 project selection doesn't show .NET 10.0.

Solution:

Ensure .NET 10.0 SDK is installed (not just Runtime)
Restart Visual Studio completely
Go to Tools → Options → Projects and Solutions → .NET Core
Enable experimental features if disabled
Close and reopen Visual Studio

Alternative: Use command line to create project:

dotnet new console -n MyDesktopApp
# Then open folder in Visual Studio

Error: "Hot Reload not working"

Problem: Code changes in .razor files don't auto-reload during debugging.

Solutions:

Visual Studio:

Go to Debug → Edit and Continue
Enable "Hot Reload on File Save"
Ensure project targets .NET 10.0
Restart debugger

VS Code:

Ensure Blazor extension is installed
Run dotnet watch run
Make changes to .razor files
Save and check browser for auto-reload

Error: "Port 5000/5001 already in use"

Problem: Default development port is occupied by another application.

Solution:

Temporary (one-time):

dotnet run -- --urls=http://localhost:8080

Permanent (in Program.cs):

var builder = new HostBuilder()
    .WithTitle("My Desktop App")
    .UsePort(8080)  // Use different port
    .AddMudBlazor();

builder.RunApp(args);

Error: "MudBlazor styles not loading (unstyled components)"

Problem: Components appear without styling (no colors, poor layout).

Causes & Solutions:

Cause	Solution
CSS not referenced	Verify `App.razor` includes: `<link href="_content/MudBlazor/MudBlazor.min.css" rel="stylesheet" />`
Wrong CSS link	Check link path is exactly: `_content/MudBlazor/MudBlazor.min.css`
MudBlazor not added	Verify `AddMudBlazor()` called in HostBuilder
Browser cache	Hard refresh: Ctrl+Shift+Delete (Windows) or Cmd+Shift+Delete (Mac)

Quick Fix:

Open Components/App.razor

Verify CSS line exists in <head>:

<link href="_content/MudBlazor/MudBlazor.min.css" rel="stylesheet" />

Check browser console for 404 errors
Clear browser cache and reload

Error: "Could not find a part of the path" (Windows)

Problem: File path contains special characters or is too long.

Solution:

Avoid special characters in project/folder names
Keep folder paths shorter (Windows has ~260 character limit)
Don't use: < > : " / \ | ? *
Use simple names: MyDesktopApp instead of My-Desktop@App (v1.0!)

Platform-Specific Installation Notes

Windows

Fully tested and supported.

Windows 10/11 Setup

Install .NET 10.0 SDK from dotnet.microsoft.com
Restart your computer (recommended)
Use PowerShell or Command Prompt
Follow Option A, B, or C above

Visual Studio 2022 Setup

Install Visual Studio 2022
During installation, select "ASP.NET and web development" workload
Also select ".NET desktop development" for full Avalonia support
Complete installation
Follow Option B above

Development Tools

PowerShell 7+: Modern shell recommended
Windows Terminal: Better terminal experience
Visual Studio 2022: Full IDE experience

Linux

Untested but should work - Dependencies (Avalonia, Photino) are designed for Linux.

Linux Setup

Install .NET SDK:

# Ubuntu/Debian
wget https://dot.net/v1/dotnet-install.sh -O dotnet-install.sh
chmod +x dotnet-install.sh
./dotnet-install.sh --channel 10.0

Install WebKit (required for Photino):

# Ubuntu/Debian
sudo apt-get install libwebkit2gtk-4.1-dev

Create project:

dotnet new console -n MyDesktopApp
cd MyDesktopApp
dotnet add package CheapAvaloniaBlazor

Known Issues

File dialogs may not work (Avalonia StorageProvider integration)
Window decorations may differ from Windows
Please report issues on GitHub

macOS

Untested but should work - Avalonia and Photino have macOS support.

macOS Setup

Install .NET SDK:

# Using Homebrew
brew install dotnet

# Or manually from dotnet.microsoft.com

Create project:

dotnet new console -n MyDesktopApp
cd MyDesktopApp
dotnet add package CheapAvaloniaBlazor

Grant permissions (may be needed):

xcode-select --install  # Install Xcode command line tools

Known Issues

Requires macOS 10.15+
Retina display support untested
Please report issues on GitHub

Next Steps After Installation

Once installation is verified, proceed with:

Read Quick Start Guide: Follow the Getting Started guide
Create Project Structure: Set up Blazor components and pages
Add Desktop Features: Use IDesktopInteropService for file dialogs, notifications
Configure UI: Set up MudBlazor layout and components
Build & Deploy: Package your application for distribution

See the Getting Started guide for detailed guidance on each step.

Getting Help

Troubleshooting Resources

Installation Issues: Check the Troubleshooting section above
Build Errors: See Diagnostics & Debugging
API Questions: Review inline code comments and API documentation
General Help: Check project discussions or create an issue

Reporting Issues

Found a problem? Help improve CheapAvaloniaBlazor:

Check existing issues on GitHub
Provide details: OS, .NET version, error message, steps to reproduce
Share environment: dotnet --info output helpful
Include logs: Enable diagnostics and share relevant output

Uninstallation

To remove CheapAvaloniaBlazor:

Option 1: Remove Package Only

dotnet remove package CheapAvaloniaBlazor

Project folder structure remains; dependencies auto-clean on next dotnet restore.

Option 2: Remove Entire Project

# Delete the project folder
rm -r MyDesktopApp  # Linux/macOS
rmdir /s MyDesktopApp  # Windows CMD
Remove-Item -Recurse MyDesktopApp  # PowerShell

Clear NuGet Cache (Optional)

dotnet nuget locals all --clear

This removes all cached packages from your system.

Advanced Configuration

After basic installation, explore advanced features:

Custom Ports: builder.UsePort(8080)
HTTPS Support: builder.UseHttps(true)
Diagnostics: builder.EnableDiagnostics()
Splash Screen: builder.WithSplashScreen(...)
Window Configuration: builder.WithSize(), builder.WithPosition()

See the Advanced Configuration guide for details.

Migration Guide

Migrating from 1.1.x to 1.2.0

Version 1.2.0 includes important fixes and a breaking change to the project SDK.

Required: Update Project SDK

Change your .csproj file from:

<!-- OLD (1.1.x) -->
<Project Sdk="Microsoft.NET.Sdk.Web">

To:

<!-- NEW (1.2.0+) -->
<Project Sdk="Microsoft.NET.Sdk.Razor">
  <PropertyGroup>
    <!-- ... other properties ... -->
  </PropertyGroup>
</Project>

Why this change?

Microsoft.NET.Sdk.Web caused a console window to flash briefly on startup
Microsoft.NET.Sdk.Razor provides the same Blazor functionality without the console issue

What's Fixed in 1.2.0

Window operations now work - Minimize, maximize, restore, and set title buttons now function correctly
Console logging allocates a window - EnableConsoleLogging = true now properly creates a console window when launched from Windows Explorer
New fluent API - Added EnableContextMenu() method for consistency

Optional: Review Debug Options

The three debug options are now fully functional:

builder.ConfigureOptions(options =>
{
    options.EnableConsoleLogging = true;  // Shows/allocates console window
    options.EnableDevTools = true;        // Enables F12 DevTools
    options.EnableContextMenu = true;     // Enables right-click menu (default)
});

Migrating from 1.2.0/1.2.1 to 1.2.2

Version 1.2.2 fixes framework JS 404 errors with production-safe defaults.

What's Fixed

The Problem: Apps would show InvalidOperationException spam and /_framework/blazor.web.js returned 404.

Root Cause: The embedded Blazor server was running in Production environment where UseStaticWebAssets() doesn't serve framework files dynamically.

The Fix (v1.2.4): CheapAvaloniaBlazor now always uses Development environment internally. No configuration needed - it just works.

Desktop apps are localhost-only, so Production environment's security features (error hiding, HSTS) are irrelevant. Development mode is required for UseStaticWebAssets() to serve blazor.web.js and other framework files from NuGet packages.

If you're upgrading from v1.2.2 or v1.2.3, you can remove any UseEnvironment(), UseDevelopmentEnvironment(), or UseProductionEnvironment() calls - they no longer exist.

Migrating from 1.2.x to 2.0.0 (Modern Blazor Web App Pattern)

Version 2.0.0 migrates from the legacy Blazor Server pattern to the modern Blazor Web App pattern. This is a breaking change.

Required Changes

Remove AddRazorSupportForMvc from your .csproj:

<!-- REMOVE this line -->
<AddRazorSupportForMvc>true</AddRazorSupportForMvc>

Delete Components/_Host.cshtml - No longer needed.
Rename App.razor to Routes.razor - The existing Router component becomes Routes.razor.

Create new Components/App.razor as the HTML document root:

@using Microsoft.AspNetCore.Components.Web

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>My App</title>
    <base href="/" />
    <link href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,700&display=swap" rel="stylesheet" />
    <link href="_content/MudBlazor/MudBlazor.min.css" rel="stylesheet" />
    <HeadOutlet @rendermode="new InteractiveServerRenderMode(prerender: false)" />
</head>
<body>
    <Routes @rendermode="new InteractiveServerRenderMode(prerender: false)" />
    <script src="_framework/blazor.web.js"></script>
    <script src="_content/MudBlazor/MudBlazor.min.js"></script>
    <script src="_content/CheapAvaloniaBlazor/cheap-blazor-interop.js"></script>
</body>
</html>

What Changed Internally

AddServerSideBlazor() → AddRazorComponents().AddInteractiveServerComponents()
MapBlazorHub() + MapFallbackToPage() → MapRazorComponents<App>().AddInteractiveServerRenderMode()
blazor.server.js → blazor.web.js
_Host.cshtml (Razor Page) → App.razor (Razor component as HTML document root)
Razor Pages middleware removed entirely

Installation Summary Table

Method	Best For	Difficulty	Time
Command Line	VS Code, Terminal	Easy	2-3 min
Visual Studio	GUI users	Very Easy	2-3 min
Avalonia Template	Advanced users	Advanced	5-10 min

Questions? Issues? Feedback? Open an issue on GitHub or check project discussions!