STAThread

An application typically has one process that can contain one or more threads. Creating multiple threads within a process allows our application to execute code in parallel; do keep in mind that running code in parallel does not automatically guarantee an increase in performance. Multithreading can be hard to get right and comes with its own set of challenges like thread safety, preventing deadlocks and race conditions.

Component Object Model, or COM, enables application to open up their functionality to other applications in an API-like manner, by generating wrappers that can be called in other application. Windows exposes COM wrappers, for example, for the file and folder dialogs or message boxes.

WinForms relies on the COM wrappers exposed by Windows, and COM runs in a process with a single thread (the UI thread); however, new threads can be created from that point on. This is needed, for example, when you need to execute a long-running operation and you want to prevent the UI from freezing.

The final concept we need to know is the apartment. An apartment is a group of COM objects in a process. Every COM object lives in exactly one apartment, meaning that the methods on a COM object can only be called from a thread that belongs to the same apartment; should any other thread need to call into that COM object, it needs to pass through a proxy.

The WinForms process contains a single thread for rendering the UI; to render the UI, it needs to call into COM wrappers, which means that the COM wrappers and the single thread in our application’s process need to belong to the same apartment. Since apartments come in two flavors, single-threaded and multithreaded, and we only have one thread, we need a single-threaded apartment. However, we are building a C# application; C# applications ever since .NET Framework 2.0 by default use a multithreaded apartment. That’s why the STAThread attribute is set on the Program class, to indicate that this application needs a single-threaded apartment.

WinForms Startup

DPI Mode

After the STAThread attribute, we see some default configuration being set, starting with high DPI mode. DPI, or dots per inch, specifies how many pixels a screen can render on a one inch line; nowadays, the term DPI is often used together with PPI, pixels per inch. Strictly speaking, DPI is a term used for printers and PPI for screens, but DPI seems to be the term most often used in both contexts. So in short, the higher the DPI of a monitor, the more pixels can be placed upon the screen. So why does this matter? Let’s compare two surfaces with different DPI values and draw a rectangle of 8 by 2 pixels on them.

Figure 4-3 shows the same rectangle but drawn on surfaces of the same physical size, but with different DPI values; notice that the higher the DPI of a surface is, the smaller the objects drawn on that surface seem to appear. Operating systems, including mobile operating systems, solve this problem by implementing logical pixels per inch. It’s sort of a virtual screen that is laid over the actual screen; this technique exists to ensure that applications look the same across different screens; aspect ratios are a different problem of course; but that’s beside the point here.

So what was the problem with WinForms applications? Windows tried to make sure that an application looked the same size on every monitor; in a multi-monitor setup that combines high DPI monitors with normal DPI monitors, this means that applications will be “zoomed in” if you will, instead of being scaled natively. This results in a blurry, pixelated image. We can simulate this in Windows by changing the scale factor in the display settings, shown in Figure 4-4.

Figures 4-5 and 4-6 show the difference in application sharpness when high DPI support is switched off in a WinForms application. The screenshots were taken on 175% size.

Notice that Figure 4-6 shows a very blurry experience, not what you want to see on an expensive, fancy 4k ultrawide monitor is it? To fix this, Microsoft updated the GDI API with multiple modes for high DPI. The work on high DPI mode started in .NET Core 3 and kept improving with each release.

• DPI Unaware – this is the “old” behavior; applications assume 100% scaling at 96 DPI; this will result in the blurry applications that are demonstrated in Figure 4-6.

• System DPI Aware – apps will scale according to the DPI of the main monitor at the time of login into Windows. This can still result in blurry applications on the other monitors, but the application will look great on the main monitor.

• Per Monitor DPI Aware – this enables applications to update their rendering according to the DPI of the monitor they are currently on. These applications can update immediately when moved to a monitor with a different DPI; this does require developers to test their UI at different DPI settings.

• Mixed Mode DPI Aware – in mixed mode, we can set one of the above three modes on every top-level window, meaning that we can have different application windows behave differently on different monitors.

