Configuring ASP.NET for a .NET project

You can configure ASP.NET for a
Web Forms or smart client project before or after you deploy the
project to an IIS 5.0 or later server. All files and directories that
you access from a Web Forms application or a smart client application
on a Web server must have appropriate ASPNET (IIS 5.0), IIS_WPG
(IIS 6.0), or IIS_IUSRS (IIS 7.0) user permissions.

For an example of granting user permissions to a directory,
see “Granting ASP.NET user
permissions”.

Installing IIS

You can install IIS
from the Control Panel, but you might need a Windows operating system
CD. Select Add and Remove Programs from the Control Panel, then
click Add/Remove Windows Components, select the Internet Information
Services check box, and click Next. You can then follow instructions
to install IIS. On Vista, go to the Programs and Features page in the
Control Panel, select Turn Windows features on or off, and select
Internet Information Services.

If IIS 5.0 or later is installed after the .NET Framework
2.0, you must register IIS with ASP.NET manually or reinstall the
.NET Framework 2.0. To manually register IIS with ASP.NET 2.0, go
to the .NET Framework 2.0 path, run aspnet_regiis.exe
-i in the command line console, and restart IIS.

If
you use IIS 7.0 for your Web applications and components, make sure
you install the IIS 6 Compatibility Component and IIS 6 script tool.

Selecting the default ASP.NET version

If you installed multiple
versions of the .NET Framework on the target Web server, you should
make sure that IIS uses the 2.0 version for PowerBuilder .NET applications.
You can make this change globally, for all ASP.NET Web site applications,
or for individual applications that you deploy to IIS.

The following procedure applies to IIS 5 and 6. In IIS 7,
you set the .NET Framework version for the application pool your
applications use. For more information, see “Additional configuration
requirements for Windows Vista”.

To configure the ASP.NET
version for all new Web sites:

1. Select Start>Run from the Windows
   Start menu.

2. Type “InetMgr” in the Run dialog
   box drop-down list.

   The IIS Manager displays.

3. In the left pane of the IIS Manager, expand the
   local computer node and its Web Sites sub-node.

4. Right-click the Default Web Site node and select
   Properties from its pop-up menu.

   The Default Web Site Properties dialog box displays.

5. Click the ASP.NET tab of the Default Web Site
   Properties dialog box and select 2.0.50727 or later for the ASP.NET
   version.

Figure 1-2: Setting the default ASP.NET version

Changing the ASP.NET version for an existing Web Forms
project If you have already deployed a PowerBuilder .NET project,
you can follow the procedure to configure the ASP.NET version for
all new Web sites, but instead of right-clicking on the Default
Web Site node in step 4, expand the node and right-click on the
.NET application that you deployed from PowerBuilder. Then proceed
with step 5.

Viewing and modifying global properties in IIS Manager

Although
you set global properties for a Web Forms application on the Configuration
page of the Project painter before you deploy the project, you can
also view and modify the global properties in the IIS Manager after the project
is deployed.

For information about global properties generated with a PowerBuilder
.NET Web Forms project, see “Global Web configuration
properties “.

To view and edit global properties in IIS Manager:

1. Expand the nodes in the left pane of the
   IIS Manager until you see the node for the Web Forms application
   whose properties you want to examine.

2. Right-click on the Web Forms application and select
   Properties from the pop-up menu.

3. Click the ASP.NET tab and change the ASP.NET version
   to 2.0.50727 if necessary.

4. Click Edit Configuration.

   The ASP.NET Configuration dialog box displays for the current
   .NET Web Forms application. You can view its global properties in
   the list box at the bottom of the General tab.

   Modifying a global property for the application You modify a global property by selecting that property in
   the Application Settings list box and clicking Edit. You can then
   type in a new value for that property and click OK. The next time
   you run the Web Forms application, the new global property value
   is used.

Directory structure on the server

When you deploy a PowerBuilder
.NET Web Forms application, PowerBuilder creates two top-level directories
for the application under the IIS root. One of the directories takes
the name of the application specified in the Web Forms project,
and the other appends “_root” to the
application name.

