View source for Documentation:Migrating From MDriven .NET Framework to .NET Core

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 [[Documentation:MDriven designer overview Part 1|MDriven Designer]] for model projects.
* Update the MDriven Visual Studio extension for Visual Studio model projects.
* Download current tooling from [https://mdriven.net/App#/Downloads 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 ==

{| class="wikitable"
! 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 <code>App_Data</code>.
| 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.

# Follow the [[MDriven Backup & Restore Guide]] to back up the application data and user data.
# Keep the backup separate from the deployment folder that you will replace or upgrade.
# 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 [[#3. Prepare the hosting environment|Prepare the hosting environment]].

# Open the solution in Visual Studio 2022 or later.
# Change the project target framework from .NET Framework to '''.NET 8'''.
# 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.
# Build the solution and resolve all compilation errors before deploying it.
# 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 <code>.ecomdl</code>, using <code>Assets_TK</code> for [[Documentation:CodeDress|CodeDress]], generating C# code, and uploading assemblies, follow [[HowTos:How To Create a .NET Core MDriven Project]].

=== Project migration checks ===

{| class="wikitable"
! 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 [[Documentation:Installing MDriven Server and Turnkey on Microsoft Azure|Installing MDriven Server and Turnkey on Microsoft Azure]] to set up the current MDriven Turnkey and MDrivenServer deployment on Azure.

=== Turnkey data file ===

For [[Documentation:MDriven Turnkey Core|MDriven Turnkey Core]], ensure that the XML file containing data is in the same directory as the model and uses the <code>.PrototypeData.xml</code> naming convention.

== 4. Configure Core application settings ==

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

{| class="wikitable"
! File
! Used by
! Purpose
|-
| <code>App_Data/MDrivenServerOverride.xml</code>
| Turnkey
| Stores the credentials Turnkey uses to connect to MDrivenServer.
|-
| <code>App_Data/TurnkeySettingsOverride.xml</code>
| Turnkey
| Stores Turnkey settings outside the application files so they are retained on upgrade.
|-
| <code>App_Data/CommandLineOverride.xml</code>
| MDrivenServer and MDriven Turnkey
| Stores command-line arguments used when the application starts, including the application URL.
|}

# Configure <code>MDrivenServerOverride.xml</code> with the credentials that the Turnkey application must use to connect to MDrivenServer.
# Configure <code>TurnkeySettingsOverride.xml</code> with the Turnkey settings that must remain in place after an application upgrade.
# Create and configure <code>CommandLineOverride.xml</code> for '''both''' MDrivenServer and MDriven Turnkey.
# Set the application URL in each <code>CommandLineOverride.xml</code> 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 <code>CommandLineOverride.xml</code> files: one in the MDrivenServer application's <code>App_Data</code> folder and one in the Turnkey application's <code>App_Data</code> folder. Both must be configured for their respective application URLs.

== 5. Restore data and verify the deployment ==

# Restore application data and user data using the [[MDriven Backup & Restore Guide]].
# Start MDrivenServer and Turnkey using their configured command-line overrides.
# Open the deployed Turnkey URL and verify that Turnkey connects to MDrivenServer.
# Test a representative user flow, such as signing in and opening data restored from the backup.
# 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 <code>PwdReset</code> to set a new password for user <code>a</code>, then update the MDrivenServer connection credentials in <code>App_Data/MDrivenServerOverride.xml</code> 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.

== 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 [[Documentation:Scaling MDrivenServer for multiple reasons|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.

{| class="wikitable"
! 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 [[Documentation:Deployment|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.

== 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.

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.

{| class="wikitable"
! 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 [https://mdriven.net/App#/Downloads MDriven Downloads].
|-
| 2. Back up data
| ☐
| Back up the MDriven application data and user data. Follow [[Documentation:MDriven Backup & Restore Guide|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 [[HowTos:How To Create a .NET Core MDriven Project|How To Create a .NET Core MDriven Project]].
|-
| 4. Prepare hosting
| ☐
| Configure the .NET Core hosting environment. For IIS, use [[Documentation:Deploying MDriven Server & Turnkey Core on IIS|Deploying MDriven Server & Turnkey Core on IIS]]. For Azure, use [[Documentation:Installing MDriven Server and Turnkey on Microsoft Azure|Installing MDriven Server and Turnkey on Microsoft Azure]].
|-
| 5. Configure MDriven Server and Turnkey
| ☐
| Configure <code>App_Data/MDrivenServerOverride.xml</code> with the credentials that Turnkey uses to connect to MDriven Server. Configure Turnkey settings in <code>App_Data/TurnkeySettingsOverride.xml</code> so that the settings are retained when the application is upgraded.
|-
| 6. Configure startup arguments
| ☐
| Create and configure <code>App_Data/CommandLineOverride.xml</code> 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 [[Documentation:MDriven Backup & Restore Guide|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 <code>a</code>.
|}

== 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]]
* [[Documentation:Scaling MDrivenServer for multiple reasons]]
* [[Documentation:Deployment]]
* [[Documentation:Memory optimization]]
* [[Documentation:MDriven Backup & Restore Guide|MDriven Backup & Restore Guide]]
* [[HowTos:How To Create a .NET Core MDriven Project|How To Create a .NET Core MDriven Project]]
* [[Documentation:Deployment|Deployment]]

[[Category:Deprecation and migration strategies]]
[[Category:Intermediate-Friendly]]
[[Category:Priority 70]]
[[Category:Refactoring and Evolution]]