First .NET MAUI App Walkthrough: A Step-by-Step Guide for Beginners

Introduction

Welcome to the world of .NET Multi-platform App UI (MAUI)! .NET MAUI is a powerful new framework from Microsoft that enables developers to build natively styled applications for Android, iOS, macOS, Windows, and Tizen using a single codebase. This guide aims to walk you through creating your first .NET MAUI application, ensuring you understand each step of the process from setting up your development environment to deploying your app.

Step 1: Setting Up Your Development Environment

To start developing with .NET MAUI, you need to have Visual Studio installed, specifically the 2022 version or later. During this installation, ensure you select the following workloads:

• .NET Multi-platform App UI development
• Mobile development with .NET
• Desktop development with C#

These workloads include all the essential tools and dependencies needed for .NET MAUI.

1. Download and Install Visual Studio:

   • Visit the Visual Studio website and download the installer.
   • Run the installer, choose your preferred installation setup, and make sure to select the workloads mentioned above.
   • Follow the prompts to complete the installation.

2. Install .NET SDK:

   • The .NET SDK is automatically installed with Visual Studio if you selected the appropriate workloads.
   • You can verify the installation by opening a command prompt or terminal and typing dotnet --version.

3. Install Android SDK and Emulator (Optional):

   • If you plan to run your application on Android, you may need to install the Android SDK.
   • This is usually handled automatically during Visual Studio installation, but you can find additional settings under Tools > Android > Android SDK Manager.
   • Set up an Android emulator or connect a physical Android device for testing.

4. Install Xcode (macOS Users Only):

   • macOS users need Xcode to build iOS applications.
   • Install Xcode from the Mac App Store.
   • You also need to configure the macOS environment by opening Xcode, agreeing to the license terms, and installing additional components if prompted.

Step 2: Creating a New .NET MAUI Project

With your development environment set up, it’s time to create your first .NET MAUI application.

1. Open Visual Studio:

   • Launch Visual Studio 2022.

2. Create a New Project:

   • Select Create a new project from the start window.
   • In the Create a new project window, enter MAUI in the search bar.
   • From the filtered list, select .NET MAUI App (Preview) and click Next.
   • Name your project (e.g., MyFirstMAUIApp), choose a location to save it, and click Create.

3. Project Structure:

   • The project template will generate a default set of files and folders:
     • Platforms/: This folder contains platform-specific projects and files.
     • Resources/: This folder includes resources like images and styles.
     • App.xaml and App.xaml.cs: These files define the overall structure and resources of your application.
     • MainPage.xaml and MainPage.xaml.cs: These files define the main page of your application initially.

Step 3: Exploring the Project Structure

Let's take a closer look at the generated project structure and learn what each component does.

1. Platforms/ Directory:

   • Contains platform-specific projects such as Android, iOS, macOS, and Windows.
   • Each platform-specific folder may contain platform-specific configuration files and assets.

2. Resources/ Directory:

   • This is where you’ll store your application’s resources, such as images, styles, and XAML resources.
   • Resources are shared across platforms, but you can also override them for specific platforms.

3. App.xaml and App.xaml.cs:

   • App.xaml is used to define any global XAML resources that will be available across your application.
   • App.xaml.cs contains the C# code for initializing the application, setting the main page, and handling events.

4. MainPage.xaml and MainPage.xaml.cs:

   • MainPage.xaml is the main window of your application and is defined using XAML (Extensible Application Markup Language).
   • MainPage.xaml.cs contains the C# code-behind logic for the main page.

Step 4: Creating a Simple User Interface

Let’s create a simple user interface that includes a label and a button. When the button is clicked, the label’s text will change.

1. Open MainPage.xaml:

   • In Visual Studio, navigate to MainPage.xaml in the Solution Explorer.

2. Modify XAML:

   • Replace the existing code with the following:

     <?xml version="1.0" encoding="utf-8" ?>
     <ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
                  xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
                  x:Class="MyFirstMAUIApp.MainPage"
                  BackgroundColor="{DynamicResource SecondaryColor}">
         <StackLayout
             Padding="20">
             <Label
                 x:Name="HelloLabel"
                 Text="Welcome to .NET MAUI!"
                 SemanticProperties.HeadingLevel="Level1"
                 HorizontalOptions="Center"
                 FontSize="24"
                 FontAttributes="Bold"
                 LineBreakMode="WordWrap"/>
             <Button
                 x:Name="HelloButton"
                 Text="Click Me!"
                 Clicked="OnHelloButtonClicked"
                 BackgroundColor="{DynamicResource PrimaryColor}"
                 TextColor="White"
                 Margin="20,10,20,0"/>
         </StackLayout>
     </ContentPage>
     

3. Open MainPage.xaml.cs:

   • In Visual Studio, navigate to MainPage.xaml.cs in the Solution Explorer.

4. Add Event Handler:

   • Add the following method to handle the button click event:

     private void OnHelloButtonClicked(object sender, EventArgs e)
     {
         HelloLabel.Text = "Hello, .NET MAUI!";
     }
     

Step 5: Running Your Application

It’s time to run your application and see the changes you made.

1. Select a Platform:

   • At the top of your screen, in the toolbar, you’ll see a dropdown menu to select the platform you want to run your application on (e.g., Android, iOS, Windows).
   • Choose the platform you want to target.

