.NET Assembly Targets (stable)

.NET Assembly target is a stable feature

.NET Assembly target is a stable feature, which means, this feature is available and is still eligible for technical support, but will no longer be enhanced.

PowerBuilder includes a target type for creating .NET assemblies from nonvisual custom class objects.

You can create .NET Assembly targets from scratch or by using PBLs from an existing target that contain at least one nonvisual custom class object.

Creating a target from scratch

When you use the .NET Assembly target wizard to create a target from scratch, the wizard also creates an Application object, a project object that allows you to deploy the assembly, and a nonvisual object (NVO). However, you must add and implement at least one public method in the wizard-created NVO before it can be used to create a .NET assembly.

This table describes the information you must provide for .NET Assembly targets that you create from scratch:

Wizard field

Description

Project name

Name of the project object the wizard creates.

Library

Name of the library file the wizard creates. By default, this includes the current Workspace path and takes the name you enter for the project object with a PBL extension.

Target

Name of the target the wizard creates. By default, this includes the current Workspace path and takes the name you enter for the project object with a PBT extension.

Library search path

Lets you add PBLs and PBDs to the search path for the new target.

PowerBuilder object name

Name of the nonvisual object the wizard creates. By default this takes the name that you entered for a project object with an "n_" prefix.

Description

Lets you add a description for the project object the wizard creates.

Namespace

Provides a globally unique name to assembly elements and attributes, distinguishing them from elements and attributes of the same name but in different assemblies.

Assembly file name

Name of the assembly created by the wizard. By default, the assembly file name takes the namespace name with a DLL suffix.

Resource file and directory list

List of resource files, or directories containing resource files, that you want to deploy with the project. You can use the Add Files, Add Directories, or Search PBR Files buttons to add files and directories to the list box. You can select a file or directory in the list and click the Delete button to remove that file or directory from the list.

When you select a directory, the resource files in all of its subdirectories are also selected by default. However, you can use the Resource Files tab in the Project painter to prevent deployment of subdirectory files. For more information, see Resource Files and Library Files tabs.

Win32 dynamic library file list

Specifies any Win32 DLLs you want to include with your project. Click the Add button to open a file selection dialog box and add a DLL to the list. Select a DLL in the list and click Delete to remove the DLL from the list.

Setup file name

Name of the setup file the wizard creates. You can copy this MSI file to client computers, then double-click the files to install the .NET assembly on those computers.


Creating a target from an existing target

If you select the option to use an existing target, the wizard creates only the .NET Assembly target and a .NET Assembly project. The target you select must include a PBL with at least one nonvisual object having at least one public method. The public method must be implemented by the nonvisual object or inherited from a parent. The AutoInstantiate property of the nonvisual object must be set to false.

Note

All objects from an existing target are visible in the System Tree for the .NET Assembly target created from the existing target, except for any project objects that are incompatible with the new target. Although visual objects, as well as the application object, are not used in a .NET Assembly target, you can view them in the System Tree under the new target's PBLs.

When you use the wizard to create a .NET Assembly target from an existing target, the wizard prompts you for the same information as when you create a target from scratch, except that it omits the PowerBuilder object name and library search path fields. These fields are unnecessary because the existing target must have a usable nonvisual object and the library search path for the target is already set. The wizard does, however, present fields that are not available when you create a target from scratch.

This table describes these additional fields:

Wizard field

Description

Choose a target

Select a target from the list of targets in the current workspace.

Specify a project name

Select a name for the project you want to create. You must create a project object to deploy nonvisual objects as .NET components.

Choose a project library

Specify a library from the list of target libraries where you want to store the new project object.

Choose NVO objects to be deployed

Expand the library node or nodes in the list box and select check boxes next to the nonvisual objects that you want to deploy.

Use .NET nullable types

Select this check box to map PowerBuilder standard datatypes to .NET nullable datatypes. Nullable datatypes are not Common Type System (CTS) compliant, but they can be used with .NET Generic classes if a component accepts or returns null arguments or if reference arguments are set to null.

Only include functions with supported datatypes

Select this check box if you do not want to list functions that are not supported in the .NET environment. The functions will be listed in the Select Objects dialog box that you can open for the project from the Project painter.


After you create a .NET Assembly target, you can create as many .NET Assembly projects as you need. You start the .NET Assembly project wizard from the Project tab of the New dialog box. The fields in the wizard include all the fields in the table for creating a project from scratch, except for the "PowerBuilder object name" and "Description" fields. They also include all fields in the table for creating a project from an existing target, except for the "Choose a target" field.

Whether you opt to build a new target from scratch or from an existing target, most of the project-related fields listed in these tables are available for modification in the Project painter.

  • Modifying a .NET Assembly Project

    You can modify a .NET Assembly project from the Project painter.

  • Supported Datatypes

    The PowerBuilder to .NET compiler converts PowerScript datatypes to .NET datatypes.

  • Deploying and Running a .NET Assembly Project

    After you create a .NET Assembly project, you can deploy it from the Project painter or from a context menu on the project object in the System Tree.

Modifying a .NET Assembly Project

You can modify a .NET Assembly project from the Project painter.

In addition to the values for fields that you entered in the target and project wizards, you can also modify version, debug, and run settings from the Project painter, and select and rename functions of the nonvisual objects that you deploy to a .NET assembly.

Each .NET Assembly project has seven tab pages: General, Objects, Resource Files, Library Files, Version, Post-build, and Run.

General tab

The General tab in the Project painter allows you to modify the namespace, assembly file name, and setup file name for a .NET Assembly project. It also has a check box you can select to use .NET nullable datatypes. These fields are described in .NET Assembly Targets.

