XAF - Converter for Legacy API

XAF v25.2+ no longer supports .NET Framework and certain legacy APIs and features based on .NET. Review the full list of non-supported APIs in the following knowledge base article: T1312589 - XAF - Legacy .NET Framework (WinForms and ASP.NET WebForms) APIs, .NET-based API/Modules, and Security System have been removed from distribution.

This repository includes our XafApiConverter utility - designed for those migrating an XAF application to v25.2+. It automates the following routine migration tasks:

1. Updates legacy security APIs.
2. Removes .NET Framework APIs, and legacy .NET-based APIs and modules.
3. Converts an application from .NET Framework to .NET.

Full step-by-step migration guide:

• Migrate XAF ASP.NET WebForms to ASP.NET Core Blazor

How to Use the Converter

Important

XafApiConverter analyzes semantic trees based on DevExpress product versions. To recognize types correctly, conversion should be performed against a v25.1 based application.

1. Download the repository.
2. Open the XafApiConverter/Source/XafApiConverter.sln solution.
3. Build the solution.
4. Once complete, run the executable file from the command line. Use the following command format:

XafApiConverter.exe <path> <step> [step] [step] [options]

<path> - the path to the .sln file or project folder.

<step> - the migration step to perform. You can run several steps simultaneously in the following order:

• security-update step updates legacy security types:
  • Replaces SecuritySystem* with PermissionPolicy*
  • Removes obsolete feature toggles
  • Adds PermissionPolicyRoleExtensions
  • Updates permission state setters
• migrate-types step removes .NET Framework APIs, and legacy .NET-based APIs and modules. The tool marks or comments out problematic classes.
• project-conversion step converts projects from .NET Framework to .NET:
  • Converts .csproj to SDK-style format
  • Updates the target framework to .NET 9/10
  • Adds NuGet packages (base, Microsoft, Blazor) if needed
  • Removes legacy assembly references
  • Validates converted projects
  • Changes System.Data.SqlClient to Microsoft.Data.SqlClient
  • Changes DevExpress.ExpressApp.Web.* to DevExpress.ExpressApp.Blazor.*
  • Replaces types (for instance, WebApplication with BlazorApplication)
  • Processes .cs and .xafml files

Options

-tf, --target-framework - sets target .NET version: net8.0, net9.0 (default), or net10.0.

-dx, --dx-version - sets version of added/updated DevExpress packages, for instance: 25.2.2, 26.1.6. The default is 25.1.6.

-o, --output <path> - sets folder to save reports.

-b, --backup - creates backup files.

-dp, --directory-packages - adds/uses the Directory.Packages.props file to manage common dependencies across all projects within a solution.

-c, --comment-issues-only - adds comments to every problematic class without commenting out the code.
When you do not use this option, the converter comments out problematic classes. The tool only adds a warning to protected classes (such as ModuleBase and BaseObject).

-m, --show-mappings - displays all type and namespace mappings.

-h, --help - displays complete list of available options.

Command Usage Examples

Migrate XAF Application from Web Forms to ASP.NET Core Blazor

XafApiConverter.exe MySolution.sln security-update migrate-types project-conversion -tf net10.0 -b

Note

Migrating from Web Forms to ASP.NET Core Blazor involves number of manual steps, detailed in the following topic: Migrate XAF ASP.NET WebForms to ASP.NET Core Blazor. We recommend that you follow the steps in order and use the XafApiConverter tool as described herein.

Update legacy XAF Security System APIs

XafApiConverter.exe MySolution.sln security-update -b

Remove legacy .NET-based APIs and modules from XAF WinForms/Blazor Application

XafApiConverter.exe MySolution.sln migrate-types -b

Migrate XAF WinForms Application from .NET Framework to .NET

XafApiConverter.exe MySolution.sln security-update migrate-types project-conversion -b

Remove legacy .NET Framework APIs from XAF WinForms/Web Forms Application

XafApiConverter.exe MySolution.sln migrate-types -b

Does This Example Address Your Development Requirements/Objectives?

(you will be redirected to DevExpress.com to submit your response)