A Quick Recap

Software supply chain attacks are an increasing threat that targets source code, build processes or update mechanisms to infect legitimate apps and distribute malware. Incidents like the SolarWinds attack have breached all types of organisation ranging from startups to Fortune 500 companies and government agencies.

StepSecurity helps secure your software release and distribution supply chain. Secure Workflows provides remediation of vulnerabilities in GitHub Actions workflows and the Harden Runner security agent prevents exfiltration of credentials and helps detect compromised dependencies, tools or source code.

What is Harden Runner?

As seen in recent supply chain attacks, including the Codecov breach and malicious npm cryptomining packages, compromised dependencies and build tools typically make outbound calls. Restricting outbound traffic to only the endpoints needed for the workflow thwarts many software supply chain attack vectors.

When added to a job in a GitHub Actions workflow, the Harden Runner security agent can audit and block outbound traffic from the runner executing that job. There are some limitations:

• Harden Runner only works for GitHub hosted runners, self-hosted runners are not supported.
• Only Ubuntu runners are supported, Windows and macOS runners are being discussed.
• Harden Runner does not support running an entire job in a container, which is unusual for GitHub Actions.

Harden Runner supports both public and private repositories. If you use Harden Runner with a private repository the generated audit report is not public, authentication is required and only those who have access to the repository can view the report.

How do I set up Harden Runner?

The easiest way to add Harden Runner to a workflow is to use the Secure Workflows app. This can set the minimum GITHUB_TOKEN permissions for the workflow, pin the Actions used by a full length commit SHA and add the Harden Runner Action to the start of each job in audit mode. Future runs of the workflow will include a link to an audit report that lists all the outbound calls made in the workflow log.

For private repositories you also need to install the Harden Runner app on GitHub which requires actions: read permissions to your repositories. I've also installed the app for my public repositories because otherwise you have to wait 30 seconds for the results and I'm impatient.😄

How do I configure block mode?

With Harden Runner added to your workflows you continue to develop your project while it audits outbound connections. Once you have completed several runs of a workflow you can check the audit reports and build a list of allowed connections. Simple workflows like project management tasks may always make the same connections but more complicated workflows may include optional calls so it is worth checking several runs rather than relying on the results of just one audit.

The audit report lists every step in a job. If a step makes any outbound connections the domain is listed along with the name of the process that made the connection. If a workflow includes multiple jobs then each job has its own tab in the report.

The audit report also provides the YAML needed to configure Harden Runner to block any outbound connections from the job other than those listed in the report.

Once you configure Harden Runner in block mode, it will restrict outbound traffic from the workflow to only the domains listed.

What happens when a call is blocked?

Calls to any domain not allowed by Harden Runner will fail DNS resolution and cause the step that made them, and the job, to fail. So let's test that out...

I added the following step to the same CI build workflow used for the audit screenshots above:

    - name: Test Harden Runner
      run: curl -X GET https://blog.taranissoftware.com/

This uses curl to access a URL that is not in the list of allowed endpoints provided to Harden Runner. Immediately we can see in the pull request that there is a problem:

Clicking through to the workflow summary we can see that an attempt was made to access a restricted endpoint and was blocked at the DNS level:

The workflow logs show it was our test step that tried to access the restricted domain:

And, we can also see the details of the step, process and blocked endpoint in the Harden Runner report:

Tips for .NET Developers

Since Harden Runner only works on an Ubuntu runner you can't use it for jobs that require a Windows or macOS runner such as building .NET Framework, Xamarin or .NET MAUI apps but it does work for building .NET Core, .NET 5 and .NET 6 apps that will build on Linux.

Disable .NET Telemetry

The .NET CLI includes telemetry that sends data back to Microsoft. When running the CLI in a build environment you should disable the telemetry because otherwise commands like dotnet build and dotnet restore will make additional calls. To disable the telemetry add the following environment variables to your workflow:

env:
  DOTNET_NOLOGO: true                     # Disable the .NET logo in the console output
  DOTNET_SKIP_FIRST_TIME_EXPERIENCE: true # Disable the .NET first time experience
  DOTNET_CLI_TELEMETRY_OPTOUT: true       # Disable sending .NET CLI telemetry to Microsoft

This should also reduce the workflow duration slightly, which is a nice bonus.

Setup .NET

In my projects the action to set up .NET (actions/setup-dotnet) is inconsistent - sometimes it makes two outbound calls and other times it makes three. This is a good example of why you need to audit multiple runs of a workflow before enabling block mode because the list of allowed connections needs to include all possible calls. From my experience the set up .NET action needs these connections:

dotnetbuilds.azureedge.net:443
dotnetcli.azureedge.net:443
dotnetcli.blob.core.windows.net:443

Final Thoughts

Harden Runner requires some time to fully configure but once blocking is enabled it thwarts many common attack vectors. Between Secure Workflows and Harden Runner, StepSecurity have added two powerful tools to the DevSecOps toolkit for developers using GitHub Actions. Whether you're working on open or closed source projects I reccommend you check them out and improve the security of your software supply chain.

Cover image contains a vector created by upklyak from www.freepik.com.

Software Supply Chain Attacks chart is from Sonatype's 2021 State of the Software Supply Chain report.

What are Software Supply Chain Attacks?

Software supply chain attacks are an emerging threat that targets software developers and suppliers. The goal of attackers is to access source code, build processes or update mechanisms to infect legitimate apps and distribute malware. There has been a surge in supply chain attacks following the well known SolarWinds attack in 2020. These attacks have breached all types of organisation ranging from startups to Fortune 500 companies, government agencies and open source projects. Attackers are now focusing their efforts on breaching software suppliers because a successful attack may affect a large number of victims that use the supplier's software.

What is StepSecurity?

StepSecurity aims to help secure your software release and distribution supply chain as simply as possible. The Secure Workflows app provides remediation of vulnerabilities in GitHub Actions workflows, significantly reducing the time and effort required to apply security settings. And, the Harden Runner Action audits and blocks outbound traffic to prevent exfiltration of credentials, detect compromised dependencies or tools and detect code tampering during builds.

StepSecurity was recently recognized by the Linux Foundation for "high-impact and lasting improvements that almost certainly prevent major vulnerabilities in the affected code or supporting infrastructure." Secure Workflows is used by many of the OpenSSF's critical open source projects including Python, Gatsby and Babel as well as products from Microsoft, Google and Cisco.

StepSecurity currently supports GitHub Actions but support for GitLab, CircleCI and more providers is on the roadmap.

Secure Workflows

The Secure Workflows app can automatically:

• Set minimum GITHUB_TOKEN permissions
• Pin Actions to a full length commit SHA
• Add the Harden Runner Action to each job

Token Permissions

At the start of a workflow run, GitHub generates a unique GITHUB_TOKEN that is passed to the runner to be used for authentication and expires when the workflow finishes or after a maximum of 24 hours. By default the token has write permissions for all scopes except when generated by a pull request from a fork, in which case it has only read permissions.

A compromised token with write access could be used to push malicious code into a project. By setting all the token permissions to read except where required by the workflow, Secure Workflows follows the principle of least privilege and reduces the risk of a compromised token.

StepSecurity maintains a knowledge base of GitHub Actions that is used by Secure Workflows to determine the permissions needed by each step in your workflow and recommend the minimum permissions. If you maintain a GitHub Action please contribute to the knowledge base so users of your Action can know they have the correct permissions set. Both my Actions - Code Coverage Summary & Edit Release - are already in the knowledge base.

Pin Actions by SHA

Git and Docker tags are mutable. This poses a security risk because if the tag changes you will not have a chance to review the change before it gets used. The current GitHub recommended best practice for using Actions is pinning them to a full length commit SHA rather than a version tag. This helps mitigate the risk of an attacker compromising the Action's repository because they would need to generate an SHA-1 collision.

Although pinning to a commit SHA is the most secure option, specifying a tag is more convenient and easier to read so it is widely used. Secure Workflows allows you to write your workflow using tags then update it with the Secure Workflows app to pin all the Actions by commit SHA. If you use Dependabot to keep your workflow dependencies up to date, don't worry, it also understands pinning by SHA so will continue to keep your workflows updated and following best practice.

Add Harden Runner Action

Secure Workflows can add a step that installs the Harden Runner security agent to the start of each job in a workflow, configuring it in audit mode. Harden Runner only supports Ubuntu runners so disable this option if you are using a Windows or macOS runner, more on this below.

Harden Runner

Compromised dependencies and build tools typically make outbound calls. This was seen in the Codecov breach, Alex Birsan's research on dependency confusion attacks, malicious npm cryptomining packages and other recent attacks. Restricting outbound traffic to only the endpoints needed for the workflow thwarts many attack vectors that target the build server.

Harden Runner is a GitHub Action that installs a security agent on the runner to audit and block outbound traffic to prevent exfiltration of credentials, help detect compromised dependencies or tools and detect code tampering during builds. There are a few limitations:

• Harden Runner only works for GitHub hosted runners, self-hosted runners are not supported.
• Only Ubuntu runners are supported, Windows and macOS runners are not currently supported but are being discussed.
• Harden Runner does not support running a job in a container. It can monitor jobs that use containers to run steps, the limitation is if the entire job is run in a container which is not common for GitHub Actions workflows.

Since Harden Runner will only work on an Ubuntu runner you can't use it for jobs that require a Windows or macOS runner such as building .NET Framework, Xamarin or .NET MAUI apps. It does work for .NET Core and .NET 5/6 apps that will build on Linux and can be used for other jobs that don't require a Windows or macOS runner such as project management workflows.

Harden Runner supports both public and private repositories. For private repositories you need to install the Harden Runner App in GitHub which requires actions: read permissions to your repositories. I also recommend installing the app for public repositories because otherwise you have to wait 30 seconds for the results and I'm impatient. If you use Harden Runner in a private repository the generated audit report is not public, authentication is required to access the report and only those who have access to the repository can view it.

The Secure Workflows app can be used to add Harden Runner to every job in a workflow, configuring it in audit mode. Future runs of the workflow will include a link to the audit report for that run. Once you have audited several runs you can configure Harden Runner in block mode with a list of the allowed endpoints for the workflow. From then on, outbound traffic from the workflow will be restricted to only those domains on the list. Calls to any other domain will fail DNS resolution and cause the step that made them and the workflow to fail.

How do I use all this?

If all that security talk sounds complicated don't worry, StepSecurity have made implementing all the recommendations a simple process.

To secure a GitHub Actions workflow:

1. Copy the workflow YAML file
2. Paste it into the Secure Workflows app
3. Click the Secure Workflows button
4. Click the Copy button
5. Paste the workflow back into your codebase

If there are any problems securing your workflow, such as using an Action not in the knowledge base, the errors will be listed with guidance. Whenever the app discovers an Action that is missing from the knowledge base it automatically opens an issue in the Secure Workflows repository so it will be added in the near future.

.NET Build Example

Let's look at a simple .NET 6 CI build workflow:

name: CI Build

on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]

env:
  DOTNET_NOLOGO: true                     # Disable the .NET logo in the console output
  DOTNET_SKIP_FIRST_TIME_EXPERIENCE: true # Disable the .NET first time experience
  DOTNET_CLI_TELEMETRY_OPTOUT: true       # Disable sending .NET CLI telemetry to Microsoft

jobs:
  build:
    runs-on: ubuntu-latest
    name: CI Build
    steps:

    - name: Checkout
      uses: actions/checkout@v3
      with:
        fetch-depth: 0

    - name: Setup .NET
      uses: actions/setup-dotnet@v2
      with:
        dotnet-version: 6.0.x

    - name: Restore Dependencies
      run: dotnet restore src/Example.sln

    - name: Build App
      run: dotnet build src/Example.sln --configuration Release --no-restore

    - name: Run Unit Tests
      run: dotnet test src/Example.sln --configuration Release --no-build --verbosity normal --collect:"XPlat Code Coverage" --results-directory ./coverage

    - name: Code Coverage Summary Report
      uses: irongut/CodeCoverageSummary@v1.3.0
      with:
        filename: coverage/**/coverage.cobertura.xml
        badge: true
        format: 'md'
        output: 'both'

    - name: Add Coverage PR Comment
      uses: marocchino/sticky-pull-request-comment@v2
      if: github.event_name == 'pull_request'
      with:
        recreate: true
        path: code-coverage-results.md

    - name: Upload Coverage Artifact
      uses: actions/upload-artifact@v3.1.0
      with:
        name: test-coverage-report
        path: code-coverage-results.md

    - name: Upload Build Artifact
      uses: actions/upload-artifact@v3.1.0
      with:
        name: ci-nuget
        path: src/Example/bin/Release/net6.0

This workflow runs on all pull requests or pushes to the master branch and builds a .NET 6 app on an Ubuntu runner. It does not set any token permissions and pins its Actions using the easier to read version tags. It consists of one job with several steps:

• checkout the code
• set up .NET
• restore dependencies
• build the .NET code
• run unit tests
• create a code coverage summary report
• add the report to the PR
• upload the report and build artifacts

Secured .NET Build

Now let's secure the workflow using the StepSecurity Secure Workflows app:

name: CI Build

on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]

env:
  DOTNET_NOLOGO: true                     # Disable the .NET logo in the console output
  DOTNET_SKIP_FIRST_TIME_EXPERIENCE: true # Disable the .NET first time experience
  DOTNET_CLI_TELEMETRY_OPTOUT: true       # Disable sending .NET CLI telemetry to Microsoft

permissions:  # added using https://github.com/step-security/secure-workflows
  contents: read

