.NET Web Service Targets

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

The .NET Web Service target wizard gives you the option of creating a target from scratch or from an existing PowerBuilder target.

Creating a target from scratch

The .NET Web Service target wizard shares the following fields in common with the .NET Assembly target: Project Name, Target, Library, Library Search Path, PowerBuilder Object Name, Description, Resource Files, and Win32 Dynamic DLLs. However, it has four additional fields (Web service virtual directory name, Web service URL preview, Generate setup file, and Directly deploy to IIS), and the Namespace and Assembly File Name fields are specific to the .NET Assembly wizard.

This table describes the fields in the .NET Web Service wizard when you create a target 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.

Web service virtual directory name

The directory path you want to use as the current directory in the virtual file system on the server. By default, this is the full path name for the current PowerBuilder target.

Web service URL preview

Address for accessing the .NET Web service from an application.

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.

Generate setup file

Select this option to deploy the Web service in an MSI file. When you select this option, you must provide a name for the setup file.

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 Web service on those computers.

Directly deploy to IIS

Select this option to deploy the Web service directly to an IIS server. When you select this option, you must provide an IIS server address. By default, the server address is "localhost".


When you click Finish in the wizard for a target you are creating from scratch, the wizard generates an Application object, a project object, a target, and a nonvisual object. You must add and implement a public method in the nonvisual object generated by the wizard before you can deploy it as a Web service.

Creating a target from an existing target

As with the other .NET target wizards, you can use the .NET Web Service target wizard to create a target from an existing PowerBuilder target. The existing target must be added to the current workspace and 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.

When you click Finish in the wizard for a target you are creating from an existing target, the wizard creates a .NET Web Service target and a .NET Web Service project. The .NET Web Service target uses the same library list as the existing target from which you select nonvisual user objects.

As with the .NET Assembly target wizard, the .NET Web Service target wizard has additional fields for selecting nonvisual user objects when you use the existing target option. 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. After you create the .NET project, the functions are listed on the Objects tab for the project when you open it in the Project painter.

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.


  • Modifying a .NET Web Service Project

    You can modify a .NET Web Service project from the Project painter.

  • Configuring ASP.NET for a .NET Web Service Project

    Configure .NET Web Service projects.

  • Global Web Configuration Properties

    A set of global properties is available for .NET Web Services.

  • Deploying and Running a .NET Web Service Project

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

  • .NET Web Service Deployment Considerations

    This topic discusses requirements, restrictions, and options for deploying .NET Web Service projects.

Modifying a .NET Web Service Project

You can modify a .NET Web Service project from the Project painter.

The Project painter shows all the values you selected in .NET Web Service target or project wizards. However, 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 Web Service component.

.NET Web Service project tab pages

