%%ItemTitle%%

VLF .NET Snap-in Components - Developer's Guide
Installing Visual LANSA Framework .NET SDK
Send comments on this topic.

Glossary Item Box

To install Visual LANSA Framework .NET SDK run VLFSDKInstall.msi (click on the hyperlink to download the file).

The installer will install the assemblies required for the development of VLF components and integrate help contents into the Visual Studio help system. It will make four new VLF-specific items available in the Visual Studio “Add New Item” dialog box. They are:

  • Command Handler
  • Hidden Command Handler
  • Filter
  • Relationship Handler.

Click to Enlarge Click to Enlarge
Click to Shrink Click to Shrink

Prerequisites

Visual LANSA Framework .NET SDK requires Visual Studio 2005 or 2008.

If you do not have Visual Studio, you can still develop VLF .NET components provided you have .NET Framework 2.0 installed on your computer. In this case please do not start the installation and see Developing Without Visual Studio.

.NET components run on VLF.NET only (not on Visual LANSA Framework for Windows or Web).

Edition Date September 15, 2014, EPC132100

© LANSA


Developing Without Visual Studio

Glossary Item Box

If you want to develop VLF .NET components without Visual Studio, you need to have .NET Framework 2.0 (or higher) installed on your computer.

In order to develop VLF components you need:

1. VLF.dll (click on the link to download the file) - you need to reference this assembly when you build your project.

2. VLFSamples.zip (click on the link to download the file) which contains sample projects.


Getting Started

Glossary Item Box

Important Information and Warnings

Other Documents


Important Information and Warnings

Glossary Item Box

You should only reference VLF.dll assembly from your code. No other LANSA or VLF assemblies should be referenced directly from your code. You should not use any types in VLF.dll that are not mentioned in this documentation.

Failing to observe this rule may result in one or more of the following situations:

  • The introduction of incompatibilities with future versions of this Framework.
  • Voiding or limitation of any maintenance contract you may have in place for this Framework.
  • Being charged for problem resolutions that are traced back to any such modifications.


Other Documents

Glossary Item Box

This document describes how to create .NET components that can be snapped in the Visual LANSA Framework.

To learn how Framework applications work, refer to Visual LANSA Framework Guide.

For detailed instructions of how to deploy Framework applications refer to Deployment Check Lists for Visual LANSA Framework.


Data Access

Glossary Item Box

The decision of how VLF components access data on the server is left at the discretion of the programmers developing the components. We recommend that LANSA Open for .NET be used for data access, but this is not a requirement.


Create and snap in a .NET component

Glossary Item Box

Follow these steps to gain a basic understanding of how you write and snap in Framework command handlers and filters:

Create a Command Handler

Snap in the Command Handler

How to get VLF.NET to notify my component when the application is shutting down


Create a Command Handler

Glossary Item Box

This section shows how to create a VLFNET command handler.

The command handler will be snapped in for the Organization business object which is part of the HR Demo Application in the VLF demo framework:

Click to Enlarge Click to Enlarge
Click to Shrink Click to Shrink

1. Create a new C# or VB.NET class library project. Call it VLFHumanResources:

Click to Enlarge Click to Enlarge
Click to Shrink Click to Shrink

2. Open the Add New Item dialog box:

Click to Enlarge Click to Enlarge
Click to Shrink Click to Shrink

3. Choose VLF Command Handler, name it DepartmentDetails , and press the Add button.

Click to Enlarge Click to Enlarge
Click to Shrink Click to Shrink

A new VLF Command Handler is created and opened in the Designer:

Click to Enlarge Click to Enlarge
Click to Shrink Click to Shrink

4. Lay two labels (name them Label1 & Label2), two text boxes (name them TextBox1 & TextBox2) and a list box (name it ListBox1) on the command handler. Make Label1 Department Code: and Label2 Department Description:

Click to Enlarge Click to Enlarge
Click to Shrink Click to Shrink

5. View the events available to VLF .NET command handlers.

The avExecute event occurs after the component becomes visible. The avInitialize event occurs right after the component is instantiated and before it becomes visible.

Click to Enlarge Click to Enlarge
Click to Shrink Click to Shrink

Double click on the avExecute event to create a handler for that event.

Now you will need to write code to connect to the server, retrieve the details of the currently active department in the instance list from the server and populate the command handler with the details.

To access the details of the currently active entry in the instance list, you need to first get a reference to the list manager through the avListManager property of the command handler. Use avGetCurrentInstance method of the list manager to get the current entry.

