Chapter 3 The Fundamentals of .NET MAUI
Summary
Phew! That felt like a lot to take in! I think I need to take a tea break! Don’t worry, though; while this gives an overview of what each of the files are responsible for, you will be modifying most of them throughout this book with some practical examples so if there are any points that aren’t clear, or you feel you will need to revisit them, you certainly will be.
/Resources/ Folder
The Resources folder is where you store anything you want to include in your application that is not strictly code. Let’s look through each of the sub-folders and key types of resource.
Fonts
.NET MAUI allows you to embed your own custom fonts. This is especially handy if you are building an app for a specific brand, or you want to make sure that you render the same font on each platform. You can embed either True Type Fonts (.ttf files) or Open Type Fonts (.otf files).
A word of warning around fonts. I strongly recommend that you check the licensing rules around fonts before including them in your application. While there are sites that make it possible to download fonts freely, a very large percentage of those fonts usually require paying to use them.
There are two parts to embedding a font so that it can be used within your application.
\ 1.\ The font file should be place in this folder (Resources/Fonts).
51
Chapter 3 The Fundamentals of .NET MAUI
By default, the font will be automatically included as a font file based on the following line that can be found inside the project file (WidgetBoard.csproj):
<MauiFont Include="Resources\Fonts\*" />
What the above line does is set the build action of the file you just included to be of type MauiFont.
If you want to perform this manually, you can rightclick the file inside Visual Studio, click Properties, and inside the Properties panel set the Build Action to MauiFont.
\ 2.\ Configure the font.
When bootstrapping your application, you need to specify which fonts you wish to load. This is performed with the following lines inside your
MauiProgram.cs file:
.ConfigureFonts(fonts =>
{
fonts.AddFont("Lobster-Regular.ttf", "Lobster");
});
In the above example, you add the font file LobsterRegular.ttf to the collection of fonts and give it an alias of Lobster. This means you can just use the name of Lobster when referring to the file in your application.
Images
Practically every application you build will include some images. Each platform that you wish to support has its own rules on the image sizes that you need to supply to make the image render as sharp and clear on the
52
Chapter 3 The Fundamentals of .NET MAUI
many devices they run. Take iOS, for example. In order to supply a 24x24 pixel image in your app, you must provide three different image sizes: 24x24, 48x48, and 72x72. This is due to the different DPIs for the devices Apple builds. Android devices follow a similar pattern but the DPIs are not the same. This is similar for Windows.
Figure 3-2 shows an example image that would be rendered at 24x24 pixels. Note that while Windows shows the three sizes, this is just based off recommendations for trying to cover the most common settings. In truth, Windows devices can have their DPIs vary much more. Figure 3-2 shows the required image sizes needed for all supported platforms in order to render a 24x24 pixel image.
53
Chapter 3 The Fundamentals of .NET MAUI
Figure 3-2. Required image sizes across the various platforms
You can see from the figure above that it can become painful very quickly if you have lots of images in your application each requiring at least five different sizes to be maintained. Thankfully .NET MAUI gives us the ability to provide a single Scalable Vector Graphic (SVG) image and it will generate the required images for all the platforms when the application is compiled. I cannot tell you how happy all of us Xamarin.Forms old timers are at this new piece of functionality!
54
Chapter 3 The Fundamentals of .NET MAUI
As it currently stands, if the SVG image is of the correct original size, you can simply drop the image into the /Resources/Images/ folder and it will just begin to work in your application. In a similar way to how the fonts are automatically picked up, you can see how the images are also handled by looking inside your project file and observing the line <MauiImage Include="Resources\Images\*" />
.NET MAUI doesn’t render SVGs directly but generates PNG images from the SVGs at compile time. This means that when you are referring to the image you wish, it needs to have the .png extension. For example, when embedding an image called image.svg, in code you refer to it as image.png.
If the contents of the SVG are not of the desired size, then you can add some configuration to tell the tooling what size the image should be. For this the image should not be added to the /Resources/Images/ folder as the tooling will end up generating duplicates and there is no telling which one will win. Instead, you can simply add the image to the /Resources/ folder and then add the following line to your project file:
<MauiImage Include="Resources\image.svg" BaseSize="24,24" />
The above code will treat the contents of the image.svg file as being 24x24 pixels and then scale for each platform based on that size.
Raw
Your final type of resource to embed is raw files. This essentially means that what is embedded can be loaded at runtime. A typical example of this is to provide some data to preload into the application when first starting.
55