The applicationName directory contains
the generated cs and aspx files,
as well as subdirectories for any resource files, PowerBuilder libraries,
and external modules that you deploy with your application.

The applicationName_root directory
contains directories named File, Mail, Log, and Print. The File
directory contains the Common, Session, User, and Icon subdirectories.
The FileCommon directory holds read-only files specified
in the Web Forms project. The paths to the read-only files mirror
the paths on the development computer, with the drive letter serving
as the name for the top subdirectory under FileCommon
directory.

The subdirectories under the FileCommon directory
include the initial current directory that you assigned in the .NET
Web Forms Application wizard or in the Project painter. If an application
user performs write operations on a file in a FileCommon
subdirectory, a SessionID folder is created
under the FileSession directory (or, if the application
user has a permanent user account, a UserName folder
is created under the FileUser directory), and the read-only file
is copied there in a mirrored path before a user can save the modified
file.

The FileUser directory contains files saved by logged-in
users whose profiles are included in a permanent user database.
For information about creating user profiles, see “Creating permanent user
accounts”.

The FileIcon directory is used by the PowerBuilder
.NET Web Forms runtime engine to convert .ICO files
to .GIFs and .BMPs. Its
contents are not visible to Web Forms application users.

Setting up a SQL Anywhere database connection

Before
a PowerBuilder .NET Web Forms application connects to a SQL Anywhere® database,
you must either start the database manually or grant the ASPNET
user (IIS 5 on Windows XP), the IIS_WPG user group (IIS
6 on Windows 2003), or IIS_IUSRS (IIS 7 on Windows Vista)
default permissions for the SybaseShared and Sybase SQL
Anywhere directories, making sure to replace permissions of all
child objects in those directories.

Full control permissions are required for directories containing
databases that you need to access from your Web Forms applications.

Starting the database manually If your database configuration uses a server name, you must
provide the database server name in the start-up options
when you start the database manually, in addition to the name of
the database file you are accessing.

Granting ASP.NET user
permissions

If you do not grant
the appropriate user permissions for Sybase directories and your
database configuration is set to start the database automatically,
your application will fail to connect to the database. SQL Anywhere
cannot access files unless the ASPNET, IIS_WPG, or IIS_IUSRS
user group has the right to access them.

To grant an ASP.NET user
permissions for Sybase directories:

1. In Windows Explorer, right-click the Sybase,
   SybaseShared or Sybase SQL Anywhere directory and select
   Properties from the pop-up menu.

   The Properties dialog box displays for the selected directory.

2. Select the Security tab of the Properties dialog
   box for the directory and click the Add button. On Vista, click
   Edit and then Add.

   The Select Users, Computers, or Groups dialog box displays.

   If the Security tab does not display To display the Security tab, you might need to modify a setting
   on the View tab of the Folder Options dialog box for your current
   directory. You open the Folder Options dialog box by selecting the
   Tools>Folder Options menu item from Windows Explorer. To
   display the Security tab, you must clear the check box labeled “Use
   simple file sharing (Recommended)”.

3. Click Locations and choose the server computer
   name from the Locations dialog box and click OK.

4. Type ASPNET (IIS 5), IIS_WPG (IIS 6),
   or IIS_IUSRS (IIS 7) in the list box labeled “Enter
   the object names to select” and click OK.

   If valid for your server, the account name you entered is
   added to the Security tab for the current directory. (You can check
   the validity of a group or user name by clicking Check Names before
   you click OK.)

5. Select the new account in the top list box on
   the Security tab, then select the check boxes for the access permissions
   you need under the Allow column in the bottom list box.

   You must select the Full Control check box for a directory
   containing a database that you connect to from your application.

6. Click the Advanced button.

   The Advanced Security Settings dialog box displays for the
   current directory.

7. Select the check box labeled “Replace
   permission entries on all child objects with entries shown here
   that apply to child objects” and click OK.

   A Security dialog box displays, warns you that it will remove
   current permissions on child objects and propagate inheritable permissions
   to those objects, and prompts you to respond.