2. Run Your Application:

   • Click on the green Start button (or press F5) to build and run your application.
   • Depending on the platform you selected, your app will run in an emulator or simulator, or on a physical device if connected.

3. Interact with Your Application:

   • When the app opens, you should see a label saying "Welcome to .NET MAUI!" and a button labeled "Click Me!".
   • Click the button, and the label’s text should change to "Hello, .NET MAUI!".

Step 6: Adding Functionality and Styling

Let's expand our application by adding more features and styling.

1. Add a New Page:

   • In the Solution Explorer, right-click on your project and select Add > New Item.
   • Choose MAUI XAML Page and name it SecondPage.xaml.
   • This will create two files: SecondPage.xaml and SecondPage.xaml.cs.

2. Modify SecondPage.xaml:

   • Replace the existing code with the following:

     <?xml version="1.0" encoding="utf-8" ?>
     <ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
                  xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
                  x:Class="MyFirstMAUIApp.SecondPage"
                  BackgroundColor="{DynamicResource SecondaryColor}">
         <StackLayout Padding="20">
             <Label Text="This is the second page!"
                    FontSize="20"
                    HorizontalOptions="Center"/>
         </StackLayout>
     </ContentPage>
     

3. Navigate Between Pages:

   • Open MainPage.xaml and add a new button for navigation.

     <Button
         Text="Go to Second Page"
         Clicked="OnNavigateButtonClicked"
         BackgroundColor="{DynamicResource PrimaryColor}"
         TextColor="White"
         Margin="20,10,20,0"/>
     

   • Open MainPage.xaml.cs and add the navigation event handler:

     private async void OnNavigateButtonClicked(object sender, EventArgs e)
     {
         await Navigation.PushAsync(new SecondPage());
     }
     

4. Styling Your Application:

   • Open App.xaml and add styles and resources to customize your application.

     <Application xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
                  xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
                  x:Class="MyFirstMAUIApp.App">
         <Application.Resources>
             <ResourceDictionary>
                 <Style TargetType="Button">
                     <Setter Property="FontSize" Value="16"/>
                     <Setter Property="CornerRadius" Value="5"/>
                     <Setter Property="HeightRequest" Value="40"/>
                 </Style>
                 <Color x:Key="PrimaryColor">#2196F3</Color>
                 <Color x:Key="SecondaryColor">#FFFFFF</Color>
             </ResourceDictionary>
         </Application.Resources>
     </Application>
     

Step 7: Testing Your Application on Different Platforms

Testing your application on multiple platforms is crucial to ensure compatibility and a seamless user experience.

1. Test on Android:

   • Select Android from the platform dropdown in Visual Studio.
   • Run your application in an Android emulator or on a physical device.
   • Verify that navigation and styling work as expected.

2. Test on iOS:

   • Select iOS from the platform dropdown in Visual Studio.
   • Ensure you have a Mac with Xcode installed.
   • Run your application in an iOS simulator or on a physical device.
   • Check that the application functions correctly on iOS.

3. Test on macOS:

   • Select macOS from the platform dropdown in Visual Studio.
   • Run your application on macOS.
   • Verify that the application looks and behaves as expected on the desktop platform.

4. Test on Windows:

   • Select Windows from the platform dropdown in Visual Studio.
   • Run your application as a Windows application.
   • Ensure the application works correctly on the Windows platform.

Step 8: Debugging and Troubleshooting

Debugging is an essential part of the development process, helping you identify and fix issues in your application.

1. Set Breakpoints:

   • In MainPage.xaml.cs, click in the margin next to the code lines to set breakpoints.
   • The debugger will pause execution at these points, allowing you to inspect variables and step through the code.

2. Use the Debugger:

   • Start debugging by clicking on the green Start button or pressing F5.
   • When the debugger stops at a breakpoint, use the debugging toolbar to step over, step into, and step out of methods.
   • Inspect the values of variables using the Locals window or by hovering over variables in the code editor.

3. Inspect Logs:

   • Use the Output and Debug windows in Visual Studio to view log messages and diagnostic information.
   • Add log statements to your code to help trace the flow of execution and identify issues.

4. Use Visual Studio Tools:

   • Visual Studio provides powerful tools for troubleshooting, including the Performance Profiler, Memory Profiler, and Live Visual Tree.

Step 9: Publishing Your Application

Once your application is complete and tested, you can publish it to app stores and distribute it to users.

1. Prepare for Deployment:

   • Ensure your application meets the respective platform’s requirements and guidelines.
   • Sign up for developer accounts with Apple, Google, and Microsoft if you haven’t already.

2. Build and Package:

   • Select the target platform and build configuration (Release).
   • Choose Build > Publish... from the menu.
   • Follow the steps to package your application for deployment.

3. Submit to App Stores:

   • For iOS, submit your app to the Apple App Store.
   • For Android, publish your app on Google Play Store.
   • For Windows, submit your app to Microsoft Store.

4. Promote Your Application:

   • Use marketing channels and social media to promote your application.
   • Encourage users to leave reviews and ratings to improve visibility.

Conclusion

Congratulations! You’ve successfully created your first .NET MAUI application. Along the way, you learned how to set up your development environment, create a new project, build a user interface, navigate between pages, test on different platforms, debug your application, and get ready for deployment. As you continue to develop with .NET MAUI, explore more features and advanced topics to build more complex and powerful applications.

Happy coding!