jobs:
  build:
    permissions:
      contents: read  # for actions/checkout to fetch code
      pull-requests: write  # for marocchino/sticky-pull-request-comment to create or update PR comment
    runs-on: ubuntu-latest
    name: CI Build
    steps:

    - name: Harden Runner
      uses: step-security/harden-runner@74b568e8591fbb3115c70f3436a0c6b0909a8504
      with:
        egress-policy: audit # TODO: change to 'egress-policy: block' after couple of runs

    - name: Checkout
      uses: actions/checkout@d0651293c4a5a52e711f25b41b05b2212f385d28
      with:
        fetch-depth: 0

    - name: Setup .NET
      uses: actions/setup-dotnet@c0d4ad69d8bd405d234f1c9166d383b7a4f69ed8
      with:
        dotnet-version: 6.0.x

    - name: Restore Dependencies
      run: dotnet restore src/Example.sln

    - name: Build
      run: dotnet build src/Example.sln --configuration Release --no-restore

    - name: Run Unit Tests
      run: dotnet test src/Example.sln --configuration Release --no-build --verbosity normal --collect:"XPlat Code Coverage" --results-directory ./coverage

    - name: Code Coverage Summary Report
      uses:  irongut/CodeCoverageSummary@51cc3a756ddcd398d447c044c02cb6aa83fdae95
      with:
        filename: coverage/**/coverage.cobertura.xml
        badge: true
        format: 'md'
        output: 'both'

    - name: Add Coverage PR Comment
      uses: marocchino/sticky-pull-request-comment@39c5b5dc7717447d0cba270cd115037d32d28443
      if: github.event_name == 'pull_request'
      with:
        recreate: true
        path: code-coverage-results.md

    - name: Upload Coverage Summary Artifact
      uses: actions/upload-artifact@3cea5372237819ed00197afe530f5a7ea3e805c8
      with:
        name: test-coverage-report
        path: code-coverage-results.md

    - name: Upload Artifact
      uses: actions/upload-artifact@3cea5372237819ed00197afe530f5a7ea3e805c8
      with:
        name: ci-nuget
        path: src/Example/bin/Release/net6.0

As you can see, the app makes several changes to the workflow.

It starts by setting the default token permissions for all jobs to read:

permissions:  # added using https://github.com/step-security/secure-workflows
  contents: read

In the build job it sets the required token permissions for the Actions used:

jobs:
  build:
    permissions:
      contents: read  # for actions/checkout to fetch code
      pull-requests: write  # for marocchino/sticky-pull-request-comment to create or update PR comment

The Harden Runner Action is added in audit mode as the first step in the job:

    - name: Harden Runner
      uses: step-security/harden-runner@74b568e8591fbb3115c70f3436a0c6b0909a8504
      with:
        egress-policy: audit # TODO: change to 'egress-policy: block' after couple of runs

And, every Action is now pinned by commit SHA instead of a version tag, for example:

    - name: Setup .NET
      uses: actions/setup-dotnet@c0d4ad69d8bd405d234f1c9166d383b7a4f69ed8
      with:
        dotnet-version: 6.0.x

Where do we go from here?

Using Secure Workflows to restrict token permissions and pin Actions to a commit SHA is quick and easy to do for all your workflows. The next step is to continue to develop your project while Harden Runner audits outbound connections from your workflows.

In a follow-up article I show how to use the audit reports and configure Harden Runner in block mode to restrict outbound connections and further improve the security of your GitHub Actions software supply chain.

Cover image contains a vector created by fullvector from www.freepik.com.

Software Supply Chain Attacks chart is from Sonatype's 2021 State of the Software Supply Chain report.

Background

First a little background...

For the last two years I've been maintaining three iOS apps written with Xamarin.iOS and MonoTouch.Dialog (anyone remember MT.D?). These apps are part of a larger compliance management product used internationally to solve complex asset management, auditing, permitting & compliance challenges and had previously been languishing without any love for a while. I've been working to get them back in-step with the rest of the product and following the latest Apple guidelines.

This has been an interesting experience since I hadn't actually used MonoTouch.Dialog before but fortunately it is easy to learn and surprisingly powerful. I've even written several custom controls for it. Kudos to Miguel de Icaza and the original Xamarin team that MonoTouch.Dialog not only works well for our purpose but is still working 12 years and many versions of iOS later!🙇‍♂️ Genius. Now that our existing iOS apps have achieved parity with the rest of the product the time has come to create the first cross platform version of the most used app.🎉

The app itself is used for on-site data collection on civil engineering projects like road, railway and airport construction. It needs to connect to an existing backend web service to sync data, take photos, get the device's location and process different types of customisable data entry form using the same business logic as the existing app. Nothing out of the ordinary for an enterprise app so why did we choose the older Xamarin.Forms rather than the new .NET MAUI hotness?

Deciding Factors

A number of factors fed into our decision to use Xamarin.Forms over .NET MAUI.

Tooling

The tooling for .NET MAUI still requires a preview version of Visual Studio 2022 and there is no UI for archiving and publishing an app. Although the Windows tooling should be updated in August, the macOS version won't be ready until November (hopefully) and we have concerns about what will be included and it's stability. We don't want to get to the end of development only to run into problems publishing our app.

Library Support

Although library developers are working towards a .NET MAUI release some of the libraries I normally use for Xamarin.Forms apps are not ready yet and a few don't have plans for a .NET MAUI version which means waiting, finding alternatives or creating our own libraries before we can start developing the app.

Experience

We have a small team of developers with Xamarin.iOS and Xamarin.Forms experience and a larger team of .NET developers with no Xamarin experience but only one developer has any experience with .NET MAUI. (me!👋)

Documentation

While the .NET MAUI documentation is improving it is still quite sparse, especially when compared to the wealth of documentation for Xamarin.Forms. There are also a lot more books, blog posts, FAQs, Stack Overflow answers, videos, podcasts, etc to help with Xamarin.Forms than .NET MAUI which will help the members of the team with less experience.

Time

This is the most important consideration and contributes to several of the other factors I already listed. Due to wider business goals and customer requests we need an Android version of this app as soon as possible. Preferably next month, or sooner.😉 Development needs to be fast and we can't wait for Visual Studio & .NET MAUI to mature.

In a lot of ways we've been unlucky with the timing of events. If .NET MAUI had released with .NET 6 last year or if the tooling had been complete with the GA in May or if we had more time for development we probably would have picked MAUI.

Technical Debt

Given the support dates for Xamarin.Forms we will need to move this app to .NET MAUI some time next year so how can we manage this technical debt and reduce the time to repay it? I've proposed several strategies based on my knowledge of both platforms.

MVVM Framework

I made the decision not to use a third-party MVVM framework in our Xamarin.Forms app. Instead we will use the in-built MVVM features of the platform with base classes to handle INotifyPropertyChanged and the required boilerplate code. Not using a third-party framework means no-one on the team has to learn it before they can contribute. We also don't run the risk of picking a framework that doesn't get ported to .NET MAUI. And, we're not restricted in our choice of dependency injection library.

Dependency Injection

By using the Microsoft.Extensions.DependencyInjection library for dependency injection and inversion of control, the code we write for Xamarin.Forms should be compatible with .NET MAUI with minimal changes.

JSON Library

The existing apps use the old System.Json namespace to serialise and deserialise data. System.Json was designed for Silverlight and is not the most performant way to work with JSON in .NET today. Until recently I would have suggested we replace it with the familiar Newtonsoft.Json. But, having read Jon Pepper's post about Perfomance Improvements in .NET MAUI and the reduction in app size they were able to achieve with the .NET Podcasts sample app by switching from Newtonsoft.Json to System.Text.Json, I proposed we use System.Text.Json instead. This might take us a little more time now but we should see similar improvements in app size and it will save us time when moving to .NET MAUI.

Vector Images

.NET MAUI can generate an icon, splash screen and all the required images for an app from SVG images. Using the FFImageLoading library we can also use SVG images in Xamarin.Forms so I've requested all image assets in SVG format. This should reduce the time spent worrying over images when developing both versions of the app and when we must use a PNG in Xamarin.Forms (e.g. for the Android splash screen) we can export the necessary resolutions from the vector image.

Final Thoughts

I'm still excited about the future of .NET MAUI but we felt the platform needs to mature a little more before we can commit to it. I think with the release of .NET 7 and the tooling for macOS in November the picture will look better and I can start to plan moving all our apps to .NET MAUI next year.

Cover image includes a vector created by upklyak - www.freepik.com

Code Coverage Summary reads Cobertura format coverage files from your test suite and outputs a text or markdown summary that can be posted as a Pull Request comment or included in Release Notes to give you an immediate insight into the health of your code without using a third-party site.

Code Coverage Summary is designed for use with any test framework that outputs coverage in Cobertura XML format including Coverlet, gcovr, simplecov and MATLAB. See the FAQ for more details.

Release Notes

• 🗃 Now supports glob pattern matching for multiple coverage files
• ✔ Improved compatibility with simplecov & simplecov-cobertura
• ➕ Now compatible with MATLAB's code coverage plugin
• 🔐 Docker image signed using Sigstore
• 🕵️‍♂️ Compatible with StepSecurity Secure Workflows

Links

• 🛍 GitHub Marketplace
• 👨‍💻 Repository
• 📚 Documentation

Blue vector created by vectorjuice - www.freepik.com

No, I'm not writing a blues song and actually this was yesterday but I coudn't resist that opening line.😄 I awoke to find a text message telling me I had a donation via GitHub Sponsors! Who was this and which project had sparked their donation? Once I grabbed a coffee I investigated...

It turns out I'd missed a recent email from GitHub Sponsors telling me I would receive a payment from GitHub itself. GitHub hosted Maintainer Month in June, an event for open source maintainers to gather, share and be celebrated. This included conferences, meetups and podcasts where maintainers shared their knowledge and experience. It was also a chance to reflect on the challenges that face open source maintainers, which aren't always technical and can come with a lack of boundaries, vacations or emotional support.

As part of Maintainer Month, GitHub wanted to celebrate and give additional support to the open source projects they depend on to build and run GitHub and all the software they maintain. So they are distributing $500,000 to over 900 maintainers of their open source dependencies who are also signed up with GitHub Sponsors!

So I knew who and why but which project was harder to determine because the GitHub Sponsors programme doesn't tell you which project your sponsor uses. Looking through the dependency graphs for my open source projects I was able to determine that GitHub are using Code Coverage Summary, my GitHub Action that reads coverage files from your test suite and outputs a summary to give you immediate insights into the health of your code.

This has been a tough year for me personally and GitHub's donation put a smile on my face and really made my week so I want to thank them for supporting me and the other people who also received donations as part of Maintainer Month.

Thank-you GitHub! 🥰

Introduction

The .NET MAUI app this workflow builds is my demo app MAUI Beach but it should be easily adaptable for any .NET MAUI app.

This is a CI build workflow without any testing, signing or deployment steps that will build a .NET MAUI app for Android, iOS, MacCatalyst and Windows in four separate jobs that run in parallel. Each build job will usually take between 3 and 10 minutes to run, Windows and macOS runners are charged at an increased rate so be aware this workflow can eat into your GitHub Actions minutes.

Set up the Workflow

The first part of the workflow is standard stuff for GitHub Actions - set the workflow name, the events it responds to and any environment variables.

name: CI Build

on:
  push:
    branches: [ master ]
    paths-ignore:
      - '**/*.md'
      - '**/*.gitignore'
      - '**/*.gitattributes'
  pull_request:
    branches: [ master ]
  workflow_dispatch:
permissions:
  contents: read

env:
  DOTNET_NOLOGO: true                     # Disable the .NET logo
  DOTNET_SKIP_FIRST_TIME_EXPERIENCE: true # Disable the .NET first time experience
  DOTNET_CLI_TELEMETRY_OPTOUT: true       # Disable sending .NET CLI telemetry

As you can see, this workflow will respond to push and pull request events on the master branch and also has a manual workflow_dispatch trigger. To prevent unnecessary builds, the push event ignores changes that only involve markdown files, .gitignore or .gitattributes.

The environment variables tell the .NET CLI not to show the logo, to skip the first time experience and disable telemetry. This should help improve build times a little.

Android Build Job

# MAUI Android Build
  build-android:
    runs-on: windows-2022
    name: Android Build
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Setup .NET 6
        uses: actions/setup-dotnet@v2
        with:
          dotnet-version: 6.0.x

      - name: Install MAUI Workload
        run: dotnet workload install maui --ignore-failed-sources

      - name: Restore Dependencies
        run: dotnet restore src/MauiBeach/MauiBeach.csproj

      - name: Build MAUI Android
        run: dotnet publish src/MauiBeach/MauiBeach.csproj -c Release -f net6.0-android --no-restore

      - name: Upload Android Artifact
        uses: actions/upload-artifact@v3.1.0
        with:
          name: mauibeach-android-ci-build
          path: src/MauiBeach/bin/Release/net6.0-android/*Signed.a*

Building a .NET MAUI app for Android can be done on macOS or Windows so this build job uses a Windows runner as they are less expensive than macOS. Visual Studio 2022 is required so we use a windows-2022 runner. The windows-latest runner currently uses the same Windows Server 2022 image so it could be used instead.

The job starts by checking out the code as normal and then installs .NET 6. During preview a pre-release version of .NET 6 was required but since .NET MAUI is now GA we can use the standard release.

In the earlier version of this workflow I installed a distribution of JDK 11 at this point. This is no longer required. 🎉

The .NET MAUI workload is not included in GitHub's windows-2022 runner so it must also be installed. The MAUI workload installs the required workloads for every platform so we only need one install command: dotnet workload install maui

Now we get to the meat of the job - restore dependencies and build the app. We can use a standard dotnet publish command to build our app for Android. The important argument here is -f net6.0-android to set the framework we want to build. I like my CI builds to be release builds so I've used the argument -c Release as well as --no-restore so dependencies are only restored once.

Finally the job uploads the build artifacts, MAUI Beach creates AAB and APK files so both are uploaded.

Windows Build Job

# MAUI Windows Build
  build-windows:
    runs-on: windows-2022
    name: Windows Build
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Setup .NET 6
        uses: actions/setup-dotnet@v2
        with:
          dotnet-version: 6.0.x

      - name: Install MAUI Workload
        run: dotnet workload install maui --ignore-failed-sources

      - name: Restore Dependencies
        run: dotnet restore src/MauiBeach/MauiBeach.csproj

      - name: Build MAUI Windows
        run: dotnet publish src/MauiBeach/MauiBeach.csproj -c Release -f net6.0-windows10.0.19041.0 --no-restore

      - name: Upload Windows Artifact
        uses: actions/upload-artifact@v3.1.0
        with:
          name: mauibeach-windows-ci-build
          path: src/MauiBeach/bin/Release/net6.0-windows10.0.19041.0/win10-x64/AppPackages/MauiBeach*/MauiBeach*.msix

