Deployment Troubleshooting Guide | XAF: Cross-Platform .NET App UI & Web API

Oct 18, 2022
22 minutes to read

This topic provides a list of common deployment problems and ways of resolving them. It is assumed that the application runs normally at the Developer Workstation. Follow the recommendations below if you face a problem with deployment.

1. Windows Forms Specific Problems

1.1 The “application failed to initialize properly” error message is displayed

1.2 The “could not load file or assembly” error message is displayed

1.3 An error message containing insufficient information is displayed

1.4 Resolve the ‘DevExpress.Assembly.Name.vXX.X’ assembly Exception thrown: ‘System.IO.FileNotFoundException’

1.5 Logged errors are not available, although the application fails to start

1.6 Cannot store individual customizations in a multi-user environment

1.7 “Unable to save customization information” error is displayed on exit

1.8 “The LogonParameters file is inaccessible”

1.9 The application cannot find the Updater executable

1.10 The ‘1113’ error occurs

1.11 “Cannot create temporary file” error message is displayed

1.12 User customizations are lost after updating the ClickOnce deployment

2. ASP.NET Web Forms Specific Problems

2.1 The server error occurs and error details are unavailable

2.2 The error message states that an assembly could not be loaded

2.3 The ‘500.22’ internal server error occurs

2.4 Missing icons and images

2.5 The application does not open after changing session state mode to StateServer or SQLServer

2.6 Issues when running the ASP.NET Web Forms application

2.7 Issues with an ASP.NET Web Forms application built for .NET Framework 4.0

2.8 Unexpected redirects to the logon page occur when running ASP.NET Web Forms application

3. Platform Independent Problems

3.1 Numerous assemblies are missing

3.2 “The application cannot connect to the specified database” error is displayed

3.3 The ‘1111’ error occurs when running the application or DBUpdater

3.4 The application cannot connect the database, although the DBUpdater reports no error

3.5 The DBUpdater reports that the database does not exist

3.6 The DBUpdater reports the ‘1110’ error

3.7 The DBUpdater cannot update the database, as it cannot connect to the database server

3.8 The DBUpdater cannot update the database due to invalid credentials

3.9 Performance issues when working with a large amount of data

3.10 The “An attempt was made to load a program with an incorrect format” error occurs when starting the DBUpdater or standalone Model Editor tool on an x64 system

1. Windows Forms Specific Problems

1.1 The “application failed to initialize properly” error message is displayed

Problem Description:

Windows displays an Application Error window with the following text.

The application failed to initialize properly (0xc0000135). Click OK to terminate the application.

Solution:

This may happen if you try to launch an XAF Windows Forms application at the workstation with Windows XP or an older Windows version installed. These systems do not have Microsoft .NET Framework installed by default. Download and install the .NET framework of the appropriate version from the Microsoft Download Center.

1.2 The “could not load file or assembly” error message is displayed

Problem Description:

When loading, the application displays the following error message.

Deployment_Tutorial_0040

Could not load file or assembly ‘DevExpress.XtraTreeList.v9.2, Version=9.2.8.0, Culture=neutral, PublicKeyToken=b88d1754d700e49a’ or one of its dependencies. The system cannot find the file specified.

Assembly name, version, etc., may be different.

The assembly mentioned in the error message is missing from the application folder. Copy it from the Developer Workstation. It is usually located in the %PROGRAMFILES(x86)%\DevExpress 21.2\Components\Bin\Framework folder.

1.3 An error message containing insufficient information is displayed

Problem Description:

When loading, the application displays an error message that looks like this.

Deployment_Tutorial_0050

Exception occurs while loading schema from DevExpress.ExpressApp.Win.SystemModule.SystemWindowsFormsModule The type initializer for ‘DevExpress.ExpressApp.Win.SystemModule.DefaultSkinListGenerator’ threw an exception.

The details of the message may be different. Generally, the message does not contain enough information on how to resolve the error.

Solution:

To find the cause of the error, open the application log file. The log file is a text file located in the application folder or in the user’s application data folder, and has the most recent modification time. Find the text matching the error message and analyze what happened before the error occurred. For instance, this error can be caused by a missing assembly. For details, see the next item.