DPI mode in a WinForms application can be set in the app.config file, through an API call or via a static method that needs to be called at startup. The default template in .NET 6 includes setting the DPI mode to System Aware through the static method, which is now the recommended way of setting the DPI mode. Depending on what version of Windows your application is running on, you can have three or four modes.

• Unaware

• Unaware GDI Scaled

• System Aware

• Per Monitor

• Per Monitor v2

Most of these match perfectly on the list of modes supported in the GDI+ API, but what about Per Monitor v2? This is a mode that only works on Windows 10 version 1607 and later. Per Monitor v2 extends the Per Monitor option into the non-client areas, meaning that title bars and scroll bars, for example, will keep DPI scaling in mind as well. It also extends scaling events to child windows while Per Monitor limits this for parent windows only.

Responding to Scale Events

WinForms provides some events, helper methods, and properties to allow us to react to DPI changes and update the UI where needed.

• DpiChanged – an event that fires when the DPI is changed for the monitor the form is currently on.

• DpiChangedAfterParent – an event that fires when the parent control or form changed DPI from code after receiving a DpiChanged event.

• DpiChangedBeforeParent – an event that fires when the parent control or form changed DPI from code before receiving a DpiChanged event.

• LogicalToDeviceUnits – a helper method that converts a logical size to device units, keeping the current DPI in mind, and returns a System.Drawing.Size object.

• ScaleBitmapLogicalToDevice – a helper method that scales a System.Drawing.Bitmap to device units after a DPI change.

• DeviceDpi – a property that gets the current DPI value for the monitor the form is currently displayed on. This property comes in as a parameter on a DpiChanged event.

Listing 4-4 shows an example of a form that uses some of these events and properties to show a form that displays DPI information. If you still have the designer window open from the first part of this chapter, you can press F7 to switch to the code behind. From there we can add an eventhandler to the DpiChanged event , shown here in the constructor. From that eventhandler, we update the text on a label that we dropped on the form using the designer.

public partial class DpiForm : Form

{

    public DpiForm()

    {

        InitializeComponent();

        DpiLabel.Text = $"Current DPI: {DeviceDpi}";

        DpiChanged += OnDpiChanged;

    }

    private void OnDpiChanged(object sender, DpiChangedEventArgs e)

    {

        DpiLabel.Text = $"DPI changed from {e.DeviceDpiOld} to {e.DeviceDpiNew}";

    }

}

Listing 4-4

Reacting to DPI changes

Figure 4-7 shows the result of the form when it starts up.

If we set High DPI mode to DpiUnaware and change the scaling of the monitor, you’ll notice that the form seems to zoom in; it will get blurry but the text in the label will remain the same. This means that the system still calculates the size according to 96 DPI, instead of the new value. Figure 4-8 shows this result.

After setting High DPI mode to PerMonitorV2, we expect the DPI to change when we adjust scaling, and it does exactly that, but we get a new problem as shown in Figure 4-9.

You’ll notice that the text we do see is rendered sharp; however, the label didn’t resize, so our text is being cut off. This is because the WinForms designer, by default, sets autoscale mode to Font. However, our font size is not changing; our scale factor is. We can solve this by changing the autoscale mode as shown in Listing 4-5; Figure 4-10 shows the result.

public DpiForm()

{

    InitializeComponent();

    DpiLabel.Text = $"Current DPI: {DeviceDpi}";

    AutoScaleMode = AutoScaleMode.Dpi;

    DpiChanged += OnDpiChanged;

}

private void OnDpiChanged(object sender, DpiChangedEventArgs e)

{

    DpiLabel.Text = $"DPI changed from {e.DeviceDpiOld} to {e.DeviceDpiNew}";

}

Listing 4-5

Setting autoscale mode to DPI instead of font

Visual Styles

Let’s continue with the startup calls; the next step is Application.EnableVisualStyles.

EnableVisualStyles simply prepares all the colors, fonts, and other visual elements in the theme of the current operating system. Let’s take a form with a label, datepicker, and a button as shown in Figure 4-11.