Building a .NET MAUI app for the Windows platform requires Windows and Visual Studio 2022 so the Windows build job also uses a windows-2022 runner. The windows-latest runner would also work.

The job starts by checking out the code then installs .NET 6 and the .NET MAUI workload just like the Android build job.

During preview we also needed to set up MSBuild but with GA we can now build .NET MAUI apps for Windows with the .NET CLI commands. 🥳

Again I want to create a release build and not restore dependencies during build. We use a standard dotnet publish command to build our .NET MAUI Windows app, to set the framework we want to build we use the -f net6.0-windows10.0.19041.0 argument. The framework must match the Target Framework specified for Windows in the application's project file.

The last step for this job is to upload the Windows app package as a build artifact.

iOS Build Job

# MAUI iOS Build
  build-ios:
    runs-on: macos-12
    name: iOS Build
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Setup .NET 6
        uses: actions/setup-dotnet@v2
        with:
          dotnet-version: 6.0.x

      - name: Install MAUI Workload
        run: dotnet workload install maui --ignore-failed-sources

      - name: Restore Dependencies
        run: dotnet restore src/MauiBeach/MauiBeach.csproj

      - name: Build MAUI iOS
        run: dotnet build src/MauiBeach/MauiBeach.csproj -c Release -f net6.0-ios --no-restore /p:buildForSimulator=True /p:packageApp=True /p:ArchiveOnBuild=False

      - name: Upload iOS Artifact
        uses: actions/upload-artifact@v3.1.0
        with:
          name: mauibeach-ios-ci-build
          path: src/MauiBeach/bin/Release/net6.0-ios/iossimulator-x64/**/*.app

Building a .NET MAUI iOS app requires macOS, Visual Studio 2022 and Xcode 13.3 so the iOS build job needs to use a macos-12 runner.

⚠ The macos-latest runner currently uses a macOS 11 image so will not work. ⚠

As before, the job starts by checking out the code then installs .NET 6 and the .NET MAUI workload.

Now we can restore our dependencies and build our app. Unlike the other build jobs we can't use dotnet publish for the iOS build job because it signs the app for distribution and fails if a provisioning profile is not present. I don't want to include that in this workflow so use dotnet build instead. To build an iOS app we need the -f net6.0-ios argument to set the framework.

Finally the job uploads the *.app folder as a build artifact.

MacCatalyst Build Job