Each .NET Web Service project has these tab pages:

  • General tab - includes debug fields that are not available in the target or project wizards.

    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.


  • Deploy tab - the fields on the Deploy tab are all available in the .NET Web Service project wizard. For descriptions of fields available on the Deploy tab, see the first table in .NET Assembly Targets.

  • Objects tab - allows you to select the methods to make available for each nonvisual object you deploy as a Web service. You can rename the methods as Web service messages. This table describes the Objects tab fields for a .NET Web Service project:

    Objects tab field

    Description

    Custom class

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

    Object name

    You can change the object name only by selecting a different object in the Custom Class treeview.

    Web service name

    Specifies the name for the Web service. By default, this takes the name of the current custom class user object.

    Target namespace

    Specifies the target namespace. The default namespace for an IIS Web service is: http://tempurl.org. Typically you change this to a company domain name.

    Web service URL

    Specifies the deployment location for the current custom class user object. This is a read-only field. The location combines selections on the General, Deploy, and Objects tabs for the current project.

    Web service WSDL

    Specifies the WSDL file created for the project. This is a read-only field. It appends the "?WSDL" suffix to the Web service URL.

    Browse Web Service

    If you have previously deployed the project to the named IIS server on the Deploy tab of the current project, you can click this button to display a test page for the existing Web service. If a Web service has not been deployed yet for the current custom class object, a browser error message displays. The button is disabled if you selected the option to deploy the current project to a setup file.

    View WSDL

    If you previously deployed the project to the named IIS server on the Deploy tab of the current project, you can click this button to display the existing WSDL file. If a Web service has not been deployed yet for the current custom class object, a browser error message displays. The button is disabled if you selected the option to deploy the current project to a setup file.

    Message names and Function prototypes

    Select the check box for each function of the selected custom class object that you want to deploy in a .NET Web service component. Clear the check box for each function you do not want to deploy. You can modify the message names in the Message Names column. The Function Prototype column is for descriptive purposes only.

    Change message name

    You enable this button by selecting a function in the list of message names. PowerBuilder allows overloaded functions, but each function you deploy in a component class must have a unique name. After you click the Change Message Name button, you can edit the selected function name in the Message Name column.

    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 as messages for a Web service component.


  • Resource Files tab - the fields on this tab are the same as those in the project wizard. However, as for the .NET Assembly project, there is one additional field that is not included in the project or target wizard. This field is a Recursive check box next to each directory 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.

  • Library Files tab - includes fields for the Win 32 dynamic libraries you want to deploy with your project. These fields are described in .NET Web Service Targets. The Library Files tab also includes a list of PBL files for the target. You can select a check box next to each PBL files containing DataWindow or Query objects to make sure they are compiled and deployed as PBD files.

  • Version tab - the fields on this tab cannot be set in the target or project wizards:

    Version tab field

    Description

    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.

    Product version, File version, and Assembly

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


  • Post-build tab - the items on this tab cannot be set in the target or project wizards. Select a build type 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.

  • Security tab - on this tab, configure CAS security zones for Web Service components, minimizing the amount of trust required before component code is run from a user application. A radio button group field on the Security tab allows you to select full trust (default) or a customized trust option. The list box below the radio button group is disabled when full trust is selected, but it allows you to select or display the permissions you want to include or exclude when the custom option is selected.

    For information on custom permission requirements, see Security Settings and Custom Permission Settings.

  • Run tab - the fields on this tab cannot be set in the target or project wizards:

    Run tab field

    Description

    Application

    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.

    Argument

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

    Start In

    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 settings on this tab are the same as those available for other .NET projects, although the field 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.

Configuring ASP.NET for a .NET Web Service Project

Configure .NET Web Service projects.

IIS and ASP.NET

ASP.NET configuration includes making sure the Web server has a compatible version of IIS and that the 4.x version of ASP.NET is selected for your Web service components.

For information on installing IIS and setting the default version of ASP.NET, see ASP.NET Configuration for a .NET Project.

SQL Anywhere database connections

Set up a database connection for your Web service components. See Setting Up a SQL Anywhere Database Connection.

Global properties

The following global properties can be used by Web service projects:

  • LogFolder

  • FileFolder

  • PrintFolder

  • PBWebFileProcessMode

  • PBCurrentDir

  • PBTempDir

  • PBLibDir

  • PBDenyDownloadFolders

  • PBTrace

  • PBTraceTarget

  • PBTraceFileName

  • PBMaxSession

  • PBEventLogID

  • PBDeleteTempFileInterval

See Global Web Configuration Properties.

Global Web Configuration Properties

A set of global properties is available for .NET Web Services.

Global properties are set in web.config, which is deployed to the ...\wwwroot\application_name folder by the .NET Web Service project. You cannot set global properties in script.

This table lists global properties that you can set for .NET Web Service targets:

Property

Default value

Description

LogFolder

WebAppDir..​\appName_root\log

Folder that contains the PBTrace.log file.

FileFolder

WebAppDir..​\appName_root\file

Base directory for the virtual file manager. It contains the File\Common directory structure and files that mirror paths for the application resource files on the development computer. If you switch to Copy mode, a sessionID directory is created under the File\Session directory that mirrors the File\Common directory structure and file contents.