The elements on this form automatically take the styling of Windows 10, the operating system the application was running on when taking this screenshot. We can disable loading the visual styles by replacing the call to Initialize with Listing 4-3 and commenting out Application.EnableVisualStyles method we get the result from Figure 4-12.

The application still runs, but visually it looks very old; that is because all the controls fallback to their default look and feel. Application.EnableVisualStyles will keep the user’s preference in mind; if it runs on a Windows system with visual styles disabled, it will respect this setting and load the application without visual styles.

The Message Loop

The final call before our application appears on screen is Application.Run(new Form1()).

The Run method starts what’s called the message loop. A Windows desktop application needs a loop where it handles user events. The application exits once the loop exits, and this can be done programmatically by calling Exit() to terminate the application or ExitThread() to terminate the current thread, which will exit the application only if no other foreground threads are running. Applications can be exited manually by the user clicking the close button, pressing ALT-F4 or any other way to close an application on Windows. The Run method takes in a form as parameter; this form will be the startup form of the application. The message loop will end once this form is closed, effectively exiting the application.

The Form Designer

Building a form is usually done through the form designer. The designer is a visual canvas where controls can be dropped from the toolbox and laid out. Doing this visually makes for a powerful and fast developer loop. Figure 4-13 shows dropping a button from the toolbox onto the designer surface.

Feel free to double-click a form to open the designer and play around with the toolbox. Drop some components, move some controls around, and have a look at the properties. You’ll notice that the designer tries to help you by snapping the controls to align with the margins of the other controls to make for a consistent layout. Once a control is placed, we can use the properties window (F4 is the shortcut key to open the properties for the selected control) to set different properties and hook up event handlers. For example, click on the dropdown for BackColor and try some different values. You will notice that the designer reacts immediately to your changes.

Responding to Events

There are a few different ways to make a button react to a click. The fastest way is to double click on the button in the designer; this will generate a click event handler in the code behind of the form. Double-clicking any control will hook up an event handler to the default event for that control; click event for buttons, textchanged for textboxes, selectionchanged for combobox, and so on. Should we want to hook up another event, we can do this through the events pane in the properties window, found behind the lightning icon that can be seen in Figure 4-14. Look for the event you need and double-click the space beside it, as shown in Figure 4-15.

Another way is to do programmatically as shown in Listing 4-6.

public ProductForm()

{

    InitializeComponent();

    DetailsButton.DragOver += DetailsButton_DragOver;

}

private void DetailsButton_DragOver(object sender, EventArgs e)

{

}

Listing 4-6

Programmatically reacting to a button getting focus

Once our design looks good in the designer, it’s time to see what it actually looks like on screen. The first results are very good, until we resize the window.

Looks like our application is not very responsive yet. Making controls resized in WinForms is done through anchors; anchor is a property set on every control that determines what border is anchored to the side of the form.

After applying the correct anchor points, which is all anchor points in this case, we can make the form behave like Figure 4-18.

Figure 4-19 shows the used anchor points for every control.

The grid that is on the form in Figures 4-18 and 4-19 is the DataGridView. The classic DataGrid control has not been ported from .NET Framework; DataGridView is based on DataGrid and extends it, for example, in the data sources it accepts. Listing 4-7 shows a simple example of setting data to the DataGridView named ProductsDataGrid.

private async void ProductForm_Load(object sender, EventArgs e)

{

    var ctx = new AdventureWorksContext();

    var products = await ctx.Products.ToListAsync();

    ProductsDataGrid.DataSource = products;

}

Listing 4-7

Setting data to a DataGridView

We’re using an Entity Framework datacontext to easily get to our data. Once data is loaded, we assign it to the DataGridView’s DataSource property , and that is all that’s needed to show the data in the grid.

Let’s add the possibility to add new products to the dataset; Listing 4-8 shows a first attempt at this.

public partial class ProductForm : Form

{

    private List<Product> _products;

    public ProductForm()

    {

        InitializeComponent();

    }