# MAUI MacCatalyst Build
  build-mac:
    runs-on: macos-12
    name: MacCatalyst Build
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Setup .NET 6
        uses: actions/setup-dotnet@v2
        with:
          dotnet-version: 6.0.x

      - name: Install MAUI Workload
        run: dotnet workload install maui --ignore-failed-sources

      - name: Restore Dependencies
        run: dotnet restore src/MauiBeach/MauiBeach.csproj

      - name: Build MAUI MacCatalyst
        run: dotnet publish src/MauiBeach/MauiBeach.csproj -c Release -f net6.0-maccatalyst --no-restore -p:BuildIpa=True

      - name: Upload MacCatalyst Artifact
        uses: actions/upload-artifact@v3.1.0
        with:
          name: mauibeach-macos-ci-build
          path: src/MauiBeach/bin/Release/net6.0-maccatalyst/maccatalyst-x64/publish/*.pkg

Building a .NET MAUI app for MacCatalyst requires macOS, Visual Studio 2022 and Xcode 13.3 so the MacCatalyst build job needs to use a macos-12 runner.

⚠ The macos-latest runner currently uses a macOS 11 image so will not work. ⚠

The MacCatalyst build job is very similar to the other build jobs. Using the macos-12 runner it checks out the code then installs .NET 6 and the .NET MAUI workload.

We can use a standard dotnet publish command to build an app for MacCatalyst. For MacCatalyst the framework argument is -f net6.0-maccatalyst and we use the -p:BuildIpa=True argument to create a macOS app package.

The last step uploads the macOS app package as a build artifact.

And Finally...

The complete workflow can be found in my MAUI Beach repo:
👩‍💻 .github/workflows/ci-build.yml

And, you can see the workflow runs here. 🏗

If I had tests for this app they would be run as an extra step in each job between the build step and uploading the build artifacts.

This workflow could be expanded to create a CD workflow that releases a .NET MAUI app on each platform. This requires the relevant certificate, provisioning profile or keystore for each platform, which should be saved as secrets in GitHub and then copied to the runner before the build step. For Android a signing step is added after the build step but for the other platforms this is handled by the dotnet publish command. The process should be similar to that for Xamarin.Forms and you can find more information here.

Cover image includes a vector created by brgfx from www.freepik.com.

Edit Release is built with .NET 6 and Docker using GitHub Container Registry and sigstore.

Release Notes

• Signed the Docker image
• Updated libraries

How to Verify the Docker Image

1. Install sigstore/cosign.
2. Run: COSIGN_EXPERIMENTAL=1 cosign verify ghcr.io/irongut/editrelease:v1.2.0

$ COSIGN_EXPERIMENTAL=1 cosign verify ghcr.io/irongut/editrelease:v1.2.0

Verification for ghcr.io/irongut/editrelease:v1.2.0 --
The following checks were performed on each of these signatures:
  - The cosign claims were validated
  - Existence of the claims in the transparency log was verified offline
  - Any certificates were verified against the Fulcio roots.

In the JSON data that follows the docker-manifest-digest values should contain the hash sha256:a68ecd1ac7ba32ca07bc03b069f250200cf9e532e9496872aa4a3cb1d82bb167.

Links

• 🛍 GitHub Marketplace
• 👨‍💻 Repository

People vector created by pch.vector - www.freepik.com

The code for my .NET MAUI articles is available on GitHub: irongut/MauiBeach

Visual Studio 2022 Preview?

Although .NET MAUI is GA, Microsoft are still working on the tooling so preview versions of Visual Studio 2022 are still required. The completed .NET MAUI tooling should appear in a full release of Visual Studio 2022 in August for Windows and November for macOS.

Currently the required versions are Visual Studio 2022 17.3 Preview 2 on Windows or Visual Studio 2022 for Mac 17.3 Preview 2.1 on macOS. When installing select the .NET Multi-platform App UI development workload. If you also develop Xamarin.Forms applications ensure the optional Xamarin item is ticked; see VS2022 17.3 Preview 1.1 - Missing Xamarin SDKs for more details.

The Plan

There have been many changes to .NET MAUI since I last worked on MAUI Beach so I decided the best approach was to start fresh with a new project, update the code from the old project and then replace it in the repository. That way changes to required Nuget packages, project configuration and the platform specific files would all be handled and I would only need to make minor code changes.

This is a similar process to how I would convert a Xamarin.Forms app to .NET MAUI. When the .NET Upgrade Assistant gains MAUI support I will reappraise this opinion.

Creating a New .NET MAUI Project

Creating a new .NET MAUI app in Visual Studio 2022 is a simple process. Select MAUI from the Project Types drop down and Visual Studio presents you with three options - .NET MAUI App, .NET MAUI Blazor App and .NET MAUI Class Library. Select .NET MAUI App and click Next.

Visual Studio then asks for the project name, location and solution name, like any other .NET project. I gave the project and solution the same names as my original project but a different location.

Finally the Framework should be .NET 6.0 (Long-term support). Click Create and a new cross platform app is created from the .NET MAUI template.

The default template includes platform folders for Android, iOS, MacCatalyst, Tizen and Windows. I'm not interested in the Tizen platform so I deleted the Platforms/Tizen folder. There is also a Target Framework entry for Tizen in the project file but it is commented out so we can ignore it.

At this point my next step was to build and run the template app on all platforms to ensure my development setup was working correctly. Which it was, phew! 😅

Styles and Resources

Retracing my First Steps on MAUI Beach I decided to copy over my custom styles and colour palette to the new app first.

Back in .NET MAUI Preview 11 my styles and colours were all in one file: Resources/Styles/DefaultTheme.xaml

In .NET MAUI GA the default template provides two files: Resources/Styles/Colors.xaml and Resources/Styles/Styles.xaml.

I replaced the contents of Colors.xaml with my colour pallete, removing all the default values. I also copied over the contents of Platforms/Android/Resources/values/colors.xml from the old project to the new project.

Styles was slightly more complicated, checking the template styles against my previous custom styles I spotted an extra property that I had not set for Shell (TabBarForegroundColor) and also decided to add a style for TabbedPage, based on the style in the template.

There have been some changes in the Resources folder structure too. Previously the images used to construct the application icon were in the Resources folder, now they live in Resources/AppIcon. Similarly the splash screen image has now moved to the Resources/Splash folder. I copied the images from my old project to the relevant locations in the new project and in Visual Studio set their Build Action properties.

The template project provides two custom fonts but I'm not using both of them in MAUI Beach. I deleted OpenSans-Semibold.ttf from the Resources/Fonts folder and removed the line of code that adds it to the app from MauiProgram.cs.

Missing Image Build Issue

Initially I deleted the images provided by the MAUI template project but when I came to build my app I ran into errors that Resizetizer couldn't find the old images for the icon and splash screen despite them not being listed anywhere in the project file. Resizetizer is part of the tooling that creates the app icon, splash screen and other images for your app so hopefully this issue will be fixed as Visual Studio 2022 is updated. To get past it I restored the template images and was able to build my app, after that first build I was able to delete them again and everything worked. 🤷‍♂️

The Project File

With my resouces in place I decided it was time to update the project file - MauiBeach.csproj. Examining the new project file I noticed a number of changes from the MAUI preview version, including the syntax for target frameworks and supported OS versions, so it was definitely worth recreating the app from scratch. I copied over my Application Title and Id then setup my icon and splash screen using the new paths to the images.

Pages, ViewModels and Services

Now we get into the actual C# code.

I was able to copy my ViewModels directly from the old project. The only modification required was to remove some using statements that are no longer needed because implicit usings is turned on in the new project file.

MAUI Beach contains one service - DeviceInfoService, which improves on .NET MAUI's built-in DeviceInfo class and is implemented using platform specific partial classes. I'll come back to this in the next section but for now I copied the cross platform partial class Services/DeviceInfoService.cs into the new project.

MAUI Beach contains three pages so I created three new pages with the same names in the new project. When creating pages be sure to pick .NET MAUI Content Page (XAML) not Content Page (XAML) or you'll get the Xamarin version! (Yes, I did that wrong. 🤦‍♂️) I copied the contents of the XAML and C# code-behind files from my old project into the new pages and modified the using statements.

Platform Specific Code

MAUI Beach uses platform specific partial classes to implement DeviceInfoService. I copied the Platforms/<platform>/Services/DeviceInfoService.cs files into the new project. No changes were required to the Android and Windows versions of these classes. The MacCatalyst version only required me to delete the existing using statement.

The iOS version of DeviceInfoService.cs required an additional change as Visual Studio recommended I change the marshalling argument for the sysctlbyname system call from LPStr to LPWStr.

The About page in MAUI Beach has two buttons that open websites in the default browser which requires permission on Android. I copied the required intent into Platforms/Android/AndroidManifest.xml from the old project.

Shell

The UI for MAUI Beach is based around a flyout menu built using Shell. In the original version this was defined in App.xaml but the new template provides AppShell.xaml. Copying the XAML into the new file was straightforward with no surprises.

Flyout Menu Issue

When I ran MAUI Beach on Windows I discovered a problem with the flyout menu items - the images were to the right of where they should be and the text labels were not visible at all! 😲 The menu items were defined as a Grid with two columns using proportional or * sizing:

<Grid ColumnDefinitions="0.25*, 0.75*"
      Style="{StaticResource shellItem}"
      Padding="0, 10">

It seems that .NET MAUI is now using the full width of the window to calculate those sizes instead of the width of the flyout menu as it did before. Once I realised that it was simple to fix by setting a fixed width for the first column:

<Grid ColumnDefinitions="85, *"
      Style="{StaticResource shellItem}"
      Padding="0, 10">

Update Complete!

With all the code moved over, and the minor image issue mentioned earlier fixed, I was able to build and run the new version of MAUI Beach on all platforms. And, once I fixed the flyout menu items it even looks better than the old preview version because bugs have been fixed. 😁

In order to maintain version history I deleted my original project from the Git repository and copied the new project in its place. I ran into some issues with missing resources when I tried to build & run the moved project, I reset the Build Action properties of all the resources and cleaned up the changes that caused in the project file. Another Clean & Rebuild and my app was working again. 🎉

And Finally...

After committing and pushing my changes I created a Pull Request and discovered my CI builds were broken on iOS and Windows. I'll write about building a .NET MAUI app with GitHub Actions again soon but if you want a sneak peak 🕵️‍♀️ you can find my working CI Build workflow on GitHub.

Cover image includes a vector created by brgfx from www.freepik.com.

Starting with an explanation of the .NET MAUI architecture and creation of a simple app, the course includes modules on designing your UI with XAML, using Shell to create tab or flyout based apps, consuming REST services and even storing data with SQLite. The content was easy to follow and the examples were good but I wouldn't recommend it for a complete novice with .NET and Visual Studio because I did run into a few issues and errors (all reported of course) that could confuse a beginner.

I'll write more about my experiences learning .NET MAUI soon but first I plan to watch video courses from Gerald Versluis and James Montemagno. 📺

Cover image includes a vector created by upklyak from www.freepik.com.

1. Open the Visual Studio Installer and click the Modify button on your Visual Studio 2022 Preview installation.
2. On the right-hand side open the .NET Multi-platform App UI node.
3. Open the Optional node under .NET MAUI.
4. Check the Xamarin SDKs node to install the Xamarin SDKs.
5. Click Modify.

The Visual Studio installer will now download and re-install your missing Xamarin SDKs. 🥳

Cover image includes a background vector created by sentavio from www.freepik.com.

Live Sessions

There were two live sessions about .NET MAUI and Blazor Hybrid apps which now have recordings available.

Build native apps for any device with .NET and Visual Studio

Tim Heuer | Maddy Montaquila | Leslie Richardson | Daniel Roth

In the initial segment, Tim Heuer discusses the fast adoption of .NET 6 by the community and features that aid with cross platform development like unified base libraries & SDK, Hot Reload support everywhere and Apple Silicon support. He then announces the release of .NET MAUI, providing a summary of its features, and introduces the .NET Podcasts reference application.

Starting at 07:30, Maddy Montaquila shows us how to get started with .NET MAUI development. Maddy demonstrates the features of MAUI including the single project solution, creating shared icons and splash images for every platform, XAML Live Preview, the Live Visual Tree and Hot Reload for XAML and C# on Android, iOS and Windows.

Starting at 20:30, Tim introduces Hybrid apps with Blazor & .NET MAUI which allow you to combine web and native UI technology in a native client application. Built on top of .NET MAUI, Blazor Hybrid apps have access to the device to call native APIs, access the file system or use native controls if you want them.

At 21:38 Dan Roth demonstrates the features of a modern web app built with Blazor using the .NET Podcasts application. Dan then shows us how to get started building a hybrid app with Blazor & .NET MAUI using Blazor components in a native MAUI app. Maddy joins Dan to demonstrate the Listen Together feature in the .NET MAUI version of the podcasts app which is built using a Blazor web view and Blazor components.

Starting at 30:30, Tim introduces Visual Studio 2022 and discusses some of the new features that help with cross platform development including WSL integration, IntelliCode for whole line completions and suggestions for common code refactorings as you type and improved integration with GitHub and Azure. He also announces Visual Studio 2022 17.3 Preview 2 which will natively support building and debugging ARM64 apps on ARM-based processors with Windows 11 and upcomming support for ARM in .NET Framework v4.8.1.

At 33:14 Leslie Richardson shows us some of the new tools in Visual Studio 2022 including IntelliCode, Hot Reload, temporary breakpoints and the new built-in spell checker. Leslie also demonstrates Port Tunneling, an upcomming feature that makes it easier to debug a backend API from a mobile device. If your organisation uses Azure Active Directory you can signup for the Microsoft Tunneling Private Preview.

Starting at 37:50, Tim discusses how Azure can help you build a backend for your mobile apps using .NET 6. Along the way he touches on Azure Static Web Apps, Azure Functions, Azure Container Apps and using GitHub Actions to create a code to cloud pipeline with Visual Studio 2022. He also demonstrates two new features of GitHub - GitHub Advanced Security with push protection to help prevent unwanted secrets being committed into your repo and Actions Job Summaries which append job information to your workflows such as test results and visualisation.

Finally at 49:15 Tim announces the latest .NET 7 Preview 4 release and .NET Conf 2022 on 8th - 10th November.

Ask the Experts: .NET and Visual Studio

Tim Heuer | Mads Kristensen | Maddy Montaquila | David Ortinau | Daniel Roth

This was a Q&A session on Teams following the session above which summarised the earlier announcements and discussed .NET MAUI, Blazor, hybrid apps and Visual Studio 2022.

There are too many great questions and answers for me to summarise so I suggest you watch it. In particular Dave & Maddy answer questions about moving from Xamarin Forms to MAUI, updating Nuget libraries, testing tool support and what's next for MAUI.

On-Demand Sessions

Several shorter on-demand sessions are of interest to developers of .NET MAUI, Xamarin, Blazor Hybrid and React Native apps. There are also sessions for developers looking to publish Android apps on Windows 11 via the Amazon AppStore and Windows Subsystem for Android or Windows apps on the Microsoft Store.

.NET MAUI - Updates and Roadmap

Maddy Montaquila

.NET Multi-platform App UI has shipped! Maddy Montaquila explains what .NET MAUI is, how to get it, new capabilities, changes from Xamarin and what to look forward to in coming releases. Maddy also demonstrates improvements in Android startup performance versus Xamarin Forms and Xamarin Android.

Although .NET MAUI is GA the tooling is still in preview so you will require the latest preview version of Visual Studio 2022 on Windows (17.3) or Mac (17.1). On Windows the tooling should GA in August and on Mac in November.

This is a really good session to watch, with Maddy's usual enthusiasm and lots of information for cross platform .NET developers.

Native client apps with Blazor Hybrid

Daniel Roth

Blazor is expanding beyond the web to enable support for building native client apps using a hybrid of web technologies and .NET. In this session Dan Roth explains the Blazor hosting model, discusses the latest Blazor improvements in .NET 6 and how to use your Blazor skills to build native apps with .NET MAUI. Dan shows us how to get started building a hybrid app with Blazor & .NET MAUI, using native device APIs and Blazor Hybrid UI support for modernising WPF and WinForms apps. Finally he discusses the new features coming to Blazor in .NET 7.

This session is largely an expansion of Dan's segment in the main live session but if you're interested in Blazor & MAUI hybrid apps it is worth watching.

Make your cross-platform apps best on Windows

Maddy Montaquila | Steven Moyes

Extend your cross platform apps with native capabilities to build more engaging experiences. In this session, Steven Moyes and Maddy Montaquila discuss options for cross platform app development using React Native and .NET MAUI and why you might choose one platform over the other. Many of Microsoft's own apps are built using React Native including parts of Office, the XBox app on PC and Power Apps.

This session is more of an overview rather than technical but would be a good introduction if you don't know anything about React Native or .NET MAUI.

Bring your Android apps to Windows

Andrew Leader | Hamza Usmani | Mario Vivani (Amazon)

Hamza Usmani and Andrew Leader discuss publishing your existing Android apps on Windows 11 using Windows Subsystem for Android. They show how to install the Amazon AppStore, which installs WSA in the background, how to install an app from the AppStore and how to debug your app using WSA from Android Studio. Mario Vivani from Amazon explains how to sign up for the Amazon AppStore and get progress updates. He also shows how to identify that your app was installed from the Amazon AppStore when you need to use Amazon specific APIs instead of Google ones. They also discuss best practices and optimisations.

This session is really targetted at native Android developers but if you are thinking about publishing the Android version of a Xamarin Forms or Xamarin Android application on Windows 11 using WSA it is still useful.

Note: Windows Subsystem for Android is currently in preview and only available in the U.S. market. Developer participation in the Amazon AppStore on Windows 11 is in closed beta and only available to a selection of apps.

Finding your success in the Microsoft Store

Pete Brown

Pete Brown discusses tips and techniques for getting your app through the certification process in the Microsoft Store on Windows. Including common certification blockers, a few specialized situations, tips for navigating the certification process itself and what to do if you need support.

This session isn't specifically targetted at Xamarin or .NET MAUI developers but if you are planning to publish your cross platform app on Windows it is worth watching.

I hope that the announcements at Microsoft Build later this month will spark my creativity and enthusiasm again. Till then here is one of my favourite poems written by Emma, who wrote and performed poetry at many venues in our home city.

Prelude To A Dream

(Insomnia: Midnight)

By Emma Pandolfi (1980 - 2022)

Oh, deep exquisite embrace of sleep,
I invite you to take me.
Take me away,
slow but sure
to the land of Nod.
In the land of dreams.

Morpheus, dear Morpheus
Gothic prince of the night.
As delight fades to delirium
and dreams are my destiny.
So take me now and
keep me safe
in your land of dreams
tonight.

Oh, deep exquisite embrace of sleep,
I implore you to take me.
Carry me gently
but carry me swift
through the land of Nod.
In the land of dreams.

Morpheus, dear Morpheus
endless giver of dreams.
Give unto me,
I beg of you.
The sleep of the just
tonight.

Oh, deep exquisite embrace of sleep
I urge you to take me.
Whisk me away
to sub-conscious adventures
in the land of Nod.
In the land of dreams.

What is .NET Frontend Day?

.NET Frontend Day is a virtual conference that started in 2021. It is organised and hosted by the creators of two of my favourtie podcasts - Jessica & Jimmy Engström from Coding After Work and Daniel Hindrikes from App in the Cloud. The first edition had eight speakers and some great sessions for .NET desktop and web developers. All the sessions from 2021 are available on YouTube.

This year's conference followed a similar format but had a strong focus on .NET MAUI and Blazor. Speakers included the incredibly prolific Gerald Versluis (if you haven't subscribed to his YouTube channel you should!), Maddy Leger Montaquila, James Montemagno and Daniel Roth from Microsoft, Sam Basu from Progress Software (Telerik) and MVPs Stacy Cashmore, Ed Charbeneau and Layla Porter.

Thanks to the hosts and all the speakers for a great afternoon of content!

.NET Frontend Day 2022 Sessions

• Introduction to App Development with .NET MAUI - Gerald Versluis
• Authenticating in Azure Static Web Apps - Stacy Cashmore
• Writing JavaScript for C#'s Blazor - Ed Charbeneau
• Top Tips For Blazor - Layla Porter
• Visual Studio 2022 and .NET MAUI - Maddy Leger Montaquila
• Migration & Modernization with .NET MAUI - Sam Basu
• Go Hybrid across Web, Desktop, & Mobile with Blazor Hybrid - James Montemagno
• Blazor for the Web and Beyond - Daniel Roth

A playlist for all 2022 sessions is available on YouTube.

Introduction to App Development with .NET MAUI

Gerald Versluis

.NET MAUI enables developers to create cross platform apps for Android, iOS, MacOS, and Windows. In this session, Gerald introduces .NET MAUI, explains how it fits into the .NET ecosystem, how it differs from Xamarin and how to get started building great cross platform apps.

Visual Studio 2022 and .NET MAUI

Maddy Leger Montaquila

Visual Studio 2022 shipped at the end of last year with a focus on speed and developer productivity, Visual Studio 2022 for Mac is being rebuilt from the ground up and .NET MAUI improves the developer experience for cross platform development. Maddy demonstrates how to be more productive building your .NET MAUI apps and provides the latest updates on the VS 2022, VS 2022 for Mac and .NET MAUI developer experiences.

Migration & Modernization with .NET MAUI

Sam Basu

.NET MAUI is the evolution of Xamarin.Forms running on .NET 6 but what if you have existing mobile apps built with Xamarin? How much work will it be to migrate to .NET MAUI? Would the Upgrade Assistants help? What about your custom renderers and what are MAUI handlers? Could Blazor help you share code with your web apps? Sam covers this and more with a real-world look at migration strategies and app modernisation with .NET MAUI.

Go Hybrid across Web, Desktop, & Mobile with Blazor Hybrid

James Montemagno

.NET MAUI Blazor apps enable you to re-use all of your Blazor knowledge, razor components, business logic and Blazor libraries to create native apps for desktop and mobile devices. Possibly the most friendly guy in the world 😄, James shows us how to wrap your existing Blazor web app or go full hybrid, including native UI and APIs, to create the best apps for any platform.

Blazor for the Web and Beyond

Daniel Roth

Blazor enables .NET developers to build applications using web UI for any platform or device. In this session, Dan looks at the many improvements to Blazor in .NET 6, the integration of Blazor into .NET MAUI and the future of Blazor. This is a must-watch session for the extensive Q&A at the end.

As always, the code for my .NET MAUI articles is available on GitHub: irongut/MauiBeach

The Problem

Xamarin Essentials and MAUI Essentials include a DeviceInfo class which provides information about the device the application is running on but on Android it doesn't include the SDK version and on iOS it reports the model using Apple hardware identifiers, which are not very user friendly. In my Xamarin.Forms applications I use DependencyService and platform specific code to improve on the information provided by Xamarin Essentials, here I'll use partial classes to achieve the same results in .NET MAUI.

The Solution

In C# we normally write a class in a single file but it is possible to split a class over multiple files that are combined when the application is compiled by using partial classes. A partial class is created by using the partial keyword and every part of the partial class must be in the same assembly and namespace. Partial classes are part of the code that enables XAML to work so you will have used them before even if you didn't realise it.

Cross Platform Partial Class

First we need to create a cross platform partial class that defines partial methods which will be implemented by our platform specific partial classes, think of this class as like an interface.

namespace MauiBeach.Services;

internal static partial class DeviceInfoService
{
    internal static partial string Model();

    internal static partial string Platform();
}

Our platform specific code will return two strings:

• Model such as iPhone 13 Pro
• Platform which will include the platform name and version, for example Android 9 (API 28 - Pie)

Remember, all the parts of our partial class must be in the same namespace - in this case MauiBeach.Services.

Android Partial Class

The Android implementation of our platform specific code goes in the Platforms\Android folder hierarchy.

using Android.OS;

namespace MauiBeach.Services;

internal static partial class DeviceInfoService
{
    internal static partial string Model() => Build.Model;

    internal static partial string Platform()
    {
        return $"Android {Build.VERSION.Release} (API {AndroidSDK} - {AndroidCodename()})";
    }

    private static string AndroidCodename()
    {
        return (int)Build.VERSION.SdkInt switch
        {
            (int)BuildVersionCodes.Lollipop or (int)BuildVersionCodes.LollipopMr1 => "Lollipop",
            (int)BuildVersionCodes.M => "Marshmallow",
            (int)BuildVersionCodes.N or (int)BuildVersionCodes.NMr1 => "Nougat",
            (int)BuildVersionCodes.O or (int)BuildVersionCodes.OMr1 => "Oreo",
            (int)BuildVersionCodes.P => "Pie",
            (int)BuildVersionCodes.Q => "Q",
            (int)BuildVersionCodes.R => "R",
            (int)BuildVersionCodes.S => "S",
            32 => "Sv2",
            _ => "Unknown",
        };
    }

    private static int AndroidSDK => (int)Build.VERSION.SdkInt;
}

On Android the information we want is available from the Build class. I've only included SDK codenames for versions of Android supported by .NET MAUI.

iOS Partial Class

The iOS implementation of our platform specific code goes in the Platforms\iOS folder hierarchy.

using Foundation;
using Microsoft.Maui.Essentials;
using ObjCRuntime;
using System;
using System.Runtime.InteropServices;
using UIKit;

namespace MauiBeach.Services;

internal static partial class DeviceInfoService
{
    // based on code from https://github.com/dannycabrera/Get-iOS-Model

    private const string HardwareProperty = "hw.machine";

    [DllImport(Constants.SystemLibrary)]
    private static extern int sysctlbyname([MarshalAs(UnmanagedType.LPStr)] string property,
                                            IntPtr output,
                                            IntPtr oldLen,
                                            IntPtr newp,
                                            uint newlen);

    internal static partial string Model()
    {
        string version = FindVersion();
        if (version == "i386" || version == "x86_64")
        {
            return GetModel(NSProcessInfo.ProcessInfo.Environment["SIMULATOR_MODEL_IDENTIFIER"].ToString()) + " Simulator";
        }
        return GetModel(version);
    }

    internal static partial string Platform() => $"{DeviceInfo.Platform} {UIDevice.CurrentDevice.SystemVersion}";

    private static string FindVersion()
    {
        try
        {
            // get the length of the string that will be returned
            var pLen = Marshal.AllocHGlobal(sizeof(int));
            _ = sysctlbyname(HardwareProperty, IntPtr.Zero, pLen, IntPtr.Zero, 0);

            var length = Marshal.ReadInt32(pLen);

            // check to see if we got a length
            if (length == 0)
            {
                Marshal.FreeHGlobal(pLen);
                return "Unknown";
            }

            // get the hardware string
            var pStr = Marshal.AllocHGlobal(length);
            _ = sysctlbyname(HardwareProperty, pStr, pLen, IntPtr.Zero, 0);

            // convert the native string into a C# string
            var hardwareStr = Marshal.PtrToStringAnsi(pStr);

            // cleanup
            Marshal.FreeHGlobal(pLen);
            Marshal.FreeHGlobal(pStr);

            return hardwareStr;
        }
        catch (Exception ex)
        {
            Console.WriteLine("DeviceHardware.Version Ex: " + ex.Message);
        }

        return "Unknown";
    }

    private static string GetModel(string version)
    {
        if (version.StartsWith("iPhone"))
        {
            switch (version)
            {
                case "iPhone14,2":
                    return "iPhone 13 Pro";
                case "iPhone14,3":
                    return "iPhone 13 Pro Max";
                case "iPhone14,4":
                    return "iPhone 13 mini";
                case "iPhone14,5":
                    return "iPhone 13";
                case "iPhone13,1":
                    return "iPhone 12 mini";
                case "iPhone13,2":
                    return "iPhone 12";
                case "iPhone13,3":
                    return "iPhone 12 Pro";
                case "iPhone13,4":
                    return "iPhone 12 Pro Max";
                case "iPhone12,8":
                    return "iPhone SE (2nd generation)";
                case "iPhone12,5":
                    return "iPhone 11 Pro Max";
                case "iPhone12,3":
                    return "iPhone 11 Pro";
                case "iPhone12,1":
                    return "iPhone 11";
                case "iPhone11,2":
                    return "iPhone XS";
                case "iPhone11,4":
                case "iPhone11,6":
                    return "iPhone XS Max";
                case "iPhone11,8":
                    return "iPhone XR";
                case "iPhone10,3":
                case "iPhone10,6":
                    return "iPhone X";
                case "iPhone10,2":
                case "iPhone10,5":
                    return "iPhone 8 Plus";
                case "iPhone10,1":
                case "iPhone10,4":
                    return "iPhone 8";
                case "iPhone9,2":
                case "iPhone9,4":
                    return "iPhone 7 Plus";
                case "iPhone9,1":
                case "iPhone9,3":
                    return "iPhone 7";
                case "iPhone8,4":
                    return "iPhone SE";
                case "iPhone8,2":
                    return "iPhone 6S Plus";
                case "iPhone8,1":
                    return "iPhone 6S";
                case "iPhone7,1":
                    return "iPhone 6 Plus";
                case "iPhone7,2":
                    return "iPhone 6";
                case "iPhone6,2":
                    return "iPhone 5S Global";
                case "iPhone6,1":
                    return "iPhone 5S GSM";
                case "iPhone5,4":
                    return "iPhone 5C Global";
                case "iPhone5,3":
                    return "iPhone 5C GSM";
                case "iPhone5,2":
                    return "iPhone 5 Global";
                case "iPhone5,1":
                    return "iPhone 5 GSM";
            }
        }

        if (version.StartsWith("iPod"))
        {
            switch (version)
            {
                case "iPod9,1":
                    return "iPod touch 7G";
                case "iPod7,1":
                    return "iPod touch 6G";
            }
        }

        if (version.StartsWith("iPad"))
        {
            switch (version)
            {
                case "iPad14,2":
                    return "iPad mini (6th generation) Wi-FI + Cellular";
                case "iPad14,1":
                    return "iPad mini (6th generation) Wi-FI";
                case "iPad13,11":
                case "iPad13,10":
                    return "iPad Pro (12.9-inch) (5th generation) Wi-Fi + Cellular";
                case "iPad13,9":
                case "iPad13,8":
                    return "iPad Pro (12.9-inch) (5th generation) Wi-Fi";
                case "iPad13,7":
                case "iPad13,6":
                    return "iPad Pro (11-inch) (3rd generation) Wi-Fi + Cellular";
                case "iPad13,5":
                case "iPad13,4":
                    return "iPad Pro (11-inch) (3rd generation) Wi-Fi";
                case "iPad13,2":
                    return "iPad Air (4th generation) Wi-Fi + Cellular";
                case "iPad13,1":
                    return "iPad Air (4th generation) Wi-Fi";
                case "iPad12,2":
                    return "iPad (9th Generation) Wi-Fi + Cellular";
                case "iPad12,1":
                    return "iPad (9th generation) Wi-Fi";
                case "iPad11,7":
                    return "iPad (8th Generation) Wi-Fi + Cellular";
                case "iPad11,6":
                    return "iPad (8th Generation) Wi-Fi";
                case "iPad11,4":
                    return "iPad Air (3rd generation) Wi-Fi + Cellular";
                case "iPad11,3":
                    return "iPad Air (3rd generation) Wi-Fi";
                case "iPad11,2":
                    return "iPad mini (5th generation) Wi-Fi + Cellular";
                case "iPad11,1":
                    return "iPad mini (5th generation) Wi-Fi";
                case "iPad8,12":
                    return "iPad Pro (12.9-inch) (4th generation) Wi-Fi + Cellular";
                case "iPad8,11":
                    return "iPad Pro (12.9-inch) (4th generation) Wi-Fi";
                case "iPad8,10":
                    return "iPad Pro (11-inch) (2nd generation) Wi-Fi + Cellular";
                case "iPad8,9":
                    return "iPad Pro (11-inch) (2nd generation) Wi-Fi";
                case "iPad8,8":
                    return "iPad Pro 12.9-inch (3rd Generation)";
                case "iPad8,7":
                    return "iPad Pro 12.9-inch (3rd generation) Wi-Fi + Cellular";
                case "iPad8,6":
                case "iPad8,5":
                    return "iPad Pro 12.9-inch (3rd Generation)";
                case "iPad8,4":
                    return "iPad Pro 11-inch";
                case "iPad8,3":
                    return "iPad Pro 11-inch Wi-Fi + Cellular";
                case "iPad8,2":
                    return "iPad Pro 11-inch";
                case "iPad8,1":
                    return "iPad Pro 11-inch Wi-Fi";
                case "iPad7,12":
                    return "iPad (7th generation) Wi-Fi + Cellular";
                case "iPad7,11":
                    return "iPad (7th generation) Wi-Fi";
                case "iPad7,6":
                    return "iPad (6th generation) Wi-Fi + Cellular";
                case "iPad7,5":
                    return "iPad (6th generation) Wi-Fi";
                case "iPad7,4":
                    return "iPad Pro (10.5-inch) Wi-Fi + Cellular";
                case "iPad7,3":
                    return "iPad Pro (10.5-inch) Wi-Fi";
                case "iPad7,2":
                    return "iPad Pro 12.9-inch (2nd generation) Wi-Fi + Cellular";
                case "iPad7,1":
                    return "iPad Pro 12.9-inch (2nd generation) Wi-Fi";
                case "iPad6,12":
                    return "iPad (5th generation) Wi-Fi + Cellular";
                case "iPad6,11":
                    return "iPad (5th generation) Wi-Fi";
                case "iPad6,8":
                    return "iPad Pro 12.9-inch Wi-Fi + Cellular";
                case "iPad6,7":
                    return "iPad Pro 12.9-inch Wi-Fi";
                case "iPad6,4":
                    return "iPad Pro (9.7-inch) Wi-Fi + Cellular";
                case "iPad6,3":
                    return "iPad Pro (9.7-inch) Wi-Fi";
                case "iPad5,4":
                    return "iPad Air 2 Wi-Fi + Cellular";
                case "iPad5,3":
                    return "iPad Air 2 Wi-Fi";
                case "iPad5,2":
                    return "iPad mini 4 Wi-Fi + Cellular";
                case "iPad5,1":
                    return "iPad mini 4 Wi-Fi";
                case "iPad4,9":
                    return "iPad mini 3 Wi-Fi + Cellular (TD-LTE)";
                case "iPad4,8":
                    return "iPad mini 3 Wi-Fi + Cellular";
                case "iPad4,7":
                    return "iPad mini 3 Wi-Fi";
                case "iPad4,6":
                    return "iPad mini 2 Wi-Fi + Cellular (TD-LTE)";
                case "iPad4,5":
                    return "iPad mini 2 Wi-Fi + Cellular";
                case "iPad4,4":
                    return "iPad mini 2 Wi-Fi";
                case "iPad4,3":
                    return "iPad Air Wi-Fi + Cellular (TD-LTE)";
                case "iPad4,2":
                    return "iPad Air Wi-Fi + Cellular";
                case "iPad4,1":
                    return "iPad Air Wi-Fi";
                case "iPad3,6":
                    return "iPad (4th generation) Wi-Fi + Cellular (MM)";
                case "iPad3,5":
                    return "iPad (4th generation) Wi-Fi + Cellular";
                case "iPad3,4":
                    return "iPad (4th generation) Wi-Fi";
            }
        }

        return string.IsNullOrWhiteSpace(version) ? "Unknown" : version;
    }
}

The iOS implemntation is a lot more complicated because Apple does not provide an API for developers to get the model of a device. The hw.machine string provides a hardware identifier like iPhone10,6 which we need to map to the device model. Apple doesn't provide official mappings but non-official mappings can be found at The iPhone Wiki or Danny Cabrera's Get iOS Model project. My mapping is based on Danny's but I only include devices capable of running versions of iOS supported by .NET MAUI.

Windows Partial Class

The Windows implementation of our platform specific code goes in the Platforms\Windows folder hierarchy.

using Windows.Security.ExchangeActiveSyncProvisioning;
using Windows.System.Profile;

namespace MauiBeach.Services;

internal static partial class DeviceInfoService
{
    internal static partial string Model() => new EasClientDeviceInformation().SystemProductName;

    internal static partial string Platform() => $"UWP {GetVersionString()}";

    private static string GetVersionString()
    {
        var version = AnalyticsInfo.VersionInfo.DeviceFamilyVersion;

        if (ulong.TryParse(version, out var v))
        {
            var v1 = (v & 0xFFFF000000000000L) >> 48;
            var v2 = (v & 0x0000FFFF00000000L) >> 32;
            var v3 = (v & 0x00000000FFFF0000L) >> 16;
            var v4 = v & 0x000000000000FFFFL;
            return $"{v1}.{v2}.{v3}.{v4}";
        }

        return version;
    }
}

The Android and iOS implementations are the ones where we want more information and the Windows implementation is very similar to the way Xamarin / MAUI Essentials works.

MacCatalyst Partial Class

The MacCatalyst implementation of our platform specific code goes in the Platforms\MacCatalyst folder hierarchy.

using Microsoft.Maui.Essentials;

namespace MauiBeach.Services;

internal static partial class DeviceInfoService
{
    internal static partial string Model() => DeviceInfo.Model;

    internal static partial string Platform() => $"{DeviceInfo.Platform} {DeviceInfo.VersionString}";
}

I have no experience with MacCatalyst but if a MAUI app targets a platform it must include an implementation of the cross platform partial class for that platform. In order to fulfil that condition we simply return values from MAUI Essentials' DeviceInfo class. If that proves to be insufficient in future it will be easy to expand this class to provide more information.

Final Thoughts

Using partial classes to write platform specific code in .NET MAUI is quick to learn and I think slightly easier than the old DependencyService in Xamarin.Forms. And, most of the code in this article is copied and pasted from my Xamarin code so it is also easy to change from the old way to this new way of writing platform specific code. 🎉

Cover image includes a vector created by brgfx from www.freepik.com.

Edit Release is built with C# and Docker and uses GitHub Container Registry.

Edit Release v1.1.0 Release Notes

• Updates Action to .NET 6
• Reduces Docker image layers
• Disables .NET diagnostics
• Switch to file scoped namespaces

• 🛍 GitHub Marketplace
• 👨‍💻 Repository

People vector created by pch.vector - www.freepik.com

⚠ Warning! Out of Date Content Ahead! ⚠

Since the GA release of .NET MAUI the build process has changed and the workarounds required below are no longer needed. This article has been superceeded by my new article Build .NET MAUI apps with GitHub Actions.

Preamble

We need a .NET MAUI app for our workflow to build so I will be using my demo app Maui Beach. Because .NET MAUI is in preview we will be using preview versions of .NET and MSBuild so our app must be compatible with the latest preview version of .NET MAUI. Currently this is Preview 11, I explain how to install Preview 11 and update your app in my article Upgrading to .NET MAUI Preview 11.

This is a CI build workflow without any testing, signing or deployment steps and will build our .NET MAUI app for Android, iOS, MacCatalyst and Windows in separate jobs that will run in parallel. Each build job will take 4 - 7 minutes to run and we will be using Windows and MacOS runners which are charged at an increased rate so be aware this workflow can really eat into your Actions minutes.

Set up the Workflow

The first part of our CI build is standard stuff for GitHub Actions - set the action name, what events it responds to and any environment variables.

name: CI Build

on:
  push:
    branches: [ master ]
    paths-ignore:
      - '**/*.md'
      - '**/*.gitignore'
      - '**/*.gitattributes'
  pull_request:
    branches: [ master ]
  workflow_dispatch:
permissions:
  contents: read

env:
  DOTNET_NOLOGO: true                     # Disable the .NET logo
  DOTNET_SKIP_FIRST_TIME_EXPERIENCE: true # Disable the .NET first time experience
  DOTNET_CLI_TELEMETRY_OPTOUT: true       # Disable sending .NET CLI telemetry

As you can see our workflow will respond to push and pull request events on the master branch and has a manual workflow_dispatch trigger. I've also included a little trick I learned recently, to prevent unnecessary builds I've excluded the push event running when the only changes involve markdown files, .gitignore or .gitattributes.

The environment variables tell the .NET CLI not to show the logo, to skip the first time experience and disable telemetry. This should help improve build times.

Android Build Job

  build-android:
    runs-on: windows-2022
    name: Android Build
    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: Setup .NET 6
        uses: actions/setup-dotnet@v1
        with:
          dotnet-version: 6.0.x
          include-prerelease: true

      - uses: actions/setup-java@v2
        with:
          distribution: 'microsoft'
          java-version: '11'

      - name: Install MAUI Workloads
        run: |
          dotnet workload install android --ignore-failed-sources
          dotnet workload install maui --ignore-failed-sources

      - name: Restore Dependencies
        run: dotnet restore src/MauiBeach/MauiBeach.csproj

      - name: Build MAUI Android
        run: dotnet build src/MauiBeach/MauiBeach.csproj -c Release -f net6.0-android --no-restore

      - name: Upload Android Artifact
        uses: actions/upload-artifact@v2.3.1
        with:
          name: android-ci-build
          path: src/MauiBeach/bin/Release/net6.0-android/*Signed.a*

Building a .NET MAUI app for Android can be done on MacOS or Windows so our build will run on Windows since that uses less minutes. Building .NET 6 apps requires Visual Studio 2022 so we must use a windows-2022 runner.

We start by checking out the code as normal and then install .NET 6. Because MAUI is still in preview we need to install the latest pre-release version of .NET 6.

Building a .NET MAUI app for Android requires JDK 11 so that is our next step. I've picked the Microsoft distribution of JDK 11.

The .NET MAUI workloads are not included in GitHub's windows-2022 runner yet so we need to install them too. To build an Android app we need the Android and MAUI workloads.

Now we can get to the build part of the workflow - restore dependencies and build the app. We can use a standard dotnet build command to build our app for Android. The important option here is -f net6.0-android to set the framework we want to build. I like my CI builds to be release builds so I've set the option -c Release as well as --no-restore so we only restore our dependencies once.

Finally we upload our build artifacts, I've chosen to upload both AAB and APK packages.

Windows Build Job

  build-windows:
    runs-on: windows-2022
    name: Windows Build
    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: Setup .NET 6
        uses: actions/setup-dotnet@v1
        with:
          dotnet-version: 6.0.x
          include-prerelease: true

      - name: Setup MSBuild
        uses: microsoft/setup-msbuild@v1.1
        with:
          vs-prerelease: true

      - name: Install MAUI Workloads
        run: |
          dotnet workload install maui --ignore-failed-sources

      - name: Restore Dependencies
        run: dotnet restore src/MauiBeach/MauiBeach.csproj

      - name: Build MAUI Windows
        run: msbuild src/MauiBeach/MauiBeach.csproj -r -p:Configuration=Release -p:RestorePackages=false -p:TargetFramework=net6.0-windows10.0.19041 /p:GenerateAppxPackageOnBuild=true

      - name: Upload Windows Artifact
        uses: actions/upload-artifact@v2.3.1
        with:
          name: windows-ci-build
          path: src/MauiBeach/bin/Release/net6.0-windows*/**/MauiBeach*.msix