PrintFolder

WebAppDir..​\appName_root\print

Base directory for files that your application prints in PDF format.

PBWebFileProcessMode

Share

Share mode maintains files in a read-only state when a write file operation is not explicitly coded. If an application requires multiple file operations, you might want to change this property setting to Copy mode.

PBCurrentDir

c:\

Specifies the current directory for the Web Service.

PBTempDir

c:\temp

A temporary directory under the virtual file root on the server.

PBLibDir

c:\~pl_

The directory on the server where dynamic libraries are generated.

PBDenyDownloadFolders

c:\~pl_

A semicolon-delimited string of directory names.

PBTrace

Enabled

Indicates whether to log exceptions thrown by the application. Values are Enabled or Disabled.

PBTraceTarget

File

Defines where to log exceptions thrown by the application. Values are File or EventLog.

PBTraceFileName

PBTrace.log

Name of the file that logs exceptions thrown by the application. By default, this file is saved to the applicationName_root\Log directory under the virtual root directory on the server.

PBEventLogID

1100

The event ID if exceptions are logged to the EventLog.

PBDeleteTempFileInterval

600 (minutes)

Sets the number of minutes before temporary files created by composite DataWindows are deleted. A value of 0 prevents the temporary files from being deleted.


Deploying and Running a .NET Web Service Project

After you create a .NET Web Service 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 directly to an IIS server, PowerBuilder creates an application directory under the IIS virtual root and creates an ASMX file in the application directory. The ASMX file created by the project is an ASP.NET executable file rather than a true WSDL file, so you might need to add the WSDL suffix to the URL when you try to access this Web service from certain types of applications.

In addition to the application directory and the ASMX file, deploying the project creates an additional assembly containing the Web service wrapper class. The file name for this assembly is generated by appending the characters "ws" to the file name of the main application assembly. It is generated with the main assembly in the application's bin directory.

Note

In some versions of IIS, ASPNET Web services use the Temp system directory during method processing. If the IIS_IUSRS user group (IIS 7.5 or later) does not have read or write access to the Temp directory on the server, applications invoking methods on those services receive an error message stating that temporary classes cannot be generated. You can prevent this error by granting appropriate user or user group permissions to the Temp directory in the same way you grant permissions for the Appeon and database directories. See Setting Up a SQL Anywhere Database Connection.

When you deploy to a setup file in a .NET Web Service project, the project builds an MSI file that includes the ASMX file, PowerBuilder system libraries for .NET, and any resource files you listed in the project wizard or painter.

Note

You can use the Runtime Packager to copy required PowerBuilder runtime files to deployment servers. After you install the package created by the runtime packager, you must restart the server. For information about the Runtime Packager, see Deploying Applications and Components in Application Techniques.

You can run or debug a .NET Web Service 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. The Application field is typically filled in automatically with the name of the Internet Explorer executable on the development computer.

.NET Web Service Deployment Considerations

This topic discusses requirements, restrictions, and options for deploying .NET Web Service projects.

When a .NET Web Service project is open in the Project painter and no other painters are open, you can select Design > Deploy Project from the Project painter to deploy the project.

When all painters are closed, including the Project painter, you can right-click a Web Service project in the System Tree and select Deploy from its context menu.

The Output window shows the progress of the deployment and provides a list of application functions, events, and properties that are not supported in the Web Service version of the application. Most of these warnings are benign and do not prevent users from running the application as a Web Service.

If a supported version of the Microsoft .NET Framework is the only version of the .NET Framework installed on the server, or if you configured the server to use a supported version (4.x) for all Web sites by default, you can run the application immediately after you deploy it.

You can run the application from PowerBuilder by selecting Design > Run Project from the Project painter menu or selecting the Run Project toolbar icon from the Project painter toolbar. The System Tree context menu for the Web Service project also has a Run Project menu item.

Deployment to a setup file

If you are deploying a .NET project to an MSI file, you must have a file named License.rtf in the PowerBuilder DotNET\bin directory. The PowerBuilder setup program installs a dummy License.rtf file in this directory, but you should modify this file's contents or replace the file with another file of the same name.