    private async void ProductForm_Load(object sender, EventArgs e)

    {

        AdventureWorksContext ctx = new ();

        _products = await ctx.Products.ToListAsync();

        ProductsDataGrid.DataSource = _products;

    }

    private void AddProductButton_Click(object sender, EventArgs e)

    {

        _products.Add(new Product());

    }

}

Listing 4-8

Add new products to the dataset

The click event handler is triggered when the Add Product button is clicked; nothing seems to happen however. Should you set a breakpoint in the event handler, you’ll notice that the event is triggered and new products are added to the list but that change is not reflected in the UI. That is because in WinForms the UI is not reactive; it does not monitor every property to see if it might need to update; instead, it waits for an event that tells it what property has changed. Listing 4-9 shows a working example.

public partial class ProductForm : Form

{

    private BindingList<Product> _products;

    public ProductForm()

    {

        InitializeComponent();

    }

    private async void ProductForm_Load(object sender, EventArgs e)

    {

        AdventureWorksContext ctx = new();

        List<Product> products = await ctx.Products.ToListAsync();

        _products = new BindingList<Product>(products);

        ProductsDataGrid.DataSource = _products;

    }

    private void AddProductButton_Click(object sender, EventArgs e)

    {

        _products.Add(new Product());

    }

}

Listing 4-9

Working databinding

Only one thing changed; the List<Product> has changed into a BindingList<Product>; a BindingList triggers an event whenever the data in the list changes, allowing our UI to respond to that change.

WPF Startup

Listing 4-10 shows the XAML part of App.xaml. The important part here is the StartupUri; this property sets the first window to show when launching the application. You’ll notice that the code behind of App.xaml is quite empty. That is because the bootstrapping and launching of the WPF application is done in the generated App class that combines both the XAML and the code parts. You can inspect this file by going to your project in Windows Explorer and take a look in the obj folder.

Even in the generated startup code, there is not a lot going on; you will notice the StartupUri property being set to the value that was defined in App.xaml. Next to that there is the Main method that every application in .NET 6 has as a starting point. Main initializes our App class and calls its Run method; that method is part of WPF’s Application base class. It contains the logic for creating the window wrapper and creates the first window to be shown. The application base class also contains some virtual methods that can be overridden for configuring lifecycle events; some examples of these methods are OnActivated, OnDeactivated, OnLoadCompleted, OnExit, OnStartup, OnSessionEnding, and OnNavigated.

XAML Layout

Moving on to MainWindow. MainWindow also consists of two files, just like the App class. Building your UI in a WPF application can be done quite similar to WinForms; WPF also has a graphical designer, for example. Visual Studio by default shows the XAML editor when opening a XAML file. We can switch to the designer by pressing shift-F7 or selecting Design on the bottom left of Visual Studio.

As you can see in Figure 4-22, it allows us to drag and drop controls from the toolbox and position them in a very graphical way, just like with WinForms. Figure 4-23 shows the running application; don’t worry about the logic to get data in the datagrid; we’re only looking at the design in this example.

In Listing 4-13, we see two columns defined using star notation. In total we get 3, meaning that the available space will be divided into three equal parts. The first column will get one part, hence 1*. The second column will get two parts, hence 2*.

This can also be done from the designer; if you select the grid, its sizings become visible and can be adjusted as shown in Figure 4-24.

The next optimalization is easily spotted if we try to resize the form; notice what happens to the delete button.

The button is vertically aligned to the top, meaning that it will appear as close to the top of its parent as it is allowed. The margin property pushed the button down from the top. Margin takes four values, respectively, left, top, right, and bottom. Do take care not to mix this order up with the order in CSS, which is different! By setting the VerticalAligment to Bottom, we can force the button down; by using the bottom margin, we can push it back up a bit to align with the datagrid. Figure 4-26 shows the improved responsiveness.

