You can move an MDriven application from .NET Framework to .NET Core/.NET 8 by updating your development project, deploying the Core editions of MDrivenServer and Turnkey where applicable, and restoring your backed-up application data.

This guide is for teams moving an existing MDriven application from .NET Framework, including Visual Studio-based MDriven projects and deployed MDriven Turnkey applications. Plan the migration as a controlled replacement: back up first, make the project compile on .NET 8, prepare the hosting environment, configure the Core application overrides, and then restore and test.

Before you begin

Use current MDriven tooling before changing the application:

• Update MDriven Designer for model projects.
• Update the MDriven Visual Studio extension for Visual Studio model projects.
• Download current tooling from MDriven Downloads.
• For a Visual Studio project, use Visual Studio 2022 or later and the MDriven Visual Studio extension.

MDriven recommends moving .NET Framework 4.8 applications to .NET 8 and using MDriven NuGet packages for .NET 8 rather than assemblies from an installation directory. .NET 8 does not use the Global Assembly Cache (GAC), which avoids the GAC taking precedence over assemblies deployed with your application. Read Documentation:Dotnet core for the MDriven .NET direction and package guidance.

Migration overview

Stage	What you do	Result
Back up	Save application data and user data before replacing deployed components.	You have a recovery point and data to restore after deployment.
Update the development project	Retarget a Visual Studio-based project to .NET 8, replace dependencies with the appropriate MDriven NuGet packages, and build the solution.	Your project compiles against the .NET 8 runtime.
Prepare hosting	Deploy the Core edition of MDrivenServer and/or MDriven Turnkey using the instructions for your hosting platform.	The target environment is ready to run the Core applications.
Configure overrides	Set connection, Turnkey, and command-line settings in the files under App_Data.	Settings survive application upgrades and the application starts with the intended arguments and URL.
Restore and verify	Restore data, confirm Turnkey can connect to MDrivenServer, and test the application.	The migrated application is operational.

1. Back up application and user data

Create and verify a backup before changing the project, server, Turnkey installation, or hosting configuration.

1. Follow the MDriven Backup & Restore Guide to back up the application data and user data.
2. Keep the backup separate from the deployment folder that you will replace or upgrade.
3. Record the current application URL and the credentials used by Turnkey to connect to MDrivenServer. You will need these when configuring the Core deployment.

For example, if your production Turnkey site currently connects to an MDrivenServer at a configured URL, preserve both the data backup and the connection details before deploying the Core versions.

2. Update a Visual Studio MDriven project

This section applies when you have a Visual Studio project that currently targets .NET Framework. If you are only replacing a deployed Turnkey or MDrivenServer installation, continue with Prepare the hosting environment.

1. Open the solution in Visual Studio 2022 or later.
2. Change the project target framework from .NET Framework to .NET 8.
3. Replace .NET Framework-specific MDriven assembly references with the applicable MDriven NuGet packages for .NET 8. Use package versions as the identity of the MDriven binaries rather than relying on assembly versions or installed assemblies.
4. Build the solution and resolve all compilation errors before deploying it.
5. If the project includes an MDriven model, confirm that the model files and generated code are part of the project as required by your application.

For the complete procedure for creating or preparing a .NET MDriven project, including saving a model as .ecomdl, using Assets_TK for CodeDress, generating C# code, and uploading assemblies, follow HowTos:How To Create a .NET Core MDriven Project.

Project migration checks

Check	Why it matters
The project targets .NET 8	MDriven identifies .NET 8 as the current long-term supported migration direction.
MDriven dependencies come from NuGet packages intended for .NET 8	NuGet provides versioned compiled code and avoids dependency on installed assemblies or the GAC.
The solution builds without errors	Compilation issues must be resolved before you can validate deployment behavior.
The model and generated code are included where required	A Visual Studio MDriven project needs its model artifacts and generated code available to the application.