The License.rtf file should contain any license information you want to distribute with your application. You can run the .NET Assembly or Web Service only after the setup file is extracted to an IIS server. The contents of the License.rtf file appear in the setup file extraction wizard.

After you create and distribute the MSI file to an IIS server, you must extract the MSI file on the server. By default the extraction directory is set to C:\Program Files\webservice\applicationName, and the extraction wizard creates the C:\Program Files\webservice\applicationName\applicationName and C:\Program Files\webservice\applicationName\applicationName_root virtual directories, where applicationName is the name of your application.

Although you do not need to modify the default extraction directory to run the application, the extraction wizard does let you change the location of the application directories you extract. If you prefer to keep all your applications directly under the server's virtual root, you could set the extraction directory to server's Inetpub\wwwroot directory.

Deployment to a production server

You can deploy a .NET Assembly or Web Service to a production server either by:

  • Extracting an MSI file that you build from a Web Service project

  • Deploying directly from the development computer to a mapped server

  • Copying all application folders and files from IIS on a local server to IIS on a production server

Production servers must meet the requirements described in ASP.NET Configuration for a .NET Project. You must install all database clients and have access to all data sources on the production computer. For applications that you deploy to a production server, you should add required database driver DLLs to the Win32 dynamic library list on the Library Files tab page of your Web Service projects. If you are using ODBC to connect to a database, you should add the PBODB170.INI file to the list of resource files on the Resource Files tab page of Web Service projects.

The production server must have the following DLLs in its system path: atl80.dll (for 32-bit only), msvcr80.dll (for 32-bit only), msvcp80.dll (for 32-bit only), atl100.dll, msvcp100.dll, msvcr100.dll, pbshr170.dll, and if your application uses DataWindow objects, pbdwm170.dll. You can also use the Runtime Packager to deploy required PowerBuilder runtime files to the ASP.NET server. After you install the package created by the Runtime Packager, you must restart the server.

For a complete list of required runtime files and for information on the Runtime Packager, see Deploying Applications and Components in Application Techniques.

Deployment to a remote server

You can deploy directly to a mapped server only if the server is in the same domain or workgroup as the development computer. In addition, you must add the development computer user's Windows login ID as a member of the Administrators group on the remote computer hosting the IIS server.

If you copy a Web Service from a development computer to a production server, you must copy both the applicationName and applicationName_root folders (and their contents) that were created when you deployed the application locally. Direct deployment to a mapped server automatically adds the necessary ASP.NET user permissions to access these directories, but if you copy files to the server, you must add these permissions manually.

ASP .NET user permissions

If you copy files to a production server, or extract your Web Service from an MSI file, you can use Windows Explorer to grant ASP.NET permissions to the application directories. This method is described in Setting Up a SQL Anywhere Database Connection. You can also grant ASP.NET permissions from a command line. The commands are different depending on the version of IIS that your server is running:

IIS version

Commands for granting appropriate user permissions

7.5 and later

cacls applicationName\temp /t /e /c /g IIS_IUSRS:f
cacls applicationName_root /t /e /c /g IIS_IUSRS:f


Event logging on the production server

If you log Web Service events to a production server's event log (by setting the PBTraceTarget global property to "EventLog"), you must have a registry entry key for PBExceptionTrace. If you use an MSI file to deploy an application to a production server, the PBExceptionTrace key is created automatically. If you deploy directly to a mapped production server or if you copy a Web Service to a production server, you must import the PBExceptionTrace key or create it manually.

When you deploy to a local computer, PowerBuilder creates the following key: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Eventlog\Application\PBExceptionTrace. You can export this key to a .REG file and import it to the production server's registry.

For information on the PBTraceTarget global property, see Global Web Configuration Properties.

If your Web Service uses any ActiveX DLLs, such as HTML2RTF.DLL or RTF2HTML.DLL, you must also register these files on the production server.