Looking at the rowdefinitions, you will notice three rows. The top two have height set to Auto; the third one takes on all available space. This combined with the correct VerticalAlignments and some margins results in exactly the layout we want, including responsiveness. A small extra performance optimalization could be to give the top two rows an absolute value. Those rows exist solely to contain one button each; if there is absolutely no reason for the buttons to grow in height, we can set the row height to a fixed value so that the layout cycle doesn’t need to calculate the height.

Visual Tree

The WPF designer includes some tools to speed up the process of developing a UI. Figure 4-27 shows the toolbar in the title bar of a WPF application running in debug.

This example uses the VisualTreeHelper to traverse the visual tree in search for a specific type. Being able to inspect and traverse the visual tree from code gives us a great flexibility. No matter what control or part of the UI we are in, we can always find specific control instances. This allows us to create dynamic views where classic databinding, where you need to know everything up front, would not suffice.

Back to the toolbar, the Select Element on the toolbar allows us to select an element in the running application and inspect its runtime values, much like the developer tools in a browser. First select the Select Element button on the toolbar, select an element in the running application, and switch back to Visual Studio. In Visual Studio is a Live Visual Tree pane; it might be collapsed by default. If you can’t find it, use the Search box in the title bar to search for Live Visual Tree. In the Live Visual Tree pane, we can see the actual current visual tree. Right-clicking an element and selecting Show Properties will open the Live Property Explorer pane showing the properties of the selected element. The properties that are not calculated by WPF can be changed here and will impact the running application. Do note that your changes here will not automatically reflect in your XAML code. These are great tools to find the exact values you need, or debugging a visual issue while running your application, but it is not a real-time editor.

We can even use the toolbar to show us the layout adorners like margins and paddings of a selected element, as demonstrated in Figure 4-29. By toggling the layout adorners, we can inspect the margins and paddings of selected elements, again very similar to what you might be used to from browser developer tools.

The Hot Reload check in the toolbar shows that we can edit our XAML and save it, and the changes will be reflected in the running application without restarting it. We will dive deeper into Hot Reload later in this chapter.

Data Binding

That should do it! However, when we run the application, you’ll notice that the datagrid is still empty. Did we miss something? Are bindings broken in .NET 6? Do not worry; this is a result of the order in which things are happening and a result of the fact that we aren’t notifying the UI of a change yet.

The INotifyPropertyChanged interface contains one member, the PropertyChanged event. We fire this in the set method of the Products property. By firing this event, we notify the datagrid that its data has changed and that it needs to refresh its UI. We dive deeper into XAML, binding, and the MVVM design pattern in Chapter 6 of this book. Chapter 6 handles MAUI, Microsoft’s cross-platform framework.

Building a Windows App SDK application

From Visual Studio, we create a new solution. In the project type selection window, we can filter on WinUI. The WinUI 3 templates contain the references to the Windows App SDK. The SDK is fully wired up and ready to go.

There are two types of WinUI applications, packaged applications and unpackaged applications. Unpackaged applications result in an executable that we ourselves are responsible for to put into an installer; these types of applications are used when installing through an MSI or setup.exe wizard. Packaged applications on the other hand are fully prepared to be installed using MSIX. MSIX is Microsoft’s packaging format; it is an easy way for users to install, update, and uninstall applications on their system. The biggest advantage to MSIX is that every application installed through MSIX works with a sandboxed registry and a sandboxed filesystem, meaning if we uninstall the application, all traces of it are effectively removed from the system. This prevents the slowing down of computers because of registry keys that keep floating around.

There are two app templates, one packaged with MSIX and one packaged with MSIX using a Windows Application Packaging (WAP) project. The second type will generate a solution with two projects. The second project is only there to configure and generate the MSIX file using the package manifest. This is mostly there for backward compatibility reasons since the WAP projects have been around ever since MSIX was introduced with UWP.

As you might have seen, there is no template for creating unpackaged apps. An unpackaged app can be created by selecting the packaged app without WAP template and adding the WindowsPackageType setting with value None to the project file. For this example, we will use the Blank App, Packaged project type, without a WAP project. Select the template and create a new solution. Figure 4-31 shows the generated project.