If legacy code uses WCF, review it during migration. MDriven's .NET guidance states that WCF is not being moved forward and that WebApi is the communication direction. See Documentation:Dotnet core.

3. Prepare the hosting environment

Deploy the Core editions of the components your application uses. MDrivenServer and MDriven Turnkey are separate applications, so prepare each one that is part of your deployment.

IIS

For IIS hosting, follow Deploying MDriven Server & Turnkey Core on IIS. Configure IIS for the Core deployment and make sure the application URL configured for each application matches the IIS site address.

Microsoft Azure

For Azure hosting, follow Installing MDriven Server and Turnkey on Microsoft Azure to set up the current MDriven Turnkey and MDrivenServer deployment on Azure.

Turnkey data file

For MDriven Turnkey Core, ensure that the XML file containing data is in the same directory as the model and uses the .PrototypeData.xml naming convention.

4. Configure Core application settings

Core deployments keep upgrade-safe settings in override files under App_Data. Configure these files after deployment and preserve them when you upgrade the application.

File	Used by	Purpose
App_Data/MDrivenServerOverride.xml	Turnkey	Stores the credentials Turnkey uses to connect to MDrivenServer.
App_Data/TurnkeySettingsOverride.xml	Turnkey	Stores Turnkey settings outside the application files so they are retained on upgrade.
App_Data/CommandLineOverride.xml	MDrivenServer and MDriven Turnkey	Stores command-line arguments used when the application starts, including the application URL.

1. Configure MDrivenServerOverride.xml with the credentials that the Turnkey application must use to connect to MDrivenServer.
2. Configure TurnkeySettingsOverride.xml with the Turnkey settings that must remain in place after an application upgrade.
3. Create and configure CommandLineOverride.xml for both MDrivenServer and MDriven Turnkey.
4. Set the application URL in each CommandLineOverride.xml file. When you host in IIS, this URL identifies the application address IIS should use.

For example, a deployment with both MDrivenServer and Turnkey has two CommandLineOverride.xml files: one in the MDrivenServer application's App_Data folder and one in the Turnkey application's App_Data folder. Both must be configured for their respective application URLs.

5. Restore data and verify the deployment

1. Restore application data and user data using the MDriven Backup & Restore Guide.
2. Start MDrivenServer and Turnkey using their configured command-line overrides.
3. Open the deployed Turnkey URL and verify that Turnkey connects to MDrivenServer.
4. Test a representative user flow, such as signing in and opening data restored from the backup.
5. If your application uses realtime updates, verify that clients can connect after the migration. Documentation:SignalR and Realtime explains the Framework and Core SignalR compatibility behavior.

If Turnkey is blocked from connecting to MDrivenServer, use PwdReset to set a new password for user a, then update the MDrivenServer connection credentials in App_Data/MDrivenServerOverride.xml as needed.

Migration boundaries

This page covers the migration sequence. Use the linked pages for implementation details rather than changing deployment files by trial and error:

• HowTos:How To Create a .NET Core MDriven Project explains how to prepare a .NET MDriven Visual Studio project.
• Documentation:MDriven Turnkey Core covers Turnkey Core-specific requirements.
• Documentation:Dotnet core describes MDriven's .NET 8, NuGet, GAC, and MDrivenServer Core guidance.
• Documentation:Framework provides the broader MDriven Framework documentation.

See also

• HowTos:How To Create a .NET Core MDriven Project
• Documentation:Dotnet core
• Documentation:MDriven Turnkey Core
• Documentation:SignalR and Realtime
• Documentation:.net version

Plan scalability after the .NET Core migration

You can scale a migrated MDriven application for read load or regional latency by distributing MDrivenServer instances after the application is running on .NET Core.

This migration moves an existing MDriven project from .NET Framework to .NET Core. It does not describe importing a legacy .NET or WinForms database schema into MDriven, reusing business logic from that application, or running a phased legacy-to-MDriven replacement.

Scale read traffic with MDrivenServer distribution

