Windows Forms Application Creation and Initialization
This topic details the steps performed after an end-user has run an XAF Windows Forms application, until the moment the main XAF objects, like the WinApplication, are created and initialized.
In the following image, you can see that the entire process of application creation and initialization can be divided into four steps.
The table below describes all these steps in detail.
| Stage | Description | Ways to Interfere |
|---|---|---|
| Create an Application | An instance of the WinApplication is created. This is performed by the Program.Main method, automatically generated in your Windows Forms application project. | |
| Initial Application Initialization | A newly created application is initialized. The settings that are specified in the configuration file's appSettings section are read to the application: | |
|
The XafApplication.TablePrefixes property is set to the value assigned to the TablePrefixes key in the configuration file. |
If it is not necessary for you to set table prefixes in the configuration file, you can do it in code. To do this, set the TablePrefixes property after an application object has been created, but before its XafApplication.Setup method is called. | |
|
The location to be used to store the Model.User.xafml file is specified by the UserModelDiffsLocation key. |
||
|
The location to be used to store the application's Log file is specified by the TraceLogLocation key. |
||
| Application Initialization by the Designer | Then, the application is initialized by the values specified in the Application Designer. This is performed by the InitializeComponent method, automatically called in the constructor of your WinApplication class. | |
|
The XafApplication.Modules collection is populated by the modules added to the Modules section in the Designer. Each module is set up. This means that the current WinApplication instance is assigned to the ModuleBase.Applicationproperty. |
If you need to add a module that is not registered in the Toolbox, and so cannot be added via the Designer, use one of the following approaches: Specify the required module name(s) in the application project's configuration file. Pass this string as a parameter of the XafApplication.Setupmethod in the Program.Main method. Add this module to the module that is contained in your solution. To do this, use the ModuleBase.RequiredModuleTypes collection. To see code samples of both these approaches, refer to the Ways to Register a Module topic. You can perform custom actions with a module, in addition to setting the Application object. To do this, override the module's ModuleBase.Setup method. |
|
|
The XafApplication.Connection property is set to the object of the type specified in the Designer's Connection section. The connection string is specified in the Properties grid when the Connection section is selected. |
You can avoid the use of the Designer by applying one of the following techniques: Specify the connection string in the application project's configuration file. Assign this string to the XafApplication.ConnectionString property (see this property's description). Set the XafApplication.Connection and/or XafApplication.ConnectionString property before the XafApplication.Setup method is called. |
|
|
The XafApplication.Security property is set to the object of the type specified in the Designer's Security section. The authentication strategy to be used by the Security System is specified in the same section. The User type to be used by the Security System is specified in the Properties grid when the Security section is selected. |
The eXpressApp Framework supplies two security system types: SecuritySimple and SecurityComplex. You can set them using the Application Designer. If you need to use a custom security type that implements the ISecurity interface, create and assign it to the XafApplication.Security property in code, before the XafApplication.Setup method is called. If you need to use a custom authentication strategy or a custom User type, initialize them and the XafApplication.Security property, before the XafApplication.Setup method is invoked.
If you do not initialize a security system via the Application Designer or in code, a SecurityDummy will be used. This security type allows all operations with all types of objects. That's why the presence of the security system is invisible when you run an application. |
|
|
The XafApplication.ApplicationName property is set to the value that is specified in the Properties grid when the Application section is selected. |
You can assign a custom value to the XafApplication.ApplicationName property in code - before the XafApplication.Setup method is called. | |
| Application Initialization by the Setupmethod | The XafApplication.Setup method is called. This is performed by the Program.Mainmethod that is automatically generated in your Windows Forms application project. There are several overloads of the Setup method. By default, the method without parameters is called. It leaves the properties that are already initialized as they are, and proceeds with the initialization process using default values: |
You can call the Setup method with the required parameters, depending on what custom objects you need to create. However, we recommend that you use the approaches presented above, instead. |
|
A default splash screen form (DevExpress.ExpressApp.Win.Core.SplashScreen) is shown. |
You can set a custom splash screen using the WinApplication.SplashScreen property. The custom splash screen must implement the ISplashinterface. To see an example, refer to the How to: Use a Custom Splash Screen topic. | |
|
A default Object Space Provider (see XafApplication.ObjectSpaceProvider) is created using the connection string specified by the XafApplication.ConnectionStringproperty. |
To create a custom Object Space Provider subscribe to the XafApplication.CreateCustomObjectSpaceProvider event, before the Setup method is called. Alternatively, pass the required ObjectSpaceProvider object, using the Setup method as a parameter. You can override the XAFApplication.CreateDefaultObjectSpaceProvider method in your WinApplication class descendant. This method is called when no custom approaches to pass an Object Space Provider are used. This method creates an instance of the built-in ObjectSpaceProvider class. You can return an instance of another class that implements the IObjectSpaceProvider interface. |
|
|
A default Controllers Manager (ControllersManager) is created. This object contains a collection of all the Controllers that are declared in the registered modules. |
You can override the XAFApplication.CreateControllersManager method in your WinApplication class descendant. This method creates an instance of the built-in ControllersManager class. You can return an instance of another class. | |
|
A default Modules Manager (ApplicationModulesManager) is created. This object contains the Modules collection with the modules to be used by the application. This collection is populated by the modules from the XafApplication.Modulescollection. In addition, the SystemModule is added as a default module. |
You can override the XAFApplication.GetDefaultModuleTypes method in your WinApplication class descendant. This method creates an instance of the built-in ApplicationModulesManager class. You can return an instance of another class. In addition, you can override the GetDefaultModuleTypes method to return modules to be added to the application by default, in addition to the System module. |
|
|
A default Application Model Differences Store (FileModelStore) is created. |
If you need to store an Application Model's differences in a place that is different from an XafML file, you can create a custom Application Model Differences Store. To do this, subscribe to the XafApplication.CreateCustomModelDifferenceStore event before the Setup method is called, or override the WinApplication.CreateModelDifferenceStoreCore method in your WinApplication class descendant. | |
|
The Object Space Provider and Controllers Manager are assigned to the application's corresponding properties: XafApplication.ObjectSpaceProvider and ControllersManager. |
Subscribe to the XafApplication.SettingUp event, to customize the objects to be assigned to the application object. Use the event handler's parameters to access the required objects. | |
|
The modules from the Modules Manager's Modules collection are added to the XafApplication.Modules collection of the current application, since at this step the latter collection includes the modules that are only added via the Application Designer. |
||
|
The Application Model Manager (ApplicationModelsManager) which manages the creation and initialization of the Application Model is instantiated. |
||
|
The Application Model is created. Internally, the Application Model has a layered structure, so at first, the actual layers that comprise the Application Model internals are created: |
||
|
The zero layer of the Application Model is created. Initially, it is empty. It is filled with data on demand, during the application life cycle. |
To extend the Application Model, pass the required model interfaces via the application modules' ModuleBase.ExtendModelInterfacesmethods. Alternatively, you can implement the IModelExtender interface in Controllers. To modify existing node generators, implement a generator updater and register it via the ModuleBase.AddGeneratorUpdaters method of a module. For details, refer to the Extend and Customize the Application Model in Code topic. | |
|
A layer for each module used in the application is created. This layer is filled with data from the Model.DesignedDiffs.xafml file that contains Application Model differences created in a particular module. |
To modify this layer's data, modify the required module's XafML file. This can be done, for example, via the Model Editor. | |
|
A layer for the application project is created. This layer is filled with data from the Model.xafml file that contains Application Model differences created in the application project. |
To modify this layer's data, modify the application project's XafML file. This can be done, for example, via the Model Editor. | |
|
Second, all the created layers are wrapped with the master layer. |
The master layer does not contain any information itself. It serves as a proxy for all other layers. Usually, when you access the Application Model, you deal with the master layer. | |
|
The final state of the Application Model is assigned to the XafApplication.Modelproperty. |
Subscribe to the XafApplication.SetupComplete event to create extra objects (helpers, extractors, etc.), after the application has been completely initialized. |