The General tab also has fields that are not available in the target or project wizards. This table describes the additional fields:

Project painter field

Description

Debug or Release

Options that determine whether the project is deployed as a debug build (default selection) or a release build. You use debug builds for debugging purposes. Release builds have better performance, but when you debug a release build, the debugger does not stop at breakpoints.

Enable DEBUG symbol

Option to activate code inside conditional compilation blocks using the DEBUG symbol. This selection does not affect and is not affected by the project's debug build or release build setting. This option is selected by default.


Objects tab

The Objects tab in the Project painter lists all the nonvisual user objects available for deployment from the current .NET Assembly target. The Custom Class field lists all these objects even if you did not select them in the target or project wizard.

Objects that you selected in the wizard display with a user object icon in the Custom Class treeview. All methods for the objects selected in the wizard are also selected for deployment by default, but you can use the Objects tab to prevent deployment of some of these methods and to change the method names in the deployed component.

This table describes the fields available on the Objects tab:

Project painter field

Description

Custom class

Select an object in this treeview list to edit its list of functions for inclusion in or exclusion from the assembly component. You can edit the list for all the objects you want to include in the assembly, but you must do this one object at a time.

Object name, Class name, and Namespace

You can change the object name only by selecting a different object in the Custom Class treeview. By default, the class name is the same as the object name, but it is editable. In the Project painter, the namespace is editable only on the General tab.

Method names and Function prototypes

Select the check box for each function of the selected custom class object you want to deploy to a .NET assembly. Clear the check box for each function you do not want to deploy. You can modify the method names in the Method Names column, but you cannot use dashes ("-") in the modified names. The Function Prototype column is for descriptive purposes only.

Change method name and description

You enable these buttons by selecting a method in the list of method names. PowerBuilder allows overloaded functions, but each function you deploy in an assembly class must have a unique name. After you click the Change Method Name button, you can edit the selected method name in the Method Name column. The Change Method Description button lets you add or edit a method description.

Select All and Unselect All

Click the Select All button to select all the functions of the current custom class object for deployment. Click the Unselect All button to clear the check boxes of all functions of the current custom class object. Functions with unselected check boxes are not deployed to a .NET assembly.


Resource Files and Library Files tabs

The fields that you can edit on the Resource Files and Library Files tabs of the Project painter are the same as the fields available in the target and project wizards. These fields are described in the first table in .NET Assembly Targets.

The Resource Files page of the Project painter does have an additional field that is not included in the project or target wizard. The additional field is a Recursive check box next to each directory that you add to the Resource Files list. By default, this check box is selected for each directory when you add it to the list, but you can clear the check box to avoid deployment of unnecessary subdirectory files.

Version, Post-build, and Run tabs

The fields on the Version, Post-build, and Run tabs of the Project painter are not available in the .NET Assembly target or project wizards. This table describes these fields:

Project painter field

Description

Version tab: Product name, Company, Description, and Copyright

Use these fields to specify identification, description, and copyright information that you want to associate with the assembly you generate for the project.

Version tab: Product version, File version, and Assembly

Enter major, minor, build, and revision version numbers for the product, file, and assembly.

Post-build tab: Post-build command line list for build type

Select the build type (Debug or Release) and click Add to include command lines that run immediately after you deploy the project. For example, you can include a command line to process the generated component in a code obfuscator program, keeping the component safe from reverse engineering. The command lines run in the order listed, from top to bottom. You can save separate sequences of command lines for debug and release build types.

Run tab: Application

You use this text box to enter the name of an application with code that invokes the classes and methods of the generated assembly. If you do not enter an application name, you get an error message when you try to run or debug the deployed project from the PowerBuilder IDE.

Run tab: Argument

You use this text box to enter any parameters for an application that invokes the classes and methods of the deployed project.

Run tab: Start In

You use this text box to enter the starting directory for an application that invokes the classes and methods of the deployed project.


Sign tab

The fields that you can edit on the Sign tab of the Project painter are the same as the fields available for other .NET projects, although one of the fields that permits calls to strong-named assemblies from partially trusted code is available only for .NET Assembly and .NET Web Service projects. For descriptions of the fields on the Sign tab, see Strong-Named Assemblies.

Supported Datatypes

The PowerBuilder to .NET compiler converts PowerScript datatypes to .NET datatypes.

This table shows the datatype mapping between PowerScript and C#:

PowerScript datatype

C# datatype

boolean

bool

blob

byte [ ]

byte

byte

int, uint

short, ushort

long, ulong

int, uint

longlong

long

decimal

decimal

real

float

double

double

string

string

user-defined structure

struct

user-defined nonvisual object

class

Date

DateTime

Time

DateTime

DateTime

DateTime


Note

Arrays are also supported for all standard datatypes.

Deploying and Running a .NET Assembly Project

After you create a .NET Assembly project, you can deploy it from the Project painter or from a context menu on the project object in the System Tree.

When you deploy a .NET Assembly project, PowerBuilder creates an assembly DLL from the nonvisual user objects you selected in the wizard or project painter. If you also listed a setup file name, PowerBuilder creates an MSI file that includes the assembly DLL and any resource files you listed in the wizard or Project painter.

Note

You can use the Runtime Packager to copy required PowerBuilder runtime files to deployment computers. For information about the Runtime Packager, see Deploying Applications and Components in Application Techniques.

You can run or debug an assembly project from the PowerBuilder UI if you fill in the Application field (and optionally, the Argument and Start In fields) on the project Run tab in the Project painter.