Windows applications have traditionally been developed and distributed for x86 and x64 processors. However, Windows devices powered by Arm64 processors are becoming increasingly common. Developers who maintain older .NET applications now have another compatibility requirement to consider: making existing applications run natively on Windows Arm64.
The good news is that Windows already supports running many existing x86 and x64 applications through emulation. This means an application does not necessarily need to be rewritten before it can run on an Arm-based Windows device.
However, running through emulation and running natively are two different things. Native Arm64 applications can take advantage of the processor architecture directly, potentially improving performance, power efficiency, and responsiveness.
The challenge is that older .NET applications often contain architecture-specific build settings, native dependencies, third-party libraries, and configuration assumptions that are not immediately visible.
Microsoft's GitHub Copilot upgrade agent helps reduce the manual effort involved in this migration. It can analyze an existing .NET application, identify compatibility problems, prepare a migration plan, and help update the code and project configuration.
This article explains how to approach Windows Arm64 migration, identify common compatibility problems, and use the GitHub Copilot upgrade agent to move an existing .NET application toward native Arm64 support.
Understanding Windows Arm64 Compatibility
Before migrating an application, it is important to understand how Windows runs applications built for different processor architectures.
Windows on Arm supports native Arm64 applications as well as many existing x86 and x64 applications through emulation.
For example, an existing x64 desktop application can run on Windows 11 Arm64 without necessarily changing its source code. Windows provides an emulation layer that translates supported x64 instructions for the Arm64 processor.
Windows 11 also includes Prism, an improved emulation technology designed to improve compatibility and reduce the overhead of running applications built for x86 and x64 processors.
However, emulation does not provide the same execution characteristics as a native Arm64 application. Applications that perform intensive processing or depend heavily on native libraries can benefit from a native build.
For an older .NET application, the migration decision depends on its target framework, project structure, dependencies, and deployment requirements.
A managed application that uses architecture-neutral .NET libraries may require relatively few changes. An application that depends on native DLLs, processor-specific instructions, or architecture-specific third-party components may require considerably more investigation.
The objective should be to identify these differences before changing the project.
Why Existing .NET Applications Need Migration Work
A .NET application can contain several architecture-dependent components even when most of its business logic is written in C#.
Consider an older Windows desktop application built with Windows Forms or WPF. Its application logic may use standard .NET classes, but it could also depend on a native reporting library, a database provider with architecture-specific binaries, or a third-party DLL compiled only for x64.
The application may work correctly on an x64 machine but fail when built or published for Arm64.
Some common migration blockers include:
Project configurations that explicitly target x86 or x64.
Native DLLs that do not provide Arm64 binaries.
NuGet packages containing architecture-specific native assets.
P/Invoke declarations that depend on native library availability.
Processor-specific code or assumptions about instruction sets.
Build scripts that copy x64 binaries into the application output.
Installers that package only x64 executables and dependencies.
These problems can exist across multiple projects in the same solution.
For example, the main application may target Any CPU, while a supporting library uses an x64 native component. Changing the main project's architecture setting will not automatically make that dependency compatible with Arm64.
This is why a migration should begin with a dependency and configuration assessment rather than immediately changing the target architecture.
How GitHub Copilot Upgrade Agent Helps With Arm64 Migration
Microsoft has introduced a Windows Arm64 migration scenario in the GitHub Copilot upgrade agent.
The agent is designed to help developers move existing .NET applications from Windows x86 or x64 to Windows Arm64.
Instead of manually searching every project file and dependency, developers can ask the upgrade agent to analyze the application and identify the changes required for migration.
Its workflow covers several important activities.
First, it examines the existing .NET projects and their dependencies to understand the current architecture configuration.
Next, it identifies potential blockers, such as unsupported native libraries, architecture-specific settings, and dependencies that need compatible versions.
Based on the findings, it creates a migration plan. The plan describes the changes needed to move the application toward Arm64 compatibility.
The agent can then help update source code, dependencies, and project configuration. It can also build migrated components for Windows Arm64 and, when matching hardware or CI runners are available, execute tests to help validate runtime behavior.
The developer remains involved throughout the process. You can review the migration plan, inspect proposed changes, and provide input when the agent encounters decisions that require project-specific knowledge.
It is important to understand that the upgrade agent assists with migration; it does not guarantee that every application can be converted automatically. Native dependencies, unsupported components, and application-specific assumptions may still require manual work.
Installing the GitHub Copilot Upgrade Agent
The upgrade agent is available through multiple development environments, including Visual Studio, Visual Studio Code, GitHub Copilot CLI, and the GitHub Copilot app.
The installation requirements depend on the environment.
For Visual Studio, the documented prerequisites include Visual Studio 2026 or Visual Studio 2022 version 17.14.17 or later, the .NET desktop development workload, and the GitHub Copilot and GitHub Copilot app modernization optional components.
After installing the required components, open your existing .NET solution in Visual Studio.
You can access modernization functionality by right-clicking a project in Solution Explorer and selecting Modernize, or by using the Modernize agent in GitHub Copilot Chat.
For Visual Studio Code, install the GitHub Copilot upgrade extension from the Extensions view.
Open your project, start Copilot Chat, and select the Upgrade agent from the agent picker. You can also invoke it using the supported agent name.
For GitHub Copilot CLI, install the upgrade agent plugin through its marketplace:
/plugin marketplace add microsoft/upgrade-agent-plugins
/plugin install upgrade-agent@upgrade-agent-plugins
After installation, run the following command to check that the agent is available:
/agent
You should see the upgrade agent in the available agent list.
The exact installation requirements should be checked for your selected environment because supported capabilities can differ between development tools.
Analyzing an Existing .NET Application Before Migration
Once the upgrade agent is installed, open the existing solution and ask it to assess the application for Windows Arm64 compatibility.
For example, consider a solution containing the following projects:
LegacyBusinessApp/
│
├── LegacyBusinessApp.sln
│
├── DesktopClient/
│ ├── DesktopClient.csproj
│ └── Program.cs
│
├── BusinessLogic/
│ ├── BusinessLogic.csproj
│ └── OrderService.cs
│
├── DataAccess/
│ ├── DataAccess.csproj
│ └── DatabaseHelper.cs
│
└── SharedComponents/
├── SharedComponents.csproj
└── NativeIntegration.cs
The application may have architecture settings in the desktop project, while the native dependency is referenced through SharedComponents.
A useful instruction for the upgrade agent is:
Analyze this complete .NET solution for migration
from Windows x64 to Windows Arm64.
Inspect all projects, project configurations, NuGet
dependencies, native DLL references, P/Invoke declarations,
and architecture-specific build scripts.
Identify unsupported dependencies and potential
compatibility problems.
Do not modify any files yet.
Prepare a migration plan that explains the required
changes, affected projects, and validation steps.
This first assessment is important because it separates confirmed compatibility problems from assumptions that still need investigation.
For example, the agent might identify that the application targets x64, one NuGet package contains an x64-only native component, and another project references a native DLL directly.
These findings provide a starting point for the migration instead of requiring developers to discover every dependency manually.
Updating Project Configuration for Arm64
One of the first areas to inspect during migration is the project configuration.
.NET applications can use architecture-specific runtime identifiers when publishing applications for different platforms.
For a Windows Arm64 target, the runtime identifier is:
win-arm64
For comparison, the x64 and x86 Windows runtime identifiers are:
win-x64
win-x86
If the application uses a modern SDK-style project, you can configure the publish target in the project file or specify it directly through the command line.
For example, a project can define an Arm64 publish target:
<PropertyGroup>
<RuntimeIdentifier>win-arm64</RuntimeIdentifier>
<SelfContained>true</SelfContained>
</PropertyGroup>
Alternatively, you can publish the application without permanently changing the project configuration:
dotnet publish -c Release -r win-arm64 --self-contained true
This produces a self-contained Windows Arm64 deployment, subject to the compatibility of the application's dependencies.
If the application also needs to support x64, do not simply replace its existing architecture configuration without reviewing the deployment strategy.
You may need separate publish profiles or CI/CD jobs for each target architecture.
For older non-SDK-style projects, Windows desktop applications, and solutions containing native projects, architecture configuration may also be managed through Visual Studio solution platforms and project-specific settings.
The upgrade agent can help identify and update these settings, but developers should review the resulting project files to ensure that existing x64 builds continue to work.
Identifying and Replacing Unsupported Dependencies
Dependencies are often the most difficult part of a Windows Arm64 migration.
A managed NuGet package may work across different processor architectures, but a package that includes native libraries must provide compatible binaries for the target architecture.
Consider an application that uses a third-party native DLL through P/Invoke:
using System.Runtime.InteropServices;
internal static class NativeMethods
{
[DllImport("LegacyNativeLibrary.dll")]
public static extern int ProcessDocument(string filePath);
}
The C# declaration itself is not necessarily architecture-specific. However, the native library loaded at runtime must be compatible with the process architecture.
If the application is running as Arm64 but only an x64 version of the DLL is available, the native library cannot simply be loaded into the Arm64 process.
The migration agent can help identify this dependency and investigate whether an Arm64-compatible version is available.
There are several possible solutions.
If the library vendor provides an Arm64 release, update the application to use that version.
If the library is maintained internally, rebuild it using an Arm64-compatible toolchain.
If an open-source package does not provide Arm64 support, check whether a newer release includes the required binaries or whether the project can be updated.
If the dependency is no longer maintained, consider replacing it with a supported alternative.
The important point is that changing the runtime identifier does not convert an x64 native library into an Arm64 library. Every architecture-specific component must be accounted for.
Reviewing the Migration Changes With Copilot
After the initial assessment, the upgrade agent can help implement the migration plan.
It may update project settings, change compatible package versions, modify architecture-specific code, or adjust build configuration.
However, do not accept all changes without reviewing their impact.
For example, suppose the agent replaces an older native library with a newer version that supports Arm64.
You should verify whether the new version preserves the existing API, whether it changes licensing requirements, and whether it introduces new runtime dependencies.
Similarly, if the agent changes the project configuration, check that the existing x64 build remains available when the application still needs to support x64 customers.
A useful follow-up instruction is:
Apply the approved Windows Arm64 migration plan.
Preserve existing application behavior and maintain
x64 compatibility where required.
Update only the necessary source files, dependencies,
and project configuration.
Explain every significant change and identify any
migration steps that still require manual intervention.
This gives the agent a clear scope while keeping the developer involved in important decisions.
Review the resulting changes using your normal source-control workflow. Smaller, understandable changes are easier to validate and troubleshoot than a large migration patch that modifies unrelated application behavior.
Building and Testing the Arm64 Application
A successful compilation is an important milestone, but it does not prove that the application works correctly on Windows Arm64.
The application must be tested on an actual Arm64 device or a suitable Windows Arm64 virtual machine.
For an SDK-style .NET application, you can start by publishing the Arm64 build:
dotnet publish -c Release -r win-arm64 --self-contained true
After publishing, verify that the expected application files and architecture-specific dependencies are present.
You should then test the application on a Windows Arm64 environment.
Pay particular attention to native library loading, database connectivity, file operations, authentication, background processing, and any functionality that communicates with external devices or operating system components.
If the application uses Windows drivers, remember that kernel-mode drivers must be compiled natively for Arm64. Windows emulation does not provide support for x86 or x64 kernel drivers.
For automated validation, add an Arm64 environment to your CI/CD pipeline. Run the existing test suite against the native build instead of relying exclusively on x64 testing.
Also maintain separate test results for each supported architecture. This helps identify issues that occur only in the Arm64 build.
Publishing and Maintaining Multiple Architectures
Migrating an application to Arm64 does not necessarily mean discontinuing x64 support.
Many organizations need to support both architectures because customers may use a mixture of traditional x64 Windows devices and newer Arm64 devices.
Your deployment process should account for this requirement.
For example, you can maintain separate publish configurations for x64 and Arm64:
dotnet publish -c Release -r win-x64 --self-contained true
dotnet publish -c Release -r win-arm64 --self-contained true
If you distribute the application through an installer, make sure the installer can select or deliver the correct architecture.
For Microsoft Store distribution, architecture-specific packages can be included in a submission so that the appropriate package is delivered to supported devices.
For direct distribution, your download and installation process should clearly identify which architecture is supported.
Also keep application features and release versions aligned across architectures. An Arm64 release should not become a separate product with a different maintenance schedule unless there is a deliberate reason for doing so.
Common Migration Problems and How to Handle Them
Several issues can appear during the migration process.
Native DLL Cannot Be Loaded
This usually indicates that a native dependency is missing, incompatible with Arm64, or located in an unexpected directory.
Check the architecture of the DLL and verify that an Arm64 version is available. Also review the library loading path and any runtime-specific native asset configuration.
NuGet Package Does Not Support Arm64
Some packages contain architecture-specific native components.
Inspect the package's supported runtime assets and check whether an updated version provides Windows Arm64 support. If no compatible version exists, consider rebuilding, replacing, or removing the dependency.
Application Builds but Fails at Runtime
A successful build does not guarantee that every runtime dependency is compatible.
Test the application on a native Arm64 environment and inspect runtime errors, native library loading failures, and architecture-specific code paths.
Existing x64 Deployment Stops Working
This can happen when architecture settings or package versions are changed without preserving the existing x64 configuration.
Maintain separate architecture-specific publish targets and include both in regression testing.
Installer Does Not Recognize Arm64
An installer may contain assumptions about processor architecture or package locations.
Update the installer configuration, verify its detection logic, and test installation and upgrade scenarios on both x64 and Arm64 devices.
Best Practices for a Successful Migration
A successful Arm64 migration requires more than changing the processor architecture in a project file.
Start with a complete assessment of the solution and its dependencies. Identify native components before changing project configuration, because these dependencies often determine how much migration work is required.
Keep the original x64 build available until the Arm64 version has passed functional and integration testing.
Use the GitHub Copilot upgrade agent to accelerate analysis and repetitive changes, but review its migration plan and proposed patches before accepting them.
Test on actual Windows Arm64 hardware or a suitable virtual machine. Do not rely entirely on running an x64 application through emulation as proof that the native build works.
Finally, update the deployment process and CI/CD pipeline so that Arm64 compatibility remains part of the application's regular release process.
Summary
Moving an older .NET application to Windows Arm64 does not always require a complete rewrite. Many managed applications can be migrated by addressing architecture-specific configuration, replacing unsupported native dependencies, and validating the resulting build.
The GitHub Copilot upgrade agent makes this process more manageable by analyzing existing projects, identifying compatibility blockers, preparing migration plans, and helping implement the required changes.
However, automated migration is only part of the work. Developers must still review the changes, verify native dependency compatibility, test runtime behavior on Windows Arm64, and maintain support for other architectures when required.
The most effective approach is to combine AI-assisted migration with careful dependency analysis, automated testing, and human review. This helps modernize existing .NET applications while reducing unnecessary manual investigation and preserving the behavior that existing users depend on.
Join the conversation! Your thoughts help the community grow.