8. Click Yes at the Security dialog box prompt, then
   click OK to close the Properties dialog box for the current directory.

Tracing runtime exceptions The pbtrace.log file
is created in the applicationName_root
directory. This file records all runtime exceptions thrown by the
application and can be used to troubleshoot the application.

Telerik RadControls

By default, PowerBuilder installs Telerik RadControls
for ASP.NET and deploys these controls with your Web Forms applications.
RadControls provide enhanced functionality for Web Forms toolbars
and menus, DatePicker and MonthCalendar controls, and TreeView controls.

Although not recommended, you can use IE Web Controls in place
of the RadControls, but you must change the PBWebControlSource global
property for your application and install the IE Web Controls on
the server. To use the RadControls, the PBWebControlSource property
is set to RAD for Web Forms projects. You must also make sure to
download ASP.NET AJAX extensions to the Web server as described
in “Installing AJAX Extensions “.

If you want to use IE Web Controls instead of RadControls,
see “Setting up IE Web Controls
on the server”.

Setting up IE Web Controls on the server

By default, PowerBuilder uses Telerik RadControls for a menus,
toolbars, and other controls in Web Forms applications. Although
not recommended, you can use IE Web Controls instead of the RadControls,
but you must change the PBWebControlSource global property for your
application and install the IE Web Controls on the server.

For information about Telerik RadControls, see “Telerik RadControls “. For information
about the PBWebControlSource property, see “Global Web configuration
properties “.

You can download IE Web Controls from the Microsoft Web site
. The download comes with a Readme
file that provides instructions for installing the controls.

After you install the IE Web Controls by running the build.bat file
included in the download, you must copy the controls to a webctrl_client1_0 directory under
the IIS root.

To copy the IE Web Controls:

1. Open a DOS command box.

2. Change directories to the directory where you
   installed the IE Web Controls.

3. Type the following line at the command prompt,
   modifying the server IIS root directory if you do not use the default c:Inetpubwwwroot directory:

   PowerBuilder

   xcopy /s /i .uildRuntime c:Inetpubwwwrootwebctrl_client1_0 /y

   1	xcopy /s /i .uildRuntime c:Inetpubwwwrootwebctrl_client1_0 /y

4. Press Enter.

   This creates the following directory structure under the root: webctrl_client1_0
   [images]
   [treeimages]

   The webctrl_client1_0 directory
   should contain the following files: MultiPage.htc, TabStrip.htc, toolbar.htc, treeview.htc, webservice.htc,
   and webserviced.htc

Installing AJAX Extensions

PowerBuilder uses AJAX
(Asynchronous JavaScript and XML) update functionality for Web Forms
applications. With ASP.NET AJAX, the page is updated by refreshing
individual regions of the page asynchronously.

An asynchronous postback behaves much like a synchronous postback,
but performance is enhanced through minimization of the content
sent to the server and rendered again in the client browser. The
rest of the page remains unchanged, therefore data traffic and page
flickering are significantly reduced.

Because PowerBuilder uses the AJAX update feature by default,
AJAX Extensions are required for Web Forms applications on all development
and deployment machines. You can download and install the Microsoft
ASP.NET AJAX Extensions version 1.0 from the ASP.NET Web site
.

The AJAX enhancement does not require you to modify your PowerScript code
or change the way you work in the PowerBuilder IDE.

How it works

UpdatePanels All container controls (Windows, Tabs, and UserObjects) and DataWindow
controls are wrapped with UpdatePanels. When there is any user interface-related
change within a container control or DataWindow control, the portion
of the page corresponding to those container controls or the DataWindow
control is updated.

The general rule of updating is that when the visual interface
in an UpdatePanel changes, the controls wrapped in the UpdatePanel
update. When one UpdatePanel nests in another, and the controls
in the outer UpdatePanel update, the controls in the inner UpdatePanel
also update. The reverse is not true; when a change is made to the
controls in an inner UpdatePanel, the controls in the outer UpdatePanel
are not rendered again.

