Skip to content

Commit 0a0ecd1

Browse files
andrewbabbittdevandrewbabbittdev
authored
chore: update readme
1 parent a831a67 commit 0a0ecd1

1 file changed

Lines changed: 156 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 156 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,159 @@
33
[![GitHub issues](https://img.shields.io/github/issues/AndrewBabbitt97/BlazorDesktop?style=for-the-badge)](https://github.com/AndrewBabbitt97/BlazorDesktop/issues)
44

55
# Blazor Desktop
6-
Blazor Desktop allows you to create desktop apps using Blazor.
6+
Blazor Desktop allows you to create desktop apps using Blazor. Apps run inside of a .NET generic host and run inside of a WPF window.
7+
![app](https://user-images.githubusercontent.com/2308261/153133429-7e1cdebd-72d0-4d61-91d9-eb14089cf9fc.png)
8+
9+
# Getting Started
10+
The easiest way to get started with Blazor Desktop is to install the templates, you can do so using the dotnet cli as follows:
11+
12+
```powershell
13+
dotnet new --install BlazorDesktop.Templates::1.0.3
14+
```
15+
16+
Once you have the templates installed, you can either create a new project from the template either in Visual Studio in the template picker:
17+
![desktop](https://user-images.githubusercontent.com/2308261/153132853-5430710e-a4d7-434d-a46c-1269b9865711.png)
18+
19+
Or, you can create a new project using the cli as follows:
20+
```powershell
21+
dotnet new blazordesktop -n MyBlazorApp
22+
```
23+
24+
# Tips & Tricks
25+
The Blazor Desktop template is set up very similar to the Blazor WASM template, you can see the `Program.cs` file here:
26+
27+
```csharp
28+
using BlazorDesktop.Hosting;
29+
using HelloWorld;
30+
using HelloWorld.Data;
31+
using Microsoft.AspNetCore.Components.Web;
32+
33+
var builder = BlazorDesktopHostBuilder.CreateDefault(args);
34+
builder.RootComponents.Add<App>("#app");
35+
builder.RootComponents.Add<HeadOutlet>("head::after");
36+
37+
builder.Services.AddSingleton<WeatherForecastService>();
38+
39+
await builder.Build().RunAsync();
40+
```
41+
42+
You can add root components just the same as well as add additional services your app may need just the same.
43+
44+
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.
45+
46+
## Window Utilities
47+
The window can have most of its common configuration done through the `BlazorDesktopHostBuilder.Window` APIs before you build your app in `Program.cs`.
48+
49+
To change your window title:
50+
```csharp
51+
builder.Window.UseTitle("Hello");
52+
```
53+
54+
Window size:
55+
```csharp
56+
builder.Window.UseWidth(1920)
57+
.UseHeight(1080);
58+
```
59+
60+
Disable window resizing:
61+
```csharp
62+
builder.Window.UseResizable(false);
63+
```
64+
65+
Disable the window frame (allows you to use your own window chrome inside of Blazor):
66+
```csharp
67+
builder.Window.UseFrame(false);
68+
```
69+
70+
And change your window icon (uses `wwwroot/favicon.ico` as the default):
71+
```csharp
72+
builder.Window.UseFrame(false);
73+
```
74+
75+
It is also possible to configure these values through `appsettings.json` like so:
76+
```json
77+
{
78+
"Window": {
79+
"Title": "Hello Blazor",
80+
"Height": 900,
81+
"Width": 400,
82+
"Frame": false,
83+
"Resizable": false,
84+
"Icon": "hello.ico"
85+
},
86+
"Logging": {
87+
"LogLevel": {
88+
"Default": "Information",
89+
"Microsoft.AspNetCore": "Warning"
90+
}
91+
}
92+
}
93+
```
94+
95+
**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.**
96+
97+
## Custom Window Chrome & Draggable Regions
98+
It is possible to make your own window chrome for Blazor Desktop apps. As an example base setup you could do the following:
99+
100+
Set up the window to have no frame in `Program.cs`:
101+
```csharp
102+
builder.Window.UseFrame(false);
103+
```
104+
105+
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:
106+
```razor
107+
@inherits LayoutComponentBase
108+
109+
<div class="page">
110+
<div class="sidebar">
111+
<NavMenu />
112+
</div>
113+
114+
<main>
115+
<div class="top-row px-4" style="-webkit-app-region: drag;">
116+
<a href="https://docs.microsoft.com/aspnet/" target="_blank">About</a>
117+
</div>
118+
119+
<article class="content px-4">
120+
@Body
121+
</article>
122+
</main>
123+
</div>
124+
```
125+
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.
126+
127+
In terms of handling things such as the close button, you can inject the Window into any page and interact from it there.
128+
129+
Here is an example changing `MainLayout.razor`:
130+
```razor
131+
@using System.Windows
132+
@inherits LayoutComponentBase
133+
@inject Window window
134+
135+
<div class="page">
136+
<div class="sidebar">
137+
<NavMenu />
138+
</div>
139+
140+
<main>
141+
<div class="top-row px-4" style="-webkit-app-region: drag;">
142+
<a href="https://docs.microsoft.com/aspnet/" target="_blank">About</a>
143+
</div>
144+
145+
<article class="content px-4">
146+
<button @onclick="CloseWindow">Close Window</button>
147+
@Body
148+
</article>
149+
</main>
150+
</div>
151+
152+
@code {
153+
void CloseWindow()
154+
{
155+
window.Close();
156+
}
157+
}
158+
```
159+
160+
## Issues
161+
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.

0 commit comments

Comments
 (0)