You might have noticed by now the naming convention of the VLF specific properties and methods – they always start with the prefix ‘av’.

Use the method of your choice (LOpen.NET or ADO.NET) to fetch the required details off the server. Update the UI controls (textboxes, listboxes) with the details.

7. If you are using LOpen.NET (you need a valid license and LOpen.dll), copy this code to to your command handler, otherwise modify it as required.

The section How to get VLF.NET to notify my component when it’s shutting down will show you how to improve the code to gracefully close LOpen .NET sessions when the framework application shuts down.

You will need to modify the connection settings (in this sample they are for the listener on the iSeries).

Show Department Details Command Handler Source Code VB

Department Details Command Handler VB Copy Code
Imports LOpen
Imports System

Public Class DepartmentDetails
Private m_Session As Session
Private m_SessionManager As SessionManager

Private Sub EmployeeDetails_avExecute(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.avExecute
' Connect to a LANSA server using LOpen.NET
m_SessionManager = SessionManager.GetInstance("ENG")
m_Session = m_SessionManager.Session("Session1")
If Not m_Session.Connected Then
m_Session.ComputerName = "MyServer"
m_Session.Partition = "DEM"
m_Session.LanguageCode = "ENG"
m_Session.PortNumber = "4545"
m_Session.Connect(False, "MyUserName", "MyPassword")
End If
' Get the currently selected instance
Dim entry As VLF.ListEntry = Me.avListManager.avGetCurrentInstance()
If entry IsNot Nothing Then
Me.TextBox1.Text = entry.avVisualID2
Me.TextBox2.Text = entry.avVisualID1
' Use LOpen.NET to retrieve associated sections
Dim SectionTable As LOpen.Table = m_Session.Table("SECTAB")
Dim sectionField As LOpen.Field = SectionTable.StringField("SECTION")
Dim descField As LOpen.Field = SectionTable.StringField("SECDESC")
Dim deptField As LOpen.Field = SectionTable.StringField("DEPTMENT")
deptField.Value = entry.avVisualID2
Dim dt As DataTable = SectionTable.[Select](New LOpen.Field() {sectionField, descField}, New LOpen.Field() {deptField}, False, Nothing, False, False, _
False, False)
' Populate the section list box
Me.ListBox1.BeginUpdate()
Me.ListBox1.Items.Clear()
For Each row As DataRow In dt.Rows
Me.ListBox1.Items.Add(row("SECDESC"))
Next
Me.ListBox1.EndUpdate()
End If
End Sub

End Class

Show Department Details Command Handler Source Code C# (DepartmentDetails.cs)

Department Details Command Handler C# Copy Code
using System;
using System.Data;
using LOpen;

namespace VLFHumanResources
{
      public partial class DepartmentDetails : VLF.CommandHandler
      {

      public DepartmentDetails()
      {
InitializeComponent();
      }
     private void DepartmentDetails_avExecute(object sender, EventArgs e)
            {
                  // Connect to a LANSA server using LOpen.NET
                  Session session = SessionManager.GetInstance("ENG").Session("Session1");
                  if (!session.Connected)
                  {
                        session.ComputerName = "MyServer";
                        session.Partition = "DEM";
                        session.LanguageCode = "ENG";
                        session.PortNumber = 4545;
                        session.Connect(false, "MyUserName", "MyPassword");
                  }

                  // Get the currently selected instance
                  VLF.ListEntry entry = this.avListManager.avGetCurrentInstance();
                  if (entry != null)
                  {
                        this.TextBox1.Text = entry.avVisualID2;
                        this.TextBox2.Text = entry.avVisualID1;

                        // Retrieve associated sections
                        LOpen.Table sectionTable = session.Table("SECTAB");
                        LOpen.Field sectionField = sectionTable.StringField("SECTION");
                        LOpen.Field descField = sectionTable.StringField("SECDESC");
                        LOpen.Field deptField = sectionTable.StringField("DEPTMENT");

                        deptField.Value = entry.avVisualID2;
                        DataTable dt = sectionTable.Select(
new LOpen.Field[] { sectionField, descField },
new LOpen.Field[] { deptField }, false, null, false, false, false, false);

                        // Populate the section list box
                        this.ListBox1.BeginUpdate();
                        this.ListBox1.Items.Clear();
                        foreach (DataRow row in dt.Rows)
                        {
                              this.ListBox1.Items.Add(row["SECDESC"]);
                        }
                        this.ListBox1.EndUpdate();
                  }
            }
      }
}

If this code generates error messages, ensure that you have a reference to LOpen.dll.

7. Save and build your project. Your command handler is now ready to be snapped in the Framework.

8. Copy the compiled assembly (VLHumanresources.dll) to your LANSA partition Execute directory (for example C:\Program Files\LANSA\X_WIN95\X_LANSA\x_dem\execute).


Snap in the Command Handler

Glossary Item Box

In this step you will snap the command handler into the Framework and test it.

1. Start the Framework.

2. Open the Framework Properties to register the .NET assemblies you are using. Display the Framework Details tab. Notice the section .NET assemblies used by Snap-in .NET filters and command handlers.

You need to add the .NET assemblies containing your snap-in components, one assembly in each line. You also need to add all DLLs referenced in your assemblies such as LOpen.dll, but you should not include VLF.dll or any standard .NET assemblies.

You can use either absolute or relative paths. If you use a relative path, the assembly has to be in the LANSA partition execute folder.

Click to Enlarge Click to Enlarge
Click to Shrink Click to Shrink

Next you will snap the .NET command handler in as the Organization business object command handler:

3. Select the Organizations business object:

Click to Enlarge Click to Enlarge
Click to Shrink Click to Shrink

4. Open the business object properties. Go to the Commands Enabled tab. Select the Details command from the Enabled list. You need to specify your .NET command handler in the .NET Component section at the bottom of the dialog box:

Click to Enlarge Click to Enlarge
Click to Shrink Click to Shrink

5. Click on the small button next to the Class Name text box to display the available .NET components. The NET Components dialog is displayed:

6. Select VLFHumanResources.DepartmentDetails.

7. Click OK and close the business object properties.

8. Save the Framework and upload the files to your server.

9. Execute your VLF .NET application (for example http://hostname/My_Framework_ENG.application) and select Organizations and then a Department. Your command handler is snapped in and functional:

Click to Enlarge Click to Enlarge
Click to Shrink Click to Shrink


How to get VLF.NET to notify my component when the application is shutting down
Send comments on this topic.

Glossary Item Box

More than likely you will need to do some form of cleaning up when VLF.NET is shutting down, such as closing your database connections or LOpen .NET connections.

When the application is shutting down, the framework manager (VLF.FrameworkManager class) will fire the avApplicationExit event, so all you need to do is to provide your own handler for this event.

Below is a modified code fragment from the example in the previous section showing just how to do that.

Shutting Down VLF.NET Copy Code
private void DepartmentDetails_avExecute(object sender, EventArgs e)
{
…
Session session = SessionManager.GetInstance("ENG").Session("Session1");
if (!session.Connected)
{
session.ComputerName = "MyServer";
session.Partition = "DEM";
session.LanguageCode = "ENG";
session.PortNumber = 4545;
session.Connect(false, "MyUserName", "MyPassword");

this.avManager.avApplicationExit += new System.EventHandler(this.DepartmentDetails_avApplicationExit);
}
…
            }

private void DepartmentDetails_avApplicationExit(object sender, EventArgs e)
{
Session session = SessionManager.GetInstance("ENG").Session("Session1");
session.Disconnect();
}

Since it is more than likely that you will have to write more than one command handlers or filters, your code will be more maintainable if you create a separate session class that will centrally handles the opening and closing of connections to your server. All your command handlers and filters can then use this new session class without having to worry about opening and closing connections themselves.


Executable Sample Code

Glossary Item Box

Executable C# sample code is provided in VLFSamples.zip. Click on the link to download the file, then extract the contents of the zip file and locate VLFSamples.csproj to open the project in Visual Studio.


Code Samples, Tips, Techniques, and FAQs

Glossary Item Box

Code Samples, Tips, Techniques, and FAQs

Sample code for a filter which adds new entries to the instance list

Where should I put my code to populate the instance list when I have a hidden filter?

How to update an instance list entry?

Is it possible to delete a particular entry in the instance list?

Sample Code for Relationship Handler which Adds New Entries to the Instance List

How to get the current entry in the instance list?

How to navigate (switch) to a different business object?

How can I read the framework's custom properties?

How can I pass values between my .NET command handlers & server-side command handlers (WAMs/WEBEVENTs)?

Executable Sample Code

Sample Code for Relationship Handler which Adds New Entries to the Instance List


Sample code for a filter which adds new entries to the instance list
Send comments on this topic.

Glossary Item Box

This sample code uses L/Open for .NET to retrieve data for the instance list:

Filter Source C# Copy Code
// Change application status to busy
VLFApplication.SetBusy(this.avManager, true);

// Always call avBeginListUpdate before making changes to the instance list
this.avListManager.avBeginListUpdate();
try
{
   // Use LOpen.NET to retrieve the list of departments
   LOpen.Table deptTable = VLFApplication.GetSession(this.avManager).Table("DEPTAB");
   LOpen.StringField codeField = deptTable.StringField("DEPTMENT");
   LOpen.StringField descField = deptTable.StringField("DEPTDESC");
   DataTable dataTable = deptTable.Select(
                      new LOpen.Field[] { codeField, descField },
                      new LOpen.Field[] { },
                      false, null, false, false, false, false);

   // Always clear the instance list in a filter otherwise the entries will be duplicated
   this.avListManager.avClearList();

   // Populate with newly retrieved records
   int i = 0;
   foreach (DataRow row in dataTable.Rows)
   {
       VLF.ListEntry entry = this.avListManager.avNewInstance();
       entry.avBusinessObjectType = "DEM_ORG";
       entry.avAColumnCount = 10;
       entry.avNColumnCount = 10;
       entry.avAKey1 = row["DEPTMENT"].ToString();
       entry.avVisualID1 = row["DEPTDESC"].ToString();
       entry.avVisualID2 = row["DEPTMENT"].ToString();
       i++;
       if (i >= maxCount) break;
   }
}
finally
{
   // Always call avEndListUpdate at the end of instance list update
   this.avListManager.avEndListUpdate();
   VLFApplication.SetBusy(this.avManager, false);
}


Where should I put my code to populate the instance list when I have a hidden filter?
Send comments on this topic.

Glossary Item Box

A hidden filter is a non-visual filter that retrieves data immediately when it is loaded. You should put the retrieval code in the avInitialize event.


How to update an instance list entry?
Send comments on this topic.

Glossary Item Box

Any update to the list should be done between avBeginUpdate and avEndUpdate commands. If an update is performed without first invoking avBeginUpdate, and exception will be thrown.

The code fragment below appends the word ‘Deleted’ to the the visual ID of the current entry in the list.

Update Instance List Entry C# Copy Code
this.avListManager.avBeginListUpdate();

VLF.ListEntry entry = this.avListManager.avGetCurrentInstance();
entry.avVisualID1 = entry.avVisualID1 + " " + "(Deleted)";

this.avListManager.avEndListUpdate();


Is it possible to delete a particular entry in the instance list?
Send comments on this topic.

Glossary Item Box

It is not possible to delete a particular entry from the instance list. The only way to remove entries from the list is by clearing the whole list using avClearList method.


Sample Code for Relationship Handler which Adds New Entries to the Instance List
Send comments on this topic.

Glossary Item Box

This relationship handler will retrieve sections associated with a department when the ‘Sections’ node (under department) is expanded in the HR Demonstration application:

Relationship Handler C# Copy Code
privatevoid OrgSecEmpRelationshipHandler_avExecute(object sender, RelationshipExecuteEventArgs args)
{
   stringparent = args.avParent.avBusinessObjectType;
   stringchild = args.avChildBusinessObjectType;

   if(parent == "DEM_ORG" && child == "DEM_ORG_SEC")
   {
       string dept = args.avParent.avAKey1;
       LOpen.Table sectionTable = VLFApplication.GetSession(this.avManager).Table("SECTAB");
       LOpen.Field departmentField = sectionTable.StringField("DEPTMENT");
       LOpen.Field sectionField = sectionTable.StringField("SECTION");
       LOpen.Field sectionDescField = sectionTable.StringField("SECDESC");

       departmentField.Value = dept;

       DataTable dt = sectionTable.Select(
               new LOpen.Field[] { sectionField, sectionDescField },
               new LOpen.Field[] { departmentField },
               false, null, false, false, false, false);

       foreach (DataRow dr in dt.Rows)
       {
          VLF.ListEntry entry = args.avListManager.avNewInstance();
          entry.avBusinessObjectType = "DEM_ORG_SEC";
          entry.avAKey1 = dept;
          entry.avAKey2 = dr["SECTION"].ToString();
          entry.avVisualID1 = dr["SECTION"].ToString();
          entry.avVisualID2 = dr["SECDESC"].ToString();
       }
   }
}


How to get the current entry in the instance list?
Send comments on this topic.

Glossary Item Box

Use the avGetCurrentInstance method of avListManager:

Get Current Entry C# Copy Code
VLF.ListEntry entry = this.avListManager.avGetCurrentInstance();


How to navigate (switch) to a different business object?
Send comments on this topic.

Glossary Item Box

Assuming the current framework is the demo framework, this statement will navigate the framework to the HR Applications - Organizations business object.

Switching to Another Business Object C# Copy Code
this.avManager.avSwitch(VLF.SwitchToType.avBusinessObject, "DEM_ORG", "");

If you need to populate the instance list of the target business object right after switching, you need to write a method to do that. Your method has to have one parameter of type VLF.ListManager . When calling avSwitch, use the overload that accepts your populate method. This tells VLF to call your populate method right after it switches to the target business object.

Populating Target Instance List C# Copy Code
private void btnShowDetails_Click(object sender, EventArgs e)
{
   this.avManager.avSwitch(VLF.SwitchToType.avBusinessObject, "DEM_ORG_SEC_EMP", "DETAILS", this.AddEmployeeInstances);
}

private void AddEmployeeInstances(VLF.ListManager listManager)
{
   listManager.avBeginListUpdate();
   listManager.avClearList();
   try
{
   ...
}
   finally
   {
       listManager.avEndListUpdate();
   }
}


How can I read the framework's custom properties?
Send comments on this topic.

Glossary Item Box

Use the avGetCustomProperty method of the framework manager.


How can I pass values between my .NET command handlers & server-side command handlers (WAMs/WEBEVENTs)?
Send comments on this topic.

Glossary Item Box

Use the framework’s virtual clipboard. When a .NET command handler put a value into the virtual clipboard, it will be accessible by any server-side command handlers.

To put & fetch values into/from the virtual clipboard, use the avSaveValue & avRestoreValue of the framework manager. On the server side, similar methods are used to access to clipboard (refer to the VLF Documentation).


Debugging

Glossary Item Box

To debug your .NET components Using Visual Studio, you need to first run VLF.NET on your computer by navigating your browser to the application URL.

After VLF.NET is running, switch to Visual Studio and attach your source code to your application process. If your framework is called HR_Framework and you are running the ENG language version of it, the process name would be HR_Framework_ENG.app.exe.
Click to Enlarge Click to Enlarge
Click to Shrink Click to Shrink

Now pay attention to the Attach to above the Available Processes. Because we are debugging managed .NET code it has to show Managed Code. If it does not show Managed Code you will have to force it by clicking on the Select button next to it, select the second radio button, and tick Managed Code.
Click to Enlarge Click to Enlarge
Click to Shrink Click to Shrink

Click to Enlarge Click to Enlarge
Click to Shrink Click to Shrink

Your assembly is now running attached to the VLF.NET process.

Now put a breakpoint inside one of the methods in one of your .NET components. Go back to VLF.NET, navigate to the business object associated with the .NET component. Visual Studio will enter debug mode when your breakpoint is hit.


Empty Index Entry

Glossary Item Box

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


Topic Not Found

Glossary Item Box

Topic Not Found

The link you just clicked was not able to connect to the target page.

Some possible reasons and remedies are as follows:

Reason | Remedy
Destination topic is not part of the area you specified in the Filtered by field. | Either select another filter or select (no filter).
The URL of the destination topic is incorrect or has changed. | Use the index or the search function instead.
Problems with the help installation. | Rerun Setup for the product this help is related to and select the 'Repair' option.

Additional help is available for filters, search, and the index.

Click Back to return to the page you were on.

The target parameters are:

Keyword:
Index Moniker:
URL:


a
about
after
against
all
along
also
although
am
among
an
and
are
as
at
be
became
because
been
being
between
but
by
can
caution
come
could
details
did
do
does
doing
done
during
each
early
far
finally
for
found
from
had
has
have
he
her
here
his
how
however
I
if
in
include
including
information
into
is
it
its
late
later
made
many
may
me
med
might
more
most
near
no
non
none
nor
not
note
of
off
on
only
or
other
over
saw
see
seen
several
she
since
so
some
such
than
that
the
their
them
then
there
these
they
this
those
through
tip
to
too
under
until
up
us
use
very
warning
was
we
were
when
where
which
while
who
with
you