Those DPI values sure look familiar; they are the same values we have set back when we were talking about WinForms.

Let’s have a look at MainWindow.xaml. It looks very similar to what we had in WPF, so how do we know we really are using the Windows App SDK with WinUI 3? Figure 4-32 shows what the namespaces for a button in XAML; on the left is the WinUI 3 project we just created, while on the right is a .NET 6 WPF application.

Every control in WinUI 3 lives in the Microsoft.UI.Xaml.Controls namespace. With this, we have confirmation that we are using the controls from the WinUI 3 library, coming from the Windows App SDK NuGet package. No longer do we need to wait for a Windows update whenever a bug is found in a control or when new controls are announced. Thanks to WinUI 3, the controls are now shipped out of band with Windows, through NuGet.

Using Windows APIs with Windows App SDK

Thanks to the Windows App SDK, we get access to the Windows Runtime, or WinRT, interop capabilities. We first fetch a pointer to where the window lives in memory (window is the name given to the window element in XAML). With that pointer we can grab the window ID, and finally with that ID we can fetch the actual AppWindow instance.

This code replaces the button’s event handler that was in MainWindow when it was created. When we run this and click the button, you will see the title change, and the window will resize to the result in Figure 4-33.

This was just one example of how we can use the Windows App SDK. The full set of documentation can be found at https://docs.microsoft.com/en-us/windows/apps/windows-app-sdk/ .

Packaging

Once your application is ready to be shipped, we can package it as an MSIX. Make sure to verify the Packaging tab in Package.appxmanifest. Before we can create our MSIX, we need to select a certificate to sign our application. MSIX requires this to prevent attacks on the user’s system through altered software. The toolchain does allow us to create a test certificate, but I would strongly advice to get a real trusted certificate to sign your applications. For now, for the sake of this demo, a self-signed certificate will suffice. Click on the Choose Certificate option and select Create. This will create a self-signed certificate and add it to your project as a *.pfx file. Figure 4-34 shows the certificate window.

This certificate will now be used to sign your application before packaging it as an MSIX. But certificates only work when they are trusted by the machine they are used on. Navigate to the pfx file in Windows Explorer and double-click it. This will launch the Certificate Import Wizard. Select Local Machine as store location in step 1. The certificate’s filename in step 2 should already be filled in with your pfx file. In step 3 you are asked to select a password; this is optional and can be left blank. In the final step we will select the certificate store ourselves and browse to Trusted Root Certificate Authorities.

Select Next and Finish to import the certificate into your Trusted Root Authority.

A quick but very important sidenote. We have just imported a self-signed certificate into our Trusted Root store of our machine. This is not the way certificates are meant to be used, and we are potentially opening up our machine for malicious software. Keep this in mind and remove the certificate from your store as soon as possible.

Once everything is in order, right-click the project and select Pack.

Once Visual Studio is done packaging your application, you will find an MSIX file in your project’s bin<cpu architecture>Release et6.0-windows10.0.19041.0win10-x86AppPackagesApressWinUiDemo_1.0.0.0_x86_Test.

Double-click the MSIX file and an installer will popup. If you did everything correctly, the installer will say that this is a trusted app, which means that the certificate that was used for signing the application is trusted by your machine. Figure 4-37 shows the installer.

After installing, the application will show up in the list of installed applications on your Windows installation. Remember, this application is using sandboxed registry and filesystem, so uninstalling it shouldn’t leave a trace behind.

Upgrade Assistant

There is an alternative to doing the migration manually. Microsoft has created a command line tool called Upgrade Assistant. It basically does the same steps as described above but automatically. The upgrade assistant is open source and can be found at https://github.com/dotnet/upgrade-assistant. Upgrading a project using the upgrade assistant is as easy as calling upgrade assistant upgrade .Pixelator.csproj. The upgrade assistant is a wizard that guides you through the process step by step, allowing you to skip whatever step you want or see more details.

Just like with the manual process, test every single nook and cranny of your application after migrating to .NET 6!