README.md

Blazor Desktop

Blazor Desktop allows you to create desktop apps using Blazor. Apps run inside of a .NET generic host with a WPF window thats fully managed using a similar template to Blazor WASM.

Getting Started

The easiest way to get started with Blazor Desktop is to install the templates, you can do so using the dotnet cli as follows:

dotnet new install BlazorDesktop.Templates::8.0.0

Once you have the templates installed, you can either create a new project from the template either in Visual Studio in the template picker:

Or, you can create a new project using the cli as follows:

dotnet new blazordesktop -n MyBlazorApp

Tips & Tricks

The Blazor Desktop template is set up very similar to the Blazor WASM template, you can see the Program.cs file here:

using BlazorDesktop.Hosting;
using HelloWorld.Components;
using Microsoft.AspNetCore.Components.Web;

var builder = BlazorDesktopHostBuilder.CreateDefault(args);

builder.RootComponents.Add<Routes>("#app");
builder.RootComponents.Add<HeadOutlet>("head::after");

if (builder.HostEnvironment.IsDevelopment())
{
    builder.UseDeveloperTools();
}

await builder.Build().RunAsync();

You can add root components just the same as well as add additional services your app may need just the same.

There are however a few additional APIs and services that have been made available to help when working in the context of a WPF window.

Window Utilities

The window can have most of its common configuration done through the BlazorDesktopHostBuilder.Window APIs before you build your app in Program.cs.

To change your window title:

builder.Window.UseTitle("Hello");

Window size:

builder.Window
    .UseWidth(1920)
    .UseHeight(1080)
    .UseMinWidth(1280)
    .UseMinHeight(720)
    .UseMaxWidth(2560)
    .UseMaxHeight(1440);

Disable window resizing:

builder.Window.UseResizable(false);

Disable the window frame (allows you to use your own window chrome inside of Blazor):

builder.Window.UseFrame(false);

And change your window icon (uses favicon.ico as the default, base directory is wwwroot):

builder.Window.UseIcon("myicon.ico");

It is also possible to configure these values through appsettings.json like so:

{
  "Window": {
    "Title": "Hello Blazor",
    "Height": 1080,
    "Width": 1920,
    "MinHeight": 720,
    "MinWidth": 1280,
    "MaxHeight": 1440,
    "MaxWidth": 2560,
    "Frame": false,
    "Resizable": false,
    "Icon": "hello.ico"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  }
}

The Window object itself is also made available inside of the DI container, so you can access all properties on it by using the inject Razor keyword or requesting it through the constructor of a class added as a service.

Custom Window Chrome & Draggable Regions

It is possible to make your own window chrome for Blazor Desktop apps. As an example base setup you could do the following:

Set up the window to have no frame in Program.cs:

builder.Window.UseFrame(false);

Using the base template, if you were to edit MainLayout.razor and add a -webkit-app-region: drag; style to the top bar like so:

@inherits LayoutComponentBase

<div class="page">
    <div class="sidebar">
        <NavMenu />
    </div>

    <main>
        <div class="top-row px-4" style="-webkit-app-region: drag;">
            <a href="https://learn.microsoft.com/aspnet/core/" target="_blank">About</a>
        </div>

        <article class="content px-4">
            @Body
        </article>
    </main>
</div>

The top bar becomes draggable, applying the -webkit-app-region: drag; property to anything will make it able to be used to drag the window.

In terms of handling things such as the close button, you can inject the Window into any page and interact from it there.

Here is an example changing MainLayout.razor:

@using BlazorDesktop.Wpf

@inherits LayoutComponentBase
@inject BlazorDesktopWindow window

<div class="page">
    <div class="sidebar">
        <NavMenu />
    </div>

    <main>
        <div class="top-row px-4" style="-webkit-app-region: drag;">
            <a href="https://learn.microsoft.com/aspnet/core/" target="_blank">About</a>
        </div>

        <article class="content px-4">
            @Body
        </article>
    </main>
</div>

@code {
    void CloseWindow()
    {
        window.Close();
    }
}

To support fullscreen mode, you should also hide your custom window chrome when in fullscreen. You can check the current fullscreen status using the IsFullscreen property on the window. You can also monitor for it changing using the OnFullscreenChanged event.

Issues

Under the hood, Blazor Desktop uses WebView2 which has limitations right now with composition. Due to this, if you disable the window border through the Window.UseFrame(false) API, the top edge of the window is unusable as a resizing zone for the window. However all the other corners and edges work.