How-To: Create Business Components with Motion in LASG

With the Entities and Data Access Component classes generated, it is now the time to look at the Motion: Business Component Template Generator that is available in Layered Architecture Solution Guidance 2013 to create business components. Creating business components is the third step in the LASG Code Generation process. Before beginning this guide, please make sure that you have completed the previous tutorial on Creating Data Access Components with Momentum in LASG. Please make sure that your solution is fully compilable without any errors before starting.

This walk-through also uses the LeaveSample database that is part of the Layered Architecture Sample for .NET but you may use your own database to follow through.

1. In Solution Explorer, expand the Tutorial solution, go to the Business folder, right-click on the Tutorial.Business project and click Add Business Components...
   
   
   
2. This launches the Motion: Business Component Template Generator that comprises of 3 sections.
   
   
   
3. At the  1. Define Business Component  section, enter Leave in the Create new component text box and leave the default Suffix as Component. Motion will create the class with the name LeaveComponent for us.
   
   Tip: After you have defined business components and successfully compile them in the project, they will appear in the Use existing component dropdown list the next time you launch Motion.
4. By default, Motion will attempt to load the data project assembly from the centralized bin folder located under the solution (i.e. Tutorial\bin). All projects unfolded by LASG (except the Host and Web projects) will target this folder. In this exercise, the Tutorial.Data.dll should be automatically loaded.
   
   
   
   
   
   Tip: All the data access components and their methods will be listed in the Data access component methods tree-view in the  2. Select Data Methods to Call in Business Method  section if the data assembly is loaded correctly. Take note that it is normal for the tree-view to be disabled.
   
   Note: If the data project assembly is not loaded, please exit Motion and return to Visual Studio to make sure that there are data access components in the Tutorial.Data project and the solution is compilable without errors. Also please ensure that all dependent assemblies are located in the centralized bin folder. You can also manually load the data project assembly by clicking the Load button and selecting the .dll file.
5. Create the Apply business method. Enter Apply in the Business method name text box. The Data access component methods tree-view should be enabled now.
   
   Tip: It is recommended that you use business-like terms (i.e. Apply, Submit, Cancel, Approve, List etc.) to name your business methods instead of technical terms such as Insert, Update, Delete and Select. For example, it makes more sense to name your business method as Register for adding a user instead of calling it InsertUser.
6. Expand the LeaveDAC and LeaveStatusLogDAC nodes in the tree-view. If you remembered, these are the two DACs which you have created in the previous tutorial. Check on the check boxes beside the Create method of the LeaveDAC and the Create method of the LeaveStatusLogDAC. 
7. Click the    button to add them to the Called methods grid.
   
   Tip: You can also drag-and-drop methods from the Data access component methods tree-view to the Called methods grid. You can't select or check a DAC. If you have made any mistakes and want to start over, click on the Reset button.
8. Check on the check box in the Return grid column for the Create method of the LeaveDAC component. This will return the updated entity after insertion.
   
   
   

   Tip: You can use the Top and Bottom arrow buttons to re-arrange your called methods.
9. Click on the Add to Code Generation button to queue the definition.
10. Create the Approve business method. Enter Approve in the Business method name text box.
11. Check on the UpdateById method of the LeaveDAC and the Create method of the LeaveStatusLogDAC.
12. Click the    button to add them to the Called methods grid.
13. Uncheck any check boxes in the Return grid column.
14. Click on the Add to Code Generation button to add the definition to the code generation queue.
    
    
    
15. Create the Cancel business method. Enter Cancel in the Business method name text box.
16. Repeat the same steps from step 11 to 14 for the Cancel method.
17. Create the business method to list leaves. Enter ListLeaves in the Business method name text box.
18. Drag the SelectPage method under the LeaveDAC node to the Called methods grid. Verify that the check box at the Return grid column is checked.
19. Click on the Add to Code Generation button to add the definition to the code generation queue.
20. Create the business method to retrieve a Leave. Enter GetLeave in the Business method name text box.
21. Drag the SelectById method under the LeaveDAC node to the Called methods grid. Verify that the check box at the Return grid column is checked.
22. Click on the Add to Code Generation button to add the definition to the code generation queue.
23. By now you should have 5 business methods in your LeaveComponent queue - Apply, Approve, Cancel, ListLeaves and GetLeave.
24. Next, we will make some modifications to the methods. At the  3. Generate Business Components  section, select the Apply method in the list below the LeaveComponent and locate the CallMethods property in the property grid. Click on the ellipses [...] button to invoke the MethodModel Collection Editor dialog.
    
    
    
    
    