Building a .NET app for Windows requires Windows and .NET 6 requires Visual Studio 2022 so we will use a windows-2022 runner for our Windows build job as well.

Again we start by checking out the code and install the latest pre-release version of .NET 6.

Using dotnet build to build a .NET MAUI app for Windows doesn't work with the current previews of .NET MAUI so for this job we will need to use MSBuild. We need the latest pre-release version of MSBuild so that is our next step.

The .NET MAUI workloads are not included in GitHub's windows-2022 runner yet so we need to install them too. To build a Windows app we only need the MAUI workload.

With our build environment set up we can now restore our dependencies and build our app. I want MSBuild to create a release build and not to restore dependencies itself. The important options in the MSBuild command are the framework -p:TargetFramework=net6.0-windows10.0.19041 and the instruction to create an app package /p:GenerateAppxPackageOnBuild=true.

Finally we upload the app package as a build artifact.

iOS Build Job

  build-ios:
    runs-on: macos-11
    name: iOS Build
    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: Setup .NET 6
        uses: actions/setup-dotnet@v1
        with:
          dotnet-version: 6.0.x
          include-prerelease: true

      - name: Install MAUI Workloads
        run: |
          dotnet workload install ios --ignore-failed-sources
          dotnet workload install maui --ignore-failed-sources

      - name: Restore Dependencies
        run: dotnet restore src/MauiBeach/MauiBeach.csproj

      - name: Build MAUI iOS
        run: dotnet build src/MauiBeach/MauiBeach.csproj -c Release -f net6.0-ios --no-restore

      - name: Upload iOS Artifact
        uses: actions/upload-artifact@v2.3.1
        with:
          name: ios-ci-build
          path: src/MauiBeach/bin/Release/net6.0-ios/**/*.app/

Apple requires that all iOS apps are built on a Mac and .NET 6 requires Visual Studio 2022 so we need to use a macos-11 runner for our iOS build job.

Again we start by checking out the code and install the latest pre-release version of .NET 6.

The .NET MAUI workloads are not included in GitHub's macos-11 runner yet so we need to install them too. To build an iOS app we need the iOS and MAUI workloads.

Now we can restore our dependencies and build our app. Like the Android build job we can use a standard dotnet build command to build our app for iOS. Again I want dotnet build to create a release build and not to restore dependencies. The important option here is -f net6.0-ios to set the framework we want to build.

Finally we upload the *.app folder as a build artifact.

MacCatalyst Build Job

  build-mac:
    runs-on: macos-11
    name: MacCatalyst Build
    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: Setup .NET 6
        uses: actions/setup-dotnet@v1
        with:
          dotnet-version: 6.0.x
          include-prerelease: true

      - name: Install MAUI Workloads
        run: |
          dotnet workload install maccatalyst --ignore-failed-sources
          dotnet workload install maui --ignore-failed-sources

      - name: Restore Dependencies
        run: dotnet restore src/MauiBeach/MauiBeach.csproj

      - name: Build MAUI MacCatalyst
        run: dotnet build src/MauiBeach/MauiBeach.csproj -c Release -f net6.0-maccatalyst --no-restore

      - name: Upload MacCatalyst Artifact
        uses: actions/upload-artifact@v2.3.1
        with:
          name: macos-ci-build
          path: src/MauiBeach/bin/Release/net6.0-maccatalyst/**/*.app/

Our MacCatalyst build job is very similar to our iOS build job. Using a macos-11 runner we check out our code and install the latest pre-release version of .NET 6. To build a MacCatalyst app we need the MacCatalyst and MAUI workloads so they are installed next.

Again we can use a standard dotnet build command to build our app for MacCatalyst. For this job the framework option is -f net6.0-maccatalyst.

The last step is to upload the *.app folder as a build artifact.

And Finally...

The complete workflow can be found in my Maui Beach repo:
👩‍💻 .github/workflows/ci-build.yml

And, you can see the workflow run here. 🥳🎉

Cover image includes a vector created by brgfx from www.freepik.com.

Installing .NET MAUI Preview 11

Update: Visual Studio 2022 17.1 Preview 2 is now available and is the recommended method to install .NET MAUI Preview 11. CLI install is no longer needed, see below for how to remove the CLI workloads and install with VS2022.

.NET MAUI Preview 11 can be installed using the command line but will break XAML Hot Reload in Visual Studio 2022 17.1 Preview 1 and risks conflicts once Visual Studio 2022 17.1 Preview 2 is released. If you're willing to accept those issues the process is fairly simple:

1. Close all Visual Studio + Visual Studio Installer windows
2. Install .NET v6.0.1 (aka v6.0.101)
3. dotnet --version (check for 6.0.101)
4. dotnet workload update
5. dotnet workload install maui

At this point it is recommended to create a new MAUI project using the command line dotnet new maui to check for templates that need to be installed or updated. This command will install or update all MAUI templates:

dotnet new --install  Microsoft.Maui.Templates

Another useful command is dotnet workload list which will show all the workloads installed from the command line - note it does not list workloads installed using the Visual Studio Installer.

Disable XAML Hot Reload

As mentioned Preview 11 breaks XAML Hot Reload in Visual Studio 2022 17.1 Preview 1. I didn't find any problems running a MAUI app on Windows with XAML Hot Reload still enabled but when I tried Android the app wouldn't run. To disable XAML Hot Reload in Visual Studio:

1. Open the Options window (Tools | Options)
2. Expand the Debugging section
3. Untick Enable XAML Hot Reload at the top of the window

Removing CLI Workloads

Now that Visual Studio 2022 17.1 Preview 2 is available we should remove the CLI workloads before updating Visual Studio. We can do this with the dotnet workload uninstall command:

dotnet workload uninstall maui
dotnet workload uninstall android
dotnet workload uninstall ios
dotnet workload uninstall maccatalyst

Check that you have uninstalled all the workloads with dotnet workload list and you can update to Visual Studio 2022 17.1 Preview 2. Remember to re-enable Hot Reload after the update.

Updating an app for .NET MAUI Preview 11

In order to update MAUI Beach from Preview 10 to Preview 11 I made the following changes. You can also see them on GitHub here and here.

Required Changes for Windows

In your project file *.csproj change the RuntimeIdentifier to win10-x64 in this section:

<PropertyGroup Condition="$(TargetFramework.Contains('-windows'))">
    <OutputType>WinExe</OutputType>
    <RuntimeIdentifier>win10-x64</RuntimeIdentifier>
</PropertyGroup>

You will also need to update the Microsoft.WindowsAppSDK and Microsoft.Graphics.Win2D dependencies. Using the Visual Studio package manager didn't work for me because those packages are in their own conditional ItemGroup so I would recommend updating them by editing your *.csproj manually:

<ItemGroup Condition="$(TargetFramework.Contains('-windows'))">
    <!-- Required - WinUI does not yet have buildTransitive for everything -->
    <PackageReference Include="Microsoft.Graphics.Win2D" Version="1.0.0.30" />
    <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.0.0" />
</ItemGroup>

When I tried to run my app on Windows I ran into this error related to a splash screen:

DEP0700: Registration of the app failed. [0x80073CF6] 
AppxManifest.xml(33,27): error 0x80070002: Cannot install or update package 
because the splash screen image [appiconfgSplashScreen.png] cannot be located.

I'm not sure if this was because of Preview 11 but I was able to fix it by updating the uap:SplashScreen property in Platforms/Windows/Package.appxmanifest:

<uap:SplashScreen Image="Assets\wave_splashSplashScreen.png" />

Amusingly I still don't actually see a splash screen on Windows but it compiles and runs. 🤷‍♂️

Required Changes for Android

In Platforms/Android/MainActivity.cs add the OnCreate and OnRequestPermissionsResult methods from the new template:

public class MainActivity : MauiAppCompatActivity
{
    protected override void OnCreate(Bundle savedInstanceState)
    {
        base.OnCreate(savedInstanceState);
        Platform.Init(this, savedInstanceState);
    }

    public override void OnRequestPermissionsResult(int requestCode, string[] permissions, Permission[] grantResults)
    {
        Platform.OnRequestPermissionsResult(requestCode, permissions, grantResults);
        base.OnRequestPermissionsResult(requestCode, permissions, grantResults);
    }
}

Required Changes for iOS & MacCatalyst

I didn't find any changes that were necessary for iOS or MacCatalyst. 🎉

Optional Changes

The .NET MAUI Preview 11 app template uses C# 10 implicit global usings and file-scoped namespaces. If you want to opt-in to implicit global usings add the following property to the first PropertyGroup in your *.csproj:

<ImplicitUsings>enable</ImplicitUsings>

You can then remove most of the using statements in your code!

File-scoped namespaces are even easier to use. Just open a *.cs file and place your cursor on the namespace line, a Quick Action icon will appear, click the Convert to file-scoped namespace action and you're done.

Useful Links

• .NET December Updates
• .NET 6 Downloads
• MAUI Preview 11 Release

Cover image includes a vector created by brgfx from www.freepik.com.

Example Code

The example solution in the src folder contains a .NET Standard 2.1 class library DocFXExample and a test project. DocFXExample has one class Example which contains a single method Divide(). The code itself is not important, we just need something we can document.

namespace DocFXExample
{
    public static class Example
    {
        public static (int quotient, int remainder) Divide(int dividend, int divisor)
        {
            return (dividend / divisor, dividend % divisor);
        }
    }
}

Installing DocFX

DocFX is a documentation generator for .NET which supports C#, Visual Basic and F#. Using XML doc comments in your code along with Markdown and YAML files, DocFX builds a static HTML website which can be hosted on GitHub Pages or any web server.

DocFX can be integrated with Visual Studio but I prefer using the command line version which can be installed using Chocolatey, Homebrew or manually from GitHub.

• Chocolatey: choco install docfx -y
• Homebrew: brew install docfx
• GitHub: Download DocFX, extract to a folder and add it to your PATH

Create a Documentation Project

First we need to initialise a new DocFX project. In the root of the repo type the command:

docfx init -q

This generates a documentation project named docfx_project.

The documentation project contains several files and folders we can use to customise the generated documentation:

• docfx.json - configuration file
• index.md - home page for the generated site
• toc.yml - main navigation menu
• articles - folder for custom articles
• api/index.md - index page for API documentation

We need to tell DocFX where to find our code by updating the src property in the metadata section of the configuration file docfx.json. We also need to change the output folder dest from _site to ../docs to make publishing to GitHub Pages easier:

{
  "metadata": [
    {
      "src": [
        {
          "src": "../",
          "files": [
            "src/DocFXExample/**.csproj"
          ]
        }
      ],
      "dest": "api",
      "disableGitFeatures": false,
      "disableDefaultFilter": false
    }
  ],
  "build": {
    "content": [
      {
        "files": [
          "api/**.yml",
          "api/index.md"
        ]
      },
      {
        "files": [
          "articles/**.md",
          "articles/**/toc.yml",
          "toc.yml",
          "*.md"
        ]
      }
    ],
    "resource": [
      {
        "files": [
          "images/**"
        ]
      }
    ],
    "overwrite": [
      {
        "files": [
          "apidoc/**.md"
        ],
        "exclude": [
          "obj/**",
          "_site/**"
        ]
      }
    ],
    "dest": "../docs",
    "globalMetadataFiles": [],
    "fileMetadataFiles": [],
    "template": [
      "default"
    ],
    "postProcessors": [],
    "markdownEngineName": "markdig",
    "noLangKeyword": false,
    "keepFileLink": false,
    "cleanupCacheHistory": false,
    "disableGitFeatures": false
  }
}

DocFX includes its own .gitignore files in the docfx_project and docfx_project/api folders but I like to keep my ignores central so I delete those files and add the following to the root .gitignore file:

# DocFX
docfx_project/api/.manifest
docfx_project/api/*.yml
docs

We can now build and test our documentation project locally with the following command:

docfx docfx_project\docfx.json --serve

You can view the generated website at: http://localhost:8080/

Add XML Doc Comments

XML documentation comments are special comment fields indicated by triple slashes which can be converted into documentation by tools like DocFX, Sandcastle and Doxygen.

namespace DocFXExample
{
    /// <summary>A simple example class with one method which divides two numbers.</summary>
    public static class Example
    {
        /// <summary>Divides the specified dividend by the divisor, returning the quotient and the remainder as a Tuple.</summary>
        /// <param name="dividend">The dividend - the number which will be divided by the divisor.</param>
        /// <param name="divisor">The divisor - the number by which the dividend will be divided.</param>
        /// <returns>(quotient, remainder)</returns>
        public static (int quotient, int remainder) Divide(int dividend, int divisor)
        {
            return (dividend / divisor, dividend % divisor);
        }
    }
}

Intellisense Tooltips

The C# compiler can also process XML doc comments and generate IntelliSense tooltips in Visual Studio. To enable Intellisense we need to tell the compiler to generate an XML file by adding a PropertyGroup to the csproj project file:

<PropertyGroup>
  <DocumentationFile>DocFXExample\Taranis.DocFXExample.xml</DocumentationFile>
</PropertyGroup>

After building the project the contents of the summary and returns tags will now appear in Visual Studio:

GitHub Actions Workflows

In the example repo I've created three GitHub Actions workflows:

• ci-build.yml
• docs-only-build.yml
• release-build.yml

All three workflows include a manual workflow_dispatch trigger for testing purposes and use Ubuntu runners. Why Ubuntu? Windows runners are charged at 2x the cost of Linux runners, MacOS runners are charged at 10x the cost of Linux runners and only Linux runners are compatible with Docker based Actions so unless you need Windows or MacOS to build your solution it is better to use an Ubuntu runner.

CI Build

ci-build.yml is a typical .NET Continuous Integration workflow with a single job that runs on any push or pull request to the master branch. It checks out the repo, sets up .NET, builds and tests the solution before uploading the Nuget library and test coverage report as build artifacts.

name: CI Build

on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]
  workflow_dispatch:
permissions:
  contents: read  
  pull-requests: write

env:
  DOTNET_NOLOGO: true                     # Disable the .NET logo in the console output
  DOTNET_SKIP_FIRST_TIME_EXPERIENCE: true # Disable the .NET first time experience to skip caching NuGet packages and speed up the build
  DOTNET_CLI_TELEMETRY_OPTOUT: true       # Disable sending .NET CLI telemetry to Microsoft

jobs:
  build:
    runs-on: ubuntu-latest
    name: CI Build
    steps:
    - name: Checkout
      uses: actions/checkout@v2

    - name: Setup .NET
      uses: actions/setup-dotnet@v1
      with:
        dotnet-version: 5.0.x

    - name: Restore Dependencies
      run: dotnet restore src/DocFXExample.sln

    - name: Build
      run: dotnet build src/DocFXExample.sln --configuration Release --no-restore

    - name: Test
      run: dotnet test src/DocFXExample.sln --configuration Release --no-build --verbosity normal --collect:"XPlat Code Coverage" --results-directory ./coverage

    - name: Copy Coverage To Predictable Location
      run: cp coverage/**/coverage.cobertura.xml coverage.cobertura.xml

    - name: Coverage Summary Report
      uses:  irongut/CodeCoverageSummary@v1.2.0
      with:
        filename: coverage.cobertura.xml
        badge: true
        format: 'md'
        output: 'both'

    - name: Add Coverage PR Comment
      uses: marocchino/sticky-pull-request-comment@v2
      if: github.event_name == 'pull_request'
      with:
        recreate: true
        path: code-coverage-results.md

    - name: Upload Coverage Artifact
      uses: actions/upload-artifact@v2.3.0
      with:
        name: test-coverage-report
        path: |
          coverage.cobertura.xml
          code-coverage-results.md

    - name: Upload Nuget Artifact
      uses: actions/upload-artifact@v2.3.0
      with:
        name: ci-nugets
        path: src/DocFXExample/bin/Release/Taranis.DocFXExample*.nupkg

Documentation Build

docs-only-build.yml is a manually triggered workflow that uses DocFX to generate and publish our documentation. It consists of a single job which checks out the repo, builds the documentation using the nikeee/docfx-action action and publishes it to GitHub Pages using the peaceiris/actions-gh-pages action. This workflow is useful for testing the documentation job and updating the site with new articles or customisation changes.

name: Docs Only Build

on:
  workflow_dispatch:

jobs:
  build-docs:
    name: Build Docs
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@v2

    - name: Build Documentation
      uses: nikeee/docfx-action@v1.0.0
      with:
        args: docfx_project/docfx.json

    - name: Deploy to GitHub Pages
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./docs

Release Build

release-build.yml is where we put everything together. Triggered whenever a pre-release or full release is published it consists of three jobs that run sequentially.

The first job build is a slightly simplified version of our CI Build workflow. It checks out the repo, builds and tests the code and uploads the Nuget and test coverage report as an artifact.

The deploy-nuget job only runs if the build job was successful. It gets the artifact from the previous step, publishes the Nuget package and adds the test coverage report to the release notes. Or it would in a real project, since this is just an example I've left out the steps to deploy the package to nuget.org, GitHub Packages or another package feed.

The final job deploy-docs is a copy of our Documentation Build workflow. It will only run if both the build and deploy-nuget jobs are successful. Like the previous workflow it checks out the repo, builds the documentation and publishes it to GitHub Pages.

name: Build + Deploy

on:
  release:
    types: [published]
    branches: [master]
  workflow_dispatch:

env:
  DOTNET_NOLOGO: true                     # Disable the .NET logo
  DOTNET_SKIP_FIRST_TIME_EXPERIENCE: true # Disable the .NET first time experience to speed up the build
  DOTNET_CLI_TELEMETRY_OPTOUT: true       # Disable sending .NET CLI telemetry

jobs:
  build:
    runs-on: ubuntu-latest
    name: Release Build
    steps:
    - name: Checkout
      uses: actions/checkout@v2

    - name: Setup .NET
      uses: actions/setup-dotnet@v1
      with:
        dotnet-version: 5.0.x

    - name: Restore Dependencies
      run: dotnet restore src/DocFXExample.sln

    - name: Build
      run: dotnet build src/DocFXExample.sln --configuration Release --no-restore

    - name: Test
      run: dotnet test src/DocFXExample.sln --configuration Release --no-build --verbosity normal --collect:"XPlat Code Coverage" --results-directory ./coverage

    - name: Copy Coverage To Predictable Location
      run: cp coverage/**/coverage.cobertura.xml coverage.cobertura.xml

    - name: Coverage Summary Report
      uses: irongut/CodeCoverageSummary@v1.2.0
      with:
        filename: coverage.cobertura.xml
        badge: true
        format: 'md'
        output: 'both'

    - name: Upload Coverage Artifact
      uses: actions/upload-artifact@v2.3.0
      with:
        name: release-nugets
        path: code-coverage-results.md

    - name: Upload Nuget Artifact
      uses: actions/upload-artifact@v2.3.0
      with:
        name: release-nugets
        path: src/DocFXExample/bin/Release/Taranis.DocFXExample*.nupkg

  deploy-nuget:
    name: Deploy Nuget
    needs: [build]
    runs-on: ubuntu-latest
    steps:
    - name: Download Artifacts
      uses: actions/download-artifact@v2
      with:
        name: release-nugets

    # Here you can deploy your Nuget package to 
    # nuget.org, GitHub Packages or a private package feed

    - name: Add Coverage to Release
      uses: irongut/EditRelease@v1.0.0
      with:
        token: ${{ secrets.GITHUB_TOKEN }}
        id: ${{ github.event.release.id }}
        files: code-coverage-results.md

  deploy-docs:
    name: Deploy Docs
    needs: [build, deploy-nuget]
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@v2

    - name: Build Documentation
      uses: nikeee/docfx-action@v1.0.0
      with:
        args: docfx_project/docfx.json

    - name: Deploy to GitHub Pages
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./docs

Configure GitHub Pages

After we publish our documentation for the first time, using either the docs only or the release workflow, we need to configure GitHub Pages to show it. On the Settings tab for the repo click Pages in the left menu. Our workflows publish the documentation to a branch called gh-pages. Select the gh-pages branch in the first drop down, / (root) in the second drop down and click Save. Our documentation site is now available on the url shown, in this case: https://irongut.github.io/DocFXExample/ 🎉

Links

• DocFX
• XML Documentation Comments
• DocFX Action
• GitHub Pages Action

Start Me Up

To get the best experience with .NET MAUI Preview 10 requires the preview version of Visual Studio 2022 (17.1) which can be installed alongside the stable release of Visual Studio 2022 (17.0) or earlier releases. During installation select the Mobile development with .NET workload and you should see .NET MAUI (Preview) added to the optional mobile components on the right. Click install and you're ready to get started with .NET MAUI!

First Time

Creating a new .NET MAUI app in Visual Studio 2022 is a simple process. Select MAUI from the Project Types drop down and you will be presented with three options - .NET MAUI App, .NET MAUI Blazor App and .NET MAUI Class Library. Select .NET MAUI App and click Next.

You will then be asked for a project name, location and solution name like any other .NET project. Click Create and a new cross platform app will be created from the .NET MAUI template.

Time to build the template app for the first time and check the emulators, etc are working. At this point I ran into a problem, my first build failed with three errors in the build output:

CS0246 The type or namespace name 'IStartup' could not be found
CS0246 The type or namespace name 'IAppHostBuilder' could not be found
CS0308 The non-generic type 'MauiApplication' cannot be used with type arguments

A quick search lead me to the cause of the problem. I had previously tried an early preview of Visual Studio 2022 and .NET MAUI which left old templates on my system and the new install hadn't replaced them. I was able to update the templates by running the following command line:

dotnet new --install  Microsoft.Maui.Templates

After deleting and recreating my project with the updated template I was able to build.

Run Through The Jungle

Having achieved my first build I ran the app on Windows, since that doesn't require an emulator or simulator. Immediately I was greeted by .NET Bot waving happily with a button connected to a counter, success! 🎉

Similarly, running the app on Android went smoothly. Visual Studio 2022 had recognised the Android emulators I use with Visual Studio 2019 so I was able to pick one from the drop down, click run and a few moments later was greeted again by .NET Bot but now running on Android. 👏

The iOS build process and the Remote Simulator have been temperamental for me in recent months so I was unsurpried when my first iOS run failed with a deployment error:

> Need recipe file