1.4 Resolve the ‘DevExpress.Assembly.Name.vXX.X’ assembly Exception thrown: ‘System.IO.FileNotFoundException’

Problem Description:

The following text is written to the application log before a warning occurs:

Deployment_Tutorial_0060

10.03.22 12:35:36.750 Resolve the ‘DevExpress.Assembly.Name.vXX.X’ assembly Exception thrown: ‘System.IO.FileNotFoundException’ in mscorlib.dll

An assembly name and version may be different.

Solution:

Outdated records in the XPObjectType table cause these warnings. Use one of the following options to avoid them:

Ignore these diagnostic messages since they are non-critical.
Change the assembly name in the AssemblyName column of the XPObjectType table in the database to point to the latest application version. For example, change the assembly name from DevExpress.Persistent.BaseImpl.v10.1 to DevExpress.Persistent.BaseImpl.Xpo.v21.2.
Override the UpdateDatabaseBeforeUpdateSchema() method and call UpdateXPObjectType for all required classes. See the following topic for details: How to: Handle Renamings and Deletions of Business Classes and their Properties, XPO - Old business class assemblies may be loaded from the application folder or GAC and cause side effects in .NET Framework apps (due to outdated XPObjectType records).

1.5 Logged errors are not available, although the application fails to start

Problem Description:

The application log file does not contain errors, or you cannot find the log file, although the application fails to start, and it is not possible to determine exactly what happens from the displayed error message.

Solution:

Check that logging is enabled in the application configuration file. This is the <Application_Name>.Win.exe.config XML file located in the application folder. Open this file in a text editor and check that the TraceLogLocation key in the appSettings section is not set to None.

Check that the user account that you use to start the application has the appropriate permissions to write to the log file. For instance, Windows Vista does not allow non-administrative users to write anything to Program Files subfolders. To resolve this issue, you can do one of the following:

grant write permissions to a user;
run the application as an administrator;
open the configuration file and set the TraceLogLocation key in appSettings section to CurrentUserApplicationDataFolder (each user has permission to write to their application data folder).
- XML
```
<appSettings>
    
    <add key="TraceLogLocation" value="CurrentUserApplicationDataFolder"/>
    
</appSettings>
```

Note

The default location of the application data folder varies in different Windows versions.

1.6 Cannot store individual customizations in a multi-user environment

Problem Description:

A Windows Forms application is installed on a Terminal Server and multiple users use it simultaneously, or it is installed on an End-User Workstation with multiple local logins enabled. User customizations interfere with each other, making individual customizations impossible.

Solution:

Open the configuration file and set the UserModelDiffsLocation key in the appSettings section to CurrentUserApplicationDataFolder.

<appSettings>
    <!-- ... -->
    <add key="UserModelDiffsLocation" value="CurrentUserApplicationDataFolder"/>
    <!-- ... -->
</appSettings>

This allows each user to store individual customizations.

Another solution is provided in the How to: Store the Application Model Differences in the Database topic.

1.7 “Unable to save customization information” error is displayed on exit

Problem Description:

A Windows Forms application launches and runs normally, however the following error message is displayed on exit.

DTG_01

Unable to save customization information.

Solution:

Check that the user account used to start the application has appropriate permissions to write to the Model.User.xafml file. This file location is specified by the UserModelDiffsLocation key in the application configuration file. By default, the Model.User.xafml file is located in the application folder. Typically, non-administrative users have no permission to write anything to Program Files subfolders. To resolve this issue, you can do one of the following:

grant write permissions to a user;
open the configuration file and set the UserModelDiffsLocation key in the appSettings section to CurrentUserApplicationDataFolder (each user has permission to write to their application data folder).

1.8 The LogonParameters file is inaccessible

Problem Description:

The following error is displayed after clicking the Log On button.

Access to the path ‘C:\Program Files\MySolution\LogonParameters’ is denied.

Solution:

Check that the user account used to start the application has appropriate permissions to write to the LogonParameters file. This file is used to save the logon parameters (user name by default), and is located together with the Model.User.xafml file. The location is specified by the UserModelDiffsLocation key in the application configuration file. By default, the LogonParameters file is located in the application folder. Typically, non-administrative users do not have permission to write anything to Program Files subfolders. To resolve this issue, you can do one of the following:

grant a write permission to a user;
open the configuration file and set the UserModelDiffsLocation key in the appSettings section to CurrentUserApplicationDataFolder (each user has permission to write to their application data folder).

1.9 The application cannot find the Updater executable

Problem Description:

When loading, the application displays the following error message.

DTG_03

_Could not find file ‘\FILESERVER\MySolutionUpdateSource

\DevExpress.ExpressApp.Updater.exe’._

Solution:

The database was updated and an automatic update was initiated. The NewVersionServer value in the application configuration file is not empty. However, the Updater utility was not found. Check that the DevExpress.ExpressApp.Updater.exe file exists in the update source folder. You can get this file from the Developer Workstation (this file path is %PROGRAMFILES(x86)%\DevExpress 21.2\Components\Tools\eXpressAppFramework\DBUpdater\DBUpdater.v21.2.exe). Check that the NewVersionServer value is correct.

1.10 The ‘1113’ error occurs

Problem Description:

When loading, the application displays the following error message.

DTG_02

An error with number 1113 has occurred. Error message: Cannot run the application. The database version is newer than the application version, but the server with the new application version is not found. Ask the administrator to check that the configuration file contains a correct path to the new application version.

Solution:

The database was updated and an automatic update was initiated. The NewVersionServer value in the application configuration file is not empty. However, the update source folder cannot be accessed. Check that the NewVersionServer key value is correct and the shared folder referenced by it is accessible.

1.11 “Cannot create temporary file” error message is displayed

Problem Description:

When loading, the application displays the following error message.

DTG_08

Cannot compile the generated code. Please inspect the generated code via this exception’s SourceCode property. The following errors occurred: (0,0): Cannot create temporary file ‘c:\Program Files\MySolution\CSC27CD.tmp’ – Access is denied.

Solution:

Starting with version v2011 vol 1, XAF can dynamically create assemblies at run time to cache the structure of Domain Components used in the application (see XAF – Core & Performance Improvements). This can be done, for instance, to store the Application Model Structure. By default, your application will try to create temporary files in the folder it is installed in. If the application is not allowed to write to this folder, you will see an error message. To solve the issue, you can specify exact cache file names that the application will be allowed to create and modify. This is done by overriding the XafApplication‘s protected GetDcAssemblyFilePath, GetModelAssemblyFilePath and GetModulesVersionInfoFilePath methods. Alternatively, you can override these methods to return null (Nothing in VB) to specify that caching should be disabled.

WinApplication.cs(WinApplication.vb)

C#
VB.NET

public partial class MySolutionWindowsFormsApplication : WinApplication {
    //...
    protected override string GetDcAssemblyFilePath() {
        return null;
    }
    protected override string GetModelAssemblyFilePath() {
        return null;
    }
    protected override string GetModulesVersionInfoFilePath() {
        return null;
    }
}

Partial Public Class MySolutionWindowsFormsApplication
    Inherits WinApplication
    '...
    Protected Overrides Function GetDcAssemblyFilePath() As String
        Return Nothing
    End Function
    Protected Overrides Function GetModelAssemblyFilePath() As String
        Return Nothing
    End Function
    Protected Overrides Function GetModulesVersionInfoFilePath() As String
        Return Nothing
    End Function
End Class

1.12 User customizations are lost after updating the ClickOnce deployment

Problem Description:

A Windows Forms application is deployed using Publish Wizard Deployment of a Windows Forms Application. User customizations are lost each time the application is updated.

Solution:

The solution is the same as for the Cannot store individual customizations in a multi-user environment issue.

2. ASP.NET Web Forms Specific Problems

2.1 The server error occurs and error details are unavailable

Problem Description:

The error message is displayed in a browser window when trying to open an ASP.NET Web Forms application:

Deployment_Tutorial_1020

The details of this message can differ. For instance it can be the “500 - Internal Server Error“ instead of the “404 - File Not Found“ error. Generally, the message does not contain enough information on how to resolve the error.

Solution:

Web Server error messages may contain information meant only for the developer and not for public access. That is why the display of unhandled error information is disabled in ISS by default. Launch the browser at the Web Server locally, and open your application, if possible. If you have no such access, modify the application Web.config file as shown below.

<system.web>
    <!-- ... -->
    <customErrors mode="Off" />
    <!-- ... -->
</system.web>

This will give you the ability to obtain a detailed error description at a remote browser (usually it will be a message about a missing assembly).

Note

It is recommended that you undo changes in the Web.config file after fixing a problem for security purposes.

2.2 The error message states that an assembly could not be loaded

Problem Description:

The following error message is displayed in a browser window when you try to open an ASP.NET Web Forms application.

Deployment_Tutorial_1030

‘DevExpress.Web.ASPxTreeList.v9.2, Version=9.2.8.0, Culture=neutral, PublicKeyToken=b88d1754d700e49a’ could not be loaded.

Assembly name, version, etc., may be different.

Solution:

An assembly mentioned in the error message is missing from the application Bin subfolder. Copy it from the Developer Workstation. Usually, it is located in the %PROGRAMFILES(x86)%\DevExpress 21.2\Components\Bin\Framework folder.

2.3 The ‘500.22’ internal server error occurs

Problem Description:

The following error message is displayed in a browser window when you try to open an ASP.NET Web Forms application.

HTTP Error 500.22 - Internal Server Error. An ASP.NET Web Forms setting has been detected that does not apply in Integrated managed pipeline mode.

Solution:

Disable the integrated mode configuration validation in the system.webServer section of the Web.config file.

<system.webServer>
    <!-- ... -->
    <validation validateIntegratedModeConfiguration="false" />
    <!-- ... -->
</system.webServer>

2.4 Missing icons and images

Problem Description:

The ASP.NET Web Forms application loads and runs correctly, but most of the icons and images are missing.

Solution:

To find the cause of this issue, do the following.

Open the Web.config file located in the application folder. Ensure that the DevExpress.Utils.v21.2.dll, DevExpress.Web.ASPxThemes.v21.2.dll and DevExpress.Images.v21.2.dll assemblies are referenced in the assemblies section. Check that these assemblies are available in the Bin subfolder.
Navigate to your application virtual folder in the IIS Manager’s Connections section and double-click the Handler Mappings feature. Ensure that the ImageResourceHttpHandler handler is configured and enabled.
Right-click the application virtual folder in the IIS Manager’s Connections section. Choose Manage Application | Advanced Settings…. Note the Application Pool name selected in the Advanced Settings window. Navigate to the Application Pools node in the IIS Manager Connections section. Double-click the application pool name used in your application settings. Ensure that the Managed Pipeline Mode of the application pool is set to Integrated.
Note
If your application is deployed to remote web hosting, you may have no access to the IIS Manager. In this instance, use the hosting web-based control panel to check the application pool settings or contact hosting support.
If your application is built for .NET Framework 4.0, refer to the 2.7 item additionally.

2.5 The application does not open after changing the session state mode to StateServer or SQLServer

Problem Description:

After changing the session state mode to a mode different from InProc, various error messages are displayed in a browser window when trying to open an ASP.NET Web Forms application.

Solution:

The XafApplication class, as well as other XAF entities stored in the session, are not serializable. An XAF application cannot use the StateServer, SQLServer and Custom session state modes; use the InProc session state mode instead.

2.6 Issues when running ASP.NET Web Forms application

Problem Description:

The ASP.NET Web Forms application loads, but there are issues with running it.

Solution:

Ensure that your browser is supported by XAF. Refer to the eXpressApp Framework - Specifications page to see the list of currently supported browsers. Note that pop-up windows must be enabled in browser preferences.

2.7 Issues with an ASP.NET Web Forms application built for .NET Framework 4.0

Problem Description:

The ASP.NET Web Forms application loads, but there are issues with running it, e.g. missing images, empty popup windows, etc.

Solution:

Open the Web.config file and navigate to the system.webServer | handlers section. Check if the runtime version is specified in preCondition attributes of HTTP handlers, i.e.:

<system.webServer>
 <handlers>
  <!-- ... -->
  <add name="WebWindowTemplateHttpHandler" verb="*" path="*.aspx"
       type="DevExpress.ExpressApp.Web.WebWindowTemplateHttpHandler, 
       DevExpress.ExpressApp.Web.v, Version=.0, culture=neutral, 
       PublicKeyToken=b88d1754d700e49a"
       preCondition="integratedMode,runtimeVersionv2.0" />
  <!-- ... -->
 </handlers>
<!-- ... -->
<system.webServer>

If there are HTTP handlers with preconditions, as illustrated in the snippet above, remove the “runtimeVersionv2.0” part of the preCondition attribute value in all of these handlers.

2.8 Unexpected redirects to the logon page occur when running the ASP.NET Web Forms application

Problem Description:

The browser is redirected to the Login.aspx page when a user interacts with the ASP.NET Web Forms application.

Solution:

Open the Web.config file and verify the form’s authentication and session timeouts.

<authentication mode="Forms">
    <forms name="Login" loginUrl="Login.aspx" path="/" timeout="10" /> 
</authentication>
<!-- ... -->
<sessionState timeout="10" />

Increase these timeouts as you require. Session timeout governs the lifetime of an application. The authentication timeout specifies how frequently the logon window is displayed. If the session timeout is less than the authentication timeout, then the logon window is displayed only once - when the application starts. Then, after the session timeout, the application will be unloaded. If you log in to the application again, but before the authentication timeout, the logon window will not be displayed. If the authentication timeout is less than the session timeout, then the authentication timeout setting is ignored and the session timeout is used instead.

3. Platform-Independent Problems

3.1 Numerous assemblies are missing

Problem Description:

After deploying an application via Xcopy, you find numerous assemblies missing from the Windows Forms application folder or ASP.NET Web Forms application Bin subfolder.

Solution:

Open the application solution at the Developer Workstation and check that you have correctly followed all the pre-deployment steps from the Xcopy Deployment of a Windows Forms Application or Xcopy Deployment of an ASP.NET Web Forms Application lesson.

Note

Use the Assembly Deployment Tool to analyze your project and obtain the list of assemblies you should deploy. Compare the assemblies the tool identifies to the redistributable assemblies list available in the End User License Agreement (EULA).

3.2 “The application cannot connect to the specified database” error is displayed

Problem Description:

The following error message is displayed when you run the application.

Deployment_Tutorial_1080 Deployment_Tutorial_0065

The application cannot connect to the specified database, because the latter does not exist or its version is older than that of the application. The automatic update is disabled, because the application was started without debugging. You should start the application under Visual Studio, or modify the source code of the ‘DatabaseVersionMismatch’ event handler to enable an automatic database update, or manually create a database using the ‘DBUpdater’ tool.

Solution:

To find out what is wrong with the application database, use the DBUpdater tool. If the DBUpdater reports an error, check if it is described later in this topic.

See also: Set Up the Database Connection

3.3 The ‘1111’ error occurs when running the application or DBUpdater

Problem Description:

The following error message is displayed when running the application or DBUpdater tool.

DTG_04

An error with number 1111 has occurred. Error message: The database version is greater than the application version. The application needs to be updated. Please contact your system administrator or download a new version. Additional information: the local version 1.0.3603.18312 of module ‘MySolutionModule’ is smaller than version 1.0.3603.21783 in the database.

Solution:

One possible reason for a version mismatch is that you restored the database from the Developer Workstation backup and did not update the application. Another possible reason is that you updated the database from another End-User Workstation running a more recent application version. In both cases, you need to update your application.

See also: Application Update

3.4 The application cannot connect the database, although the DBUpdater reports no error

Problem Description:

The following error message is displayed when you run the application.

DTG_05

An error has occurred connecting to database. Please contact your system administrator.

At the same time, the DBUpdater tool reports no error.

Solution:

A possible reason is that the application does not have sufficient permissions to access the application database. Check that the account used to connect to the Database Server is provided with proper permissions or ask the database administrator to do it. Another solution is to switch to an account having proper permissions.

See also: Set Up the Database Connection

3.5 The DBUpdater reports that the database does not exist

Problem Description:

The DBUpdater reports:

Deployment_Tutorial_0070

The database does not exist. It will be created now.

…

Database update completed successfully.

Solution:

This behavior is normal when it is required to create an initial database. The database mentioned in the connection string was absent and the DBUpdater created it. Restore the database from a backup if you need specific data absent in the created database or check the connection string - you may be connecting to the wrong database.

See also:Set Up the Database Connection

3.6 The DBUpdater reports the ‘1110’ error

Problem Description:

The following error message is displayed when running the DBUpdater tool.

Deployment_Tutorial_0071

An error with number 1110 has occurred. Error message: The database is an older version than the application. The database needs to be updated.

Solution:

The database is empty. Press ENTER and the DBUpdater will populate it with initial data.
The application was updated, so the database must be updated as well. Press ENTER and the DBUpdater will fix this issue.

See also: Application Update

3.7 The DBUpdater cannot update the database as it cannot connect to the database server

Problem Description:

The following error message is displayed when running the DBUpdater tool.

DTG_06

The database cannot be updated: An error has occurred while establishing a connection to the server.

Solution:

The possible reasons are:

network failure;
incorrect connection string;
Database Server is not running;
Database Server does not allow remote connections.

Ask the Database Server administrator for assistance if required.

See also: Set Up the Database Connection

3.8 The DBUpdater cannot update the database due to invalid credentials

Problem Description:

The following error message is displayed when running the DBUpdater tool.

DTG_07

The database cannot be updated: Login failed for the user ‘username’.

Solution:

The possible reasons are:

incorrect connection string (a mistyped user ID);
Database Server does not allow ‘username’ user to connect to a specified database.

Check that the account used to connect to the database has the proper permissions. Ask the Database Server administrator for assistance, if required.

See also: Set Up the Database Connection

3.9 Performance issues when working with a large amount of data

Problem Description:

List Views with thousands of records load too slowly.

Solution:

Set the IModelOptions.DataAccessMode option to Server, ServerView, InstantFeedback, or InstantFeedbackView. When the Server, ServerView, InstantFeedback, or InstantFeedbackView mode is enabled in an XAF application, only visible records will be retrieved from the server (about 50 records instead of thousands).
By default, XPO uses GCRecord in queries, and XAF sorts records by the IModelClass.DefaultProperty property. Create indexes for these columns. Then, run your application and trace the sent queries with the help of the XPO Profiler to check the where and order clauses, and add other necessary indexes as well.

3.10 The “An attempt was made to load a program with an incorrect format” error occurs when starting the DBUpdater or standalone Model Editor tool on an x64 system

Problem Description:

The DBUpdater or Model Editor tool states that it cannot load your application’s assembly or executable, e.g.:

Developer Express Inc (R) ExpressApp Framework Database Updater.

Version: 21.2.15.0

Silent mode OFF

The database can't be updated:

Could not load file or assembly 'c:\Program Files\MySolution\MySolution.Win.exe' or one of its dependencies.

An attempt was made to load a program with an incorrect format.

Solution:

To fix this issue, do one of the following:

Reconfigure the DBUpdater and Model Editor executable headers using CorFlags.exe (CorFlags Conversion Tool).

CorFlags.exe "%PROGRAMFILES(x86)%\DevExpress 21.2\Components\Tools\eXpressAppFramework\DBUpdater\DBUpdater.v21.2.exe" /32Bit+ /Force

CorFlags.exe "%PROGRAMFILES(x86)%\DevExpress 21.2\Components\Tools\eXpressAppFramework\Model Editor\DevExpress.ExpressApp.ModelEditor.v21.2.exe" /32Bit+ /Force
Change you application’s configuration to ‘Any CPU’, recompile and redeploy it.
Recompile the DBUpdater and Model Editor utility against x64 (sources are located in the %PROGRAMFILES(x86)%\DevExpress 21.2\Components\Sources\DevExpress.ExpressApp.Tools\ folder, by default).

See the BadImageFormatException Class article in MSDN for the full list of scenarios or situations where this error can occur.

If this document does not contain sufficient information on how to resolve your issue, feel free to contact Developer Express support engineers via the Support Center.