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

Android API level missing

If you see an error like the following, some Android dependencies are missing.

/.../Microsoft.Android.Sdk.Darwin/34.0.113/tools/Xamarin.Android.Tooling.targets(100,5): error XA5207: Could not find android.jar for 
API level 34. This means the Android SDK platform for API level 34 is not installed; it was expected to be in
/PATH_TO_SDK/platforms/android-34/android.jar.

Install the missing dependencies by executing the following commands in a terminal window. Make sure that you are in the project directory. You also need to use the correct path for your Android SDK. The path you need is shown in the error message.

export AcceptAndroidSDKLicenses=true
dotnet build -t:InstallAndroidDependencies -f net8.0-android "-p:AndroidSdkDirectory=/PATH_TO_SDK"
Android emulator hangs during startup on Windows

The emulator runs an Android image as a virtual machine. This needs to be enabled in the Windows BIOS.

Crash on start

If your application was previously working but starts to crash on starting up, it may be because some package versions have changed. Try removing all of the object and binary files and recompiling. Right-click on the project in the Solution Explorer and click Clean

During setup, directories are created with percent signs in their names (e.g. %ANDROID_HOME%)

This happens when you use the Windows PowerShell when running a terminal. Use the basic CMD command window instead. You can configure your VSCode profile to use CMD by default

Exception -532462766

When trying to start the Android emulator, this exception is reported accompanied by the additional messages below.

C:\Users\133423866\MAUI>sdkmanager --install "system-images;android-34;google_apis;x86_64"
Warning: Errors during XML parse:
Warning: Additionally, the fallback loader failed to parse the XML.
Warning: Errors during XML parse:
Warning: Additionally, the fallback loader failed to parse the XML.
[=======================================] 100% Computing updates...

The reason for this error is unknown, but it can be ignored - it should not affect the emulator.

Missing workloads

After certain updates, the .NET workloads associated with a project need to be reinstalled. When this happens, you will see an error like the following:

  Determining projects to restore...
/.../Microsoft.NET.Sdk/targets/Microsoft.NET.Sdk.ImportWorkloads.targets(38,5): error NETSDK1147: To build this
project, the following workloads must be installed: wasi-experimental [/.../Notes/Notes.csproj::TargetFramework=net8.0-android]
/.../Microsoft.NET.Sdk/targets/Microsoft.NET.Sdk.ImportWorkloads.targets(38,5): error NETSDK1147: To install these workloads, 
run the following command: dotnet workload restore [/.../Notes/Notes.csproj::TargetFramework=net8.0-android]

The command shown in the error message may not work if the restoration requires elevated privileges. On Mac or Linux, use the following command at a terminal prompt ensuring that you are in the project directory:

sudo dotnet workload restore

On Windows, start a command shell with administrator privilege, change into the project directory and execute the command:

dotnet workload restore
Package downgrade detected

If you see an error like the following, it means that there is a conflict between different NuGet packages and you need to upgrade one or more of them to their latest version.

 Determining projects to restore...
  All projects are up-to-date for restore.
  Determining projects to restore...
/.../Notes/Notes.csproj : error NU1605: Warning As Error: Detected package downgrade: 
Microsoft.EntityFrameworkCore from 8.0.7 to 8.0.6. Reference the package directly from 
the project to select a different version.  [/.../Notes.sln]

Look in the Notes.sln file to find the package that the error message refers to. Then, right-click on the project in the Solution Explorer and reinstall that package choosing the required version when prompted. This will update the references in the project file.

Platform simulator not found

If you see an error like the following when building your code, your project file includes the iOS platform, but you do not have a simulator installed. 

/.../Notes/obj/Debug/net8.0-ios/iossimulator-arm64/actool/cloned-assets/Assets.xcassets : actool error : The operation 
couldn’t be completed. Failed to locate any simulator runtime matching options: { [/.../Notes/Notes.csproj::TargetFramework=net8.0-ios]

The simplest solution is to remove the reference to iOS from the project file. Locate the TargetFrameworks entry near the start of the file and remove iOS as a target. The example below shows the line before and after the change.

<!-- BEFORE -->
<TargetFrameworks>net8.0-android;net8.0-ios;net8.0-maccatalyst</TargetFrameworks>
<!-- AFTER -->
<TargetFrameworks>net8.0-android;net8.0-maccatalyst</TargetFrameworks>

If you prefer to install a simulator so that you can keep the iOS target, please refer to the Microsoft documentation.

Request nominateProject failure

When starting VSCode, you may see the error below from time to time. It seems to arise when the host computer is busy and results from a race condition between different startup processes.

LimitedFunctionality
StreamJsonRpc.RemoteInvocationException: Request nominateProject failed with message: Cannot read properties of undefined (reading 'size')

The best solution seems to be to restart your computer to kill any unnecessary processes.