Use MDrivenServer distribution when users need lower latency in another region or when read traffic warrants additional servers. The distribution design assumes that data reads are more common than data writes.

Component	Responsibility	Operational result
Master MDrivenServer	Receives all data writes and commits data blocks.	One server remains the write authority.
Slave MDrivenServer	Serves its own database, routes save requests to the Master, and polls the Master for committed updates.	Users can read from the Slave while the Slave receives committed changes from the Master.

For example, place a Slave closer to a group of users that is far from the Master. The Slave initiates communication with the Master, sends a user's save request to the Master, and then receives committed data blocks to merge into its own database.

Account for consistency and failure behavior

A Slave is updated from committed data blocks received from the Master. Given time and working network paths, the Slave reaches the same content as the Master. This is a distribution trade-off: data at separate locations cannot always be exactly equal at the same point in time.

If a Slave cannot reach the Master, users connected to that Slave cannot save data and the Slave does not receive updates. Saving and synchronization resume when the Slave can reach the Master again.

Keep every Slave on the same model as the Master. MDrivenServer records a model checksum with each persisted commit block so that differing models are detected during distribution.

Prepare the database and deployment

MDrivenServers in a distribution cluster require an additional database table for commit blocks. The transaction that updates business data also records commit-block information, which keeps the Master consistent when its database is restored from backup. Because the additional table structure is the same on the Master and Slaves, you can use a Master database backup to deploy a new Slave.

Use the deployment guidance for your hosting environment when you add or move servers. See Deployment for IIS, Azure, Docker, and Linux deployment topics.

Validate capacity in your environment

Establish a baseline before and after the .NET Core migration, then repeat it after adding a Slave. Test both read activity and saves, because writes are accepted by the Master even when a user is connected to a Slave. Also test the expected network path between each Slave and the Master, including loss of connectivity, so that the no-save behavior is understood before production use.

See also

• Documentation:Scaling MDrivenServer for multiple reasons
• Documentation:Deployment
• Documentation:Memory optimization
• Documentation:Dotnet core

Migration checklist

You can use this checklist to migrate an MDriven application from .NET Framework to .NET Core and verify each required task before you restore users to the application.

Migration checklist

Complete the items in order. For example, do not restore application data until the .NET Core application is deployed and its override files are configured.

Step	Check	What to verify
1. Update tools	☐	Use the latest MDriven Designer for Model projects and the latest MDriven Visual Studio extension for Visual Studio Model projects. Download them from MDriven Downloads.
2. Back up data	☐	Back up the MDriven application data and user data. Follow MDriven Backup & Restore Guide.
3. Upgrade the project	☐	For a Visual Studio project that targets .NET Framework, change the target framework to .NET Core. .NET 8 or .NET 9 is supported by this migration guidance. Compile the project with no errors. See How To Create a .NET Core MDriven Project.
4. Prepare hosting	☐	Configure the .NET Core hosting environment. For IIS, use Deploying MDriven Server & Turnkey Core on IIS. For Azure, use Installing MDriven Server and Turnkey on Microsoft Azure.
5. Configure MDriven Server and Turnkey	☐	Configure App_Data/MDrivenServerOverride.xml with the credentials that Turnkey uses to connect to MDriven Server. Configure Turnkey settings in App_Data/TurnkeySettingsOverride.xml so that the settings are retained when the application is upgraded.
6. Configure startup arguments	☐	Create and configure App_Data/CommandLineOverride.xml for both MDriven Server and MDriven Turnkey. This file contains the command-line arguments used to start the applications. Set the application URL in this file so IIS points to the application.
7. Restore data	☐	Restore the application data by following MDriven Backup & Restore Guide.
8. Verify the Turnkey connection	☐	Confirm that Turnkey connects to MDriven Server. If Turnkey is blocked from connecting, use PwdReset to set a new password for user a.

See also

• MDriven Backup & Restore Guide
• How To Create a .NET Core MDriven Project
• Deployment