You can reduce the areas to be updated in a page by encapsulating
objects and controls in Tabs and User Objects. By minimizing the
number of objects and controls in a container control, you reduce
the number of items that need to be rendered when the UpdatePanel
wrapping that container control is updated.

DataWindows The minimum unit of an UpdatePanel is usually a single container
control or DataWindow. DataWindows are not container controls because
the objects and controls they contain do not inherit from the PowerObject
class.

UpdatePanels that wrap DataWindow controls behave in the same
way as UpdatePanels for container controls. Master and detail DataWindows
are wrapped in separate UpdatePanels. If a master DataWindow is
updated by an event such as a button click, only the master DataWindow
is updated. When the information in the detail DataWindow is updated
by an event in the master DataWindow, only the detail DataWindow
updates.

Using synchronous update functionality

If you must use synchronous update functionality, you can
change the PBPostbackType global property to “Synchronous” in
the Web.config file that PowerBuilder creates
when you deploy your Web Forms application. However, support for
synchronous update functionality will be removed in future releases
of PowerBuilder and you cannot modify the PBPostbackType property in
the PowerBuilder IDE.

For information on global properties, see “Global Web configuration
properties “. For information
on modifying the Web.config file, see “Viewing and modifying global
properties in IIS Manager”.

Additional configuration requirements for Windows Vista

Default application pool

Virtual directories
in IIS 7 are hosted in an application pool. An application pool
is the host process for one or more Web applications. When you deploy
a PowerBuilder Web Forms application to IIS 7 in PowerBuilder 11.2,
the application is deployed to a PowerBuilder-specific application
pool named PBAppPool. On 64-bit Vista, the PBAppPool pool is configured
to run 32-bit applications.

To avoid compatibility issues with some features, Web Forms
applications deployed from PowerBuilder to IIS 7 must run in an
application pool that uses the classic managed pipeline mode, where
ASP.NET runs as an ISAPI extension. The PBAppPool application pool
uses the integrated managed pipeline mode by default, but you should
change it to use the classic mode if your applications use TreeView
controls, StaticHyperLink controls, or currency mask conversions.

To change the PBAppPool managed pipeline mode
to classic:

1. In IIS Manager, select Application Pools.

2. In the list of Application Pools, double-click
   PBAppPool.

3. Set Managed Pipeline Mode to Classic and click
   OK.

Changing this setting affects all applications running in
the PBAppPool application pool.

Creating a new application pool

You can also create a different application to host PowerBuilder
Web Forms applications.

To create and configure a new application pool
for Web Forms applications:

1. In IIS Manager, select Application Pools.

2. In the Actions pane, select Add Application Pool.

3. Provide a name, such as PBWebForms, for the application
   pool.

4. Set .NET Framework version to .NET Framework v2.0.50727.

5. If necessary, set Managed Pipeline Mode to Classic
   and click OK.

Enabling 32-bit applications on 64-bit Vista

On 64-bit Vista, you must enable the application pool to run
32-bit applications.

To enable 32-bit applications on 64-bit Vista:

1. In IIS Manager, select Application Pools.

2. In the list of Application Pools, select the application
   pool you have configured for use with PowerBuilder Web Forms.

3. In the Actions pane, select Advanced Settings
   under Edit Application Pool.

4. Expand the General settings, set Enable 32-bit
   Applications to True, and click OK.

Moving an application into a different application
pool

If you have created and configured a new application pool
for PowerBuilder, you need to move your PowerBuilder Web Forms applications
into the pool.

To move an application into a different application
pool:

1. In IIS Manager, expand Web Sites and Default
   Web Site.

2. Right-click the virtual directory for your application
   and click Advanced Settings.

3. Select the drop-down list next to the Application
   Pool property, select the application pool you created, and click
   OK

4. Reload the application.

Application directory permissions

When you deploy a new Web
Forms target, a temp directory is created in
the Inetpubwwwrootapplication_name directory,
where application_name is the name
of your application, and several subdirectories are created in the Inetpubwwwrootapplication_name_root directory.
Files are written to and deleted from these directories, therefore
the IIS_IUSRS group must have full permissions on temp and application_name_root.

---