25. At the MethodModel Collection Editor dialog, select the Create method that belongs to the LeaveStatusLogDAC. Locate the Parameters property in the property grid on the right and click on the ellipses [...] button to invoke the ParameterModel Collection Editor dialog.
    
    
    
    Tip: If you want to wrap your methods in a TransactionScope, you can set the TransactionBegin property to true for the first method in the scope and set the TransactionEnd property to true for the last method in the scope. Please take note that it is your responsibility to arrange the sequence of the method calls correctly. For this exercise, we will not define any transaction scope.
26. At the ParameterModel Collection Editor dialog, select the leaveStatusLog parameter and set its IsInternallyDeclared property to true. This will indicate that this parameter will be declared in code and not at the method signature.
    
    
    
27. Click OK to close the ParameterModel Collection Editor dialog.
28. Click OK to close the MethodModel Collection Editor dialog.
29. Repeat these steps (24 to 28) for the Approve and Cancel methods.
30. Like the other code generators, you can perform various action from the tool-bar at the  3. Generate Business Components  section. You can Preview the code that will be generated, set Options, reposition the methods, Reset the definitions so that they will be code-generated again or Delete the definitions.
    
    

    

    Warning! Deleted definitions will not be recoverable.
    
    Note: All definitions will be marked as code generated (indicated by the IsUpdated property) after code generation. They will continue to appear in the list but will not be code generated the next time. Clicking Reset will change one or more definitions' IsUpdated value to true and mark them for code generation again.
    
    You can also Delete a method, a BC definition or all BC definitions from the tool-bar. Clicking on the Options icon will open the Code Generation Options dialog that will allow you to set a few standard options. Leave the settings alone and click OK.
31. Finally, click the Generate button to generate the business component classes.
32. At the Code Generation Completed dialog, click OK.
33. The Tutorial.Business project should contain the generated LeaveComponent code file.
    
    
    
34. Extra Tip: If you are regenerating code and the code file already exist in the project, you will be prompted to either Append, Backup, Overwrite or Cancel the process.
    
    

    

    
    

    
    Append will append whatever new methods to the bottom of the class. Take note it is not an intelligent append and duplicate methods may be appended to your class. You also need to make sure that you do not have any comments or commented code at the end of your class files.
    
    Backup creates a copy of your code file with a .bak extension and requires you to manually include its contents into your project.
    
    Overwrite will replace your existing code with the newly generated one. Any previously defined methods that were not included in the latest code generation will be lost.
    
    Cancel will discard the generated code from memory and preserves the existing code file.
    
    You can choose to apply the same option for all the files by checking the Do the same for all occurrence check box.

Adding Business Logic

By now the template of your business component should have been generated and you can proceed to implement your own business logic. 

As an example, we can modify the Apply method to contain some logic:

public Leave Apply(Leave leave)

{

    Leave result = default(Leave);

    leave.DateSubmitted = DateTime.Now;

    leave.Status = 0; // Pending

    // Data access component declarations.

    LeaveDAC leaveDAC = new LeaveDAC();

    LeaveStatusLogDAC leaveStatusLogDAC = new LeaveStatusLogDAC();

    // Step 1 - Calling Create on LeaveDAC.

    result = leaveDAC.Create(leave);

    var leaveStatusLog = new LeaveStatusLog()

    {

        LeaveID = result.LeaveID,

        Status = result.Status,

        Date = DateTime.Now

    };

    // Step 2 - Calling Create on LeaveStatusLogDAC.

    leaveStatusLogDAC.Create(leaveStatusLog);

    return result;

}

For a more complete implementation of the business logic, you can refer to the ASPNET-WCF-DAAB sample from Layered Architecture Sample for .NET

Summary

We have basically gone through how to use the Motion: Business Component Template Generator to create business components for our layered application. Take note that the methods generated only contain the basic structure without any logic. You will still need to add-in your own business processing logic to them but take note that any changes made in your code will not be reflected in the definitions stored in Motion. Therefore, practice caution when you are regenerating code on existing code file.

Coming up next - How-To: Create Service Layer Components with Velocity in LASG.