How-to guides

Rename a project in VS Code
  1. Close VS Code.
  2. Rename the Project Folder:
    • Navigate to your solution's root directory in your file explorer.
    • Rename the folder that contains your project's.csproj file.
    • Example:MyMauiApp toNewMauiApp.
  3. Update the Solution File (.sln) (Text Editor):
    • Open your.sln file (e.g.,MySolution.sln) in a text editor (like Notepad++, VS Code itself, etc.).
    • Find the line that references your project and update the path to reflect the new folder name and project name. e.g:

      Before:Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "MyMauiApp", "MyMauiApp\MyMauiApp.csproj", "{YOUR-PROJECT-GUID}"

      After:Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "NewMauiApp", "NewMauiApp\NewMauiApp.csproj", "{YOUR-PROJECT-GUID}"

  4. Save and close the.sln file.
  5. Rename the.csproj file (File System):
    • Inside the newly renamed project folder, rename the .csproj file to your new project name.

      Example: MyMauiApp.csproj to NewMauiApp.csproj.

  6. Delete bin andobj folders to remove all compiled artifacts and ensure a clean build.
  7. Open the Project in VS Code
  8. Perform a Global Find and Replace:

    This is where the bulk of the work happens.

    • Use VS Code's global search and replace functionality (Ctrl+Shift+H or Cmd+Shift+H on macOS).
    • Search for the old project name (e.g.,MyMauiApp).
    • Replace with the new project name (e.g.,NewMauiApp).
    • Important considerations for Find and Replace:
      • Case Sensitivity: Be mindful of casing. You might need to perform multiple passes (e.g.,MyMauiApp to NewMauiApp, mymauiapp to newmauiapp, MYMUIAPP to NEWMAUIAPP).
      • Word Boundaries: Be careful not to accidentally replace parts of other words. Use regex for more precise control if needed.
      • Files to Include/Exclude: Make sure to include all relevant C# (.cs), XAML (.xaml), .csproj, and MauiProgram.cs files.
      • Common Places to Update:
        • Namespaces: namespace OldProjectName.Maui; to namespace NewProjectName.Maui;
        • Class references: E.g., if you have public partial class MainPage : ContentPage { /* ... */ } and your old project name was used in partial class generation.
        • MauiProgram.cs: The CreateMauiApp() method might have references to the old project name, especially if you customized it.
        • pp.xaml and App.xaml.cs: Similarly, check these files for namespace references.
        • csproj file: Although you renamed it, there might be internal references to the old project name. Double-check RootNamespace and AssemblyName in the .csproj file directly.
  9. Manually Check Specific Files:
    • MauiProgram.cs: Verify using statements and any configuration that might have explicitly used the old namespace/name.
    • App.xaml and App.xaml.cs</strong></code>: Check x:Class and xmlns attributes for old namespace references.
    • Properties/launchSettings.json (if applicable): While not directly the project name, ensure any paths or configurations are correct.
    • Platforms folders: Check AndroidManifest.xml (Android), Info.plist (iOS/MacCatalyst), Package.appxmanifest (Windows) for display names or package names that might contain the old project name. You'll probably need to update these manually.
  10. Build the Project:
    • Open the terminal in VS Code.
    • Navigate to your project directory.
    • Run:dotnet build
  11. Run the Project

Errors and solutions

At least one invalid signature was encountered

This is a Docker Desktop clock drift issue, not a code problem. When a Mac sleeps and wakes, Docker Desktop's internal VM clock can fall out of sync, causing GPG signature validation to fail for apt repositories.

Fix: Restart Docker Desktop

  1. Click the Docker icon in the menu bar
  2. Select Restart
  3. Wait for it to fully restart
  4. Then retry the build:
    docker build --no-cache --progress=plain -t maui-dev-test "/Users/briandavison/VSCode projects/MauiDevProject"

The clock resync happens automatically on restart. This is a well-known Docker Desktop on macOS issue — the lightweight Linux VM Docker uses doesn't always keep its clock in sync after the host sleeps.

If it happens again after future builds, the quick fix is just restarting Docker Desktop. There's nothing wrong with your Dockerfile.

'No space left on device' when running docker-compose

Multiple failed --no-cache builds have filled Docker's virtual disk with abandoned image layers and build cache. You need to reclaim that space.

Run this to purge all unused Docker data (stopped containers, dangling images, build cache):

docker system prune -a --volumes

Docker will show you how much space will be freed and ask for confirmation. Type y to proceed.

After that completes, retry the build:

docker build --no-cache --progress=plain -t maui-dev-test "/Path/To/Project"

If you want to see how much disk Docker is currently using before/after:

docker system df

If the prune isn't enough and you're still tight on space, you can also increase Docker Desktop's virtual disk limit:

  1. Open Docker Desktop → Settings → Resources → Virtual disk limit
  2. Increase it (default is usually 64 GB) and click Apply & Restart
No available device

Check that the ADB server process is still running on the host operating system. Sometimes it is killed during the build process.

Signatures do not match

If you see a message like the following:

adb: failed to install StarterApp/bin/Debug/net9.0-android/com.companyname.starterapp-Signed.apk:

the version of the app you are trying to install is signed differently from the one currently installed on the emulator/device. The solutions is to uninstall the existing one with the following command: 

adb uninstall com.companyname.starterapp

Modify the name of the app if necessary.

Permissions errors when installing VS Code extensions

Always run VS Code as administrator

Unexpected build errors

When Docker rebuilds the container, it makes use of cached files and this can sometimes cause errors. For example, you may see a reference to a missing file System.Numerics.Vectors. To fix this, bypass the cache when rebuilding the container:

  1. Activate the palette menu (SHIFT+CMD/CTRL+P)
  2. Select Dev Containers: Rebuild Container Without Cache.

Android emulator starts but does not appear on the screen

This is the result of a conflict between the Android emulator and the Windows display setting. To fix it, open your Windows display setting control panel. Find the Svale and layoutem> section, and set the Scale value ot 100%. After this, restart the emulator and it should appear on the screen.

An exception has been raised that is likely due to a transient failure

This message indicates that the app could not communicate with the database. It is probably due to an incorrectly configured database connection string in your appsettings.json file. You can find this file in the StarterApp.Database project. The correct connection string is Host=10.0.2.2:5432;Username=app_user;Password=;Database=appdb.

StaticResource not found for key Gray700

This message indicates that the colour Gray700 is not defined in your StarterApp/Resources/Styles/Colors.xaml file. You can fix it by adding the following two lines in the appropriate place inn the file: 

    <Color x:Key="Gray700">#242424</Color>
    <SolidColorBrush x:Key="Gray700Brush" Color="{StaticResource Gray700}"/>

This site uses Just the Docs, a documentation theme for Jekyll.