Falling back on old Xamarin habits, I double checked the Start drop down had the Framework set to net6.0-ios and an iOS Simulator correctly selected then Cleaned and Rebuilt the solution.

That got me past the recipe file error and the Remote Simulator started up... but then failed with the message A fatal error occurred while trying to start the server. 🙁

I closed the simulator and tried again... disconnected and reconnected to my build Mac and tried again... but to no avail. For some reason Visual Studio 2022 couldn't start the simulator. Eventually I used a Xamarin.iOS project in Visual Studio 2019 to start the simulator, switched back to Visual Studio 2022 and ran my MAUI app on the same simulator...

Success! 😁

The recipe file error appears whenever I switch from testing on Windows or Android to testing on iOS. A clean and rebuild usually solves it, sometimes if done twice. 🤨 Fortunately the simulator and Visual Studio 2022 have been behaving themselves since the first time and I haven't seen that problem again.

Paint It Black

With everything working on three platforms it was time to make some changes. In Resources/Styles/DefaultTheme.xaml I created a dark theme with a few colours and default styles for Label and Button based on existing styles in App.xaml:

<ResourceDictionary xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
                    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml" 
                    x:Class="MauiBeach.Resources.Styles.DefaultTheme">

    <!-- Colour Palette -->

    <Color x:Key="pageBackgroundColor">#2E3440</Color>
    <Color x:Key="pageForegroundColor">#434C5E</Color>

    <Color x:Key="textColor">#D8DEE9</Color>
    <Color x:Key="strongTextColor">#ECEFF4</Color>
    <Color x:Key="altTextColor">White</Color>
    <Color x:Key="darkTextColor">#2E3440</Color>
    <Color x:Key="lightTextColor">#D8DEE9</Color>
    <Color x:Key="disabledTextColor">DarkGray</Color>

    <Color x:Key="primaryColor">#BF616A</Color>
    <Color x:Key="secondaryColor">#D08770</Color>
    <Color x:Key="tertiaryColor">#A3BE8C</Color>

    <!-- Styles -->

    <Style TargetType="Label">
        <Setter Property="TextColor"
                Value="{StaticResource textColor}"/>
        <Setter Property="FontFamily"
                Value="OpenSansRegular"/>
    </Style>

    <Style TargetType="Button">
        <Setter Property="TextColor"
                Value="{StaticResource altTextColor}"/>
        <Setter Property="FontFamily"
                Value="OpenSansRegular"/>
        <Setter Property="BackgroundColor"
                Value="{StaticResource primaryColor}"/>
        <Setter Property="CornerRadius"
                Value="10"/>
        <Setter Property="Padding"
                Value="15, 10"/>
    </Style>

</ResourceDictionary>

I created DefaultTheme.xaml by creating a new ContentPage and changing the type. This initially gave me an error because the ContentPage template was from Xamarin.Forms. Updating its using statements and xml namespace to MAUI instead of Forms, changing its Build Action property to MauiXaml and deleting the value of its Custom Tool property fixed the problem.

The existing styles in App.xaml I replaced by loading my theme:

<Application.Resources>
    <ResourceDictionary Source="Resources/Styles/DefaultTheme.xaml"/>
</Application.Resources>

I also added colours to Platforms/Android/Resources/values/colors.xml and updated the BackgroundColor of MainPage.xaml. I'll eventually expand on this theme, add more themes and a way to switch between them but for this article a simple dark theme will do. Running the app we can see that the theme works:

Splish Splash

Setting up a theme in .NET MAUI works exactly like Xamarin.Forms so now I wanted to try something completely new - a cross platform splash screen. In Xamarin.Forms you need to add a splash screen for each platform in their own project and learn the different ways they all handle splash screens natively. With .NET MAUI you create one splash screen which the build system will magically make work on every platform!

There isn't much documentation for .NET MAUI at the moment but David Ortinau's awesome WeatherTwentyOne app is a great resource to learn from. You've may have seen it demonstrated at .Net Conf 2021 or in the official .Net MAUI blogs.

The project file *.csproj contains a MauiSplashScreen item which allows you to specify an image and a colour to use for the background of the splash screen. You can even use an SVG image so your splash screen will look good at all resolutions and screen sizes. I changed the default image to something suitable and the colour to the primary colour in my theme.

<MauiSplashScreen Include="Resources\wave_splash.svg" Color="#BF616A"/>

My splash screen worked perfectly on both Android and iOS. (Windows does not show a splash screen)

The project file also contains a MauiIcon item which allows you to specify a background image, a foreground image and a colour. Again you can use SVG images and the build system will magically create icons for all platforms.

<MauiIcon Include="Resources\appicon.svg" ForegroundFile="Resources\wave_icon.svg" Color="#BF616A"/>

This worked quite well on Windows and iOS but unfortunately on Android the icon didn't look the same.

I spent some time editing the image with Inkscape and a text editor (to remove meta tags the build process doesn't like) but I couldn't get an icon I liked on Android or even one that looked the same as the other platforms. The build process that creates the Android icon has some limitations at the moment and rejects valid SVG tags. I can create a better icon with Android Studio so I could fall back on using a platform specific icon for Android but hopefully the process will be improved in a future preview.

Shell Shocked

I want the UI for MAUI Beach to be based around a flyout menu built using Shell. Adding an Application.MainPage element containing a Shell element to App.xaml I defined a flyout header, an item template and three flyout items:

<Application.MainPage>
    <Shell FlyoutBehavior="Flyout"
           FlyoutHeaderBehavior="Fixed"
           FlyoutVerticalScrollMode="Auto">

        <Shell.FlyoutHeader>
            <Grid BackgroundColor="{StaticResource primaryColor}"
                  HeightRequest="220"
                  Padding="0, 10">

                <Image Source="wave_icon.png"
                       HorizontalOptions="Center"
                       VerticalOptions="Center"
                       HeightRequest="200"
                       WidthRequest="200"/>

                <Label Text="MAUI Beach"
                       TextColor="{StaticResource darkTextColor}"
                       FontSize="42"
                       FontAttributes="Bold"
                       HorizontalOptions="Center"
                       VerticalOptions="End"/>

            </Grid>
        </Shell.FlyoutHeader>

        <Shell.ItemTemplate>
            <DataTemplate>
                <Grid ColumnDefinitions="0.25*,0.75*"
                      Padding="0, 10">

                    <Image Source="{Binding FlyoutIcon}"
                           HeightRequest="45"
                           HorizontalOptions="Center"/>

                    <Label Grid.Column="1"
                           Text="{Binding Title}"
                           FontSize="Large"
                           FontAttributes="Bold"
                           VerticalOptions="Center"/>

                </Grid>
            </DataTemplate>
        </Shell.ItemTemplate>

        <FlyoutItem Title="Home"
                    Icon="home.png">
            <ShellContent ContentTemplate="{DataTemplate p:HomePage}"/>
        </FlyoutItem>

        <FlyoutItem Title="Settings"
                    Icon="settings.png">
            <ShellContent ContentTemplate="{DataTemplate p:SettingsPage}"/>
        </FlyoutItem>

        <FlyoutItem Title="About"
                    Icon="about.png">
            <ShellContent ContentTemplate="{DataTemplate p:AboutPage}"/>
        </FlyoutItem>

    </Shell>
</Application.MainPage>

One thing to note here is the names of the images used in my flyout items - wave_icon.png, home.png, settings.png and about.png. You will not find those images in my project but in the Resources/Images folder you will find wave_icon.svg, home.svg, settings.svg and about.svg - so what is going on? .NET MAUI incorporates a tool called ResizetizerNT which allows you to add a single SVG or PNG image to your project and at build time it creates all the different sizes of image required by your app in the native resources folders. So about.svg in the Resources/Images folder becomes about.png in my XAML. ResizetizerNT is also invloved in the creation of app icons during the build process.

In App.xaml.cs I removed the line that created the default MainPage and deleted the files. At this point I needed to create my three pages and when creating a new ContentPage I ran into the same Xamarin.Forms template issue as earlier with the ResourceDictionary. Again updating their using statements and xml namespaces, changing Build Action to MauiXaml and deleting Custom Tool fixed the problem.

My initial pages are almost identical and very basic for now:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="MauiBeach.Pages.HomePage"
             Title="Home">
    <ContentPage.Content>
        <StackLayout>
            <Label Text="Home Page"
                   FontSize="Large"
                   VerticalOptions="CenterAndExpand" 
                   HorizontalOptions="CenterAndExpand"/>
        </StackLayout>
    </ContentPage.Content>
</ContentPage>

After checking that worked I could start to customise my UI more. To my theme in Resources/Styles/DefaultTheme.xaml I added default styles for Page and NavigationPage and styles for the Shell flyout menu and menu items.

<Style TargetType="Page"
       ApplyToDerivedTypes="True">
    <Setter Property="BackgroundColor"
            Value="{StaticResource pageBackgroundColor}"/>
    <Setter Property="Padding"
            Value="20, 10"/>
</Style>

<Style TargetType="NavigationPage"
        ApplyToDerivedTypes="True">
    <Setter Property="BackgroundColor"
            Value="{StaticResource pageBackgroundColor}"/>
    <Setter Property="BarBackgroundColor"
            Value="{StaticResource primaryColor}"/>
    <Setter Property="BarTextColor"
            Value="{StaticResource altTextColor}"/>
</Style>

<!-- Shell -->

<Style x:Key="BaseStyle"
       TargetType="Element">
    <Setter Property="Shell.FlyoutBackground"
            Value="{StaticResource pageBackgroundColor}"/>
    <Setter Property="Shell.FlyoutBackgroundColor"
            Value="{StaticResource pageBackgroundColor}"/>
    <Setter Property="Shell.BackgroundColor"
            Value="{StaticResource primaryColor}"/>
    <Setter Property="Shell.ForegroundColor"
            Value="{StaticResource altTextColor}"/>
    <Setter Property="Shell.TitleColor"
            Value="{StaticResource altTextColor}"/>
    <Setter Property="Shell.DisabledColor"
            Value="{StaticResource disabledTextColor}"/>
    <Setter Property="Shell.UnselectedColor"
            Value="{StaticResource disabledTextColor}"/>
    <Setter Property="Shell.TabBarBackgroundColor"
            Value="{StaticResource primaryColor}"/>
    <Setter Property="Shell.TabBarTitleColor"
            Value="{StaticResource altTextColor}"/>
    <Setter Property="Shell.TabBarUnselectedColor"
            Value="{StaticResource disabledTextColor}"/>
    <Setter Property="Shell.NavBarHasShadow"
            Value="True"/>
</Style>

<Style BasedOn="{StaticResource BaseStyle}"
       ApplyToDerivedTypes="True"
       TargetType="FlyoutItem"/>

<Style x:Key="shellItem"
       TargetType="Grid">
    <Setter Property="VisualStateManager.VisualStateGroups">
        <VisualStateGroupList>
            <VisualStateGroup x:Name="CommonStates">
                <VisualState x:Name="Normal">
                    <VisualState.Setters>
                        <Setter Property="BackgroundColor"
                                Value="{StaticResource pageBackgroundColor}"/>
                    </VisualState.Setters>
                </VisualState>
                <VisualState x:Name="Selected">
                    <VisualState.Setters>
                        <Setter Property="BackgroundColor"
                                Value="{StaticResource secondaryColor}"/>
                    </VisualState.Setters>
                </VisualState>
            </VisualStateGroup>
        </VisualStateGroupList>
    </Setter>
</Style>

I also expanded on my Shell definition in App.xaml by adding a flyout footer and a gradient backdrop:

<Shell.FlyoutFooter>
    <Grid BackgroundColor="{StaticResource primaryColor}"
          HeightRequest="32"
          Padding="0, 5, 0, 5">

        <Label Text="Copyright © 2021 Taranis Software"
               TextColor="{StaticResource altTextColor}"
               FontSize="Small"
               HorizontalOptions="Center"/>

    </Grid>
</Shell.FlyoutFooter>

<Shell.FlyoutBackdrop>
    <LinearGradientBrush StartPoint="0,0"
                         EndPoint="0,1">
        <GradientStop Color="{StaticResource primaryColor}"
                      Offset="0.3"/>
        <GradientStop Color="{StaticResource secondaryColor}"
                      Offset="1.0"/>
    </LinearGradientBrush>
</Shell.FlyoutBackdrop>

As you can see this mostly worked but the FlyoutBackground / FlyoutBackgroundColor properties are not correctly set on any platform, instead these areas are white or black depending on the device's current system theme. Looking at the .NET MAUI repo this has been fixed already for Android and iOS and work is in progress for Windows so a future preview version will fix my flyout menu.

The End

I now have the basic framework set up for MAUI Beach - a cross platform app built using .NET MAUI. My app has a theme, a splash screen, an icon and a flyout menu with three empty pages.

I have run into a few issues, which should be expected when working with pre-release code, but none of them were insurmountable and most things worked in a similar way to Xamarin.Forms. .NET MAUI Preview 11 is due soon and should fix some of my problems. Overall I think .NET MAUI is shaping up nicely and I'm looking forward to a great experience when it goes GA in Q2 2022.

Cover image includes a background vector created by freepik from www.freepik.com.

• 🗃 supports multiple coverage files
• 🧭 supports hiding the Branch Rate and Complexity metrics in the output

Performance has also been improved thanks to an upgrade to .Net 6 and improvements to the Docker image.

Code Coverage Summary reads Cobertura format coverage files from your test suite and outputs a text or markdown summary that can be posted as a Pull Request comment or included in Release Notes to give you an immediate insight into the health of your code without using a third-party site.

Designed for use with Coverlet and gcovr, Code Coverage Summary should work with any test framework that outputs coverage in Cobertura format.

• 🛍 GitHub Marketplace
• 👨‍💻 Repository

Blue vector created by vectorjuice - www.freepik.com