Tuesday, July 03, 2007

Delphi IDE Features for ASP.NET Under the Hood

 

By: Jim Tierney

Abstract: Detailed information about Delphi IDE features for ASP.NET. Understand how Delphi works so that you can make it work for you.�

Jim Tierney is a staff engineer at Borland. He has 15 years experience in developing software tools. He has been a member of the Delphi team since 1996 when he helped develop Delphi3. He is currently the lead developer of ASP.NET features for Delphi.

jtierney@borland.com

 

Delphi IDE Features for ASP.NET Under the Hood

Jim Tierney Borland Software Corporation


Introduction

A New Project

Environment Options

File/New Menu

New ASP.NET Application

Project Files

Saving the Project

Building the Project

Running the Project

Project Files Types

Assembly References

Web.Config

Codebehind

Global.asax

Web Forms (*.aspx)

Web Services (*.asmx)

UserControls (*.ascx)

Managing Project Files

Adding New Files

Adding Existing Files

Removing Files

Renaming Files

Renaming Projects

Subdirectories

Saving Files

Running, Debugging and Deployment

IIS Virtual Directories

Cassini

Deploying Projects

Run Problems

Debug Mode

Debugging Options

Refreshing a Page

Compiling Markup Files

Copy Local

Designer

Relationship between Tool Palette and Form Loading

Absolute Positioning User Controls

The ms_positioning Attribute

What Happened to My Component Tray?

Customizing the IDE

Customizing the File Menu

Customizing HTML Snippets

Customizing New File Templates

Grab Bag

One Project Allowed in a Directory?

Named and Unnamed Projects and Modules

Automatic File Saving

Undo After Save

Problems with File/Save As...

Rename Commands

Renaming User Control Modules

Using "~" in File Names

Problems with Leftover Files

Summary


Introduction

Delphi takes care of some of the grunt work involved in creating, editing, building and debugging ASP.NET application. By explaining what Delphi does and why, this paper can help developers can be more productive and confident.

 

This paper explains what goes on when Delphi is used to create, edit, build, or debug an ASP.NET application. It discusses problems that can occur, and how to fix them. It highlights Delphi features that that may not be well know, but can make developers more productive. Finally, although this paper does not focus on the ASP.NET framework, the information about how Delphi works with ASP.NET leads to a better understanding of ASP.NET.

A New Project

This section highlights the features that are used to create, build, and run an ASP.NET project.

Environment Options

Use Tools/Options/ASP.NET to configure the defaults for a new project. If you know that you will always want your projects created under a particular directory or that you will always be using a particular server, then specify these options so that the File/New/Project wizard shows your preferred options by default. Environment Tools/Options/ASP.NET is also where you configure the IDE to use the Cassini web server. See Cassini.

 

The Base Directory field indicates the location where a new project directory should be located. Each ASP.NET project is located in a separate directory.

While you are in the Tools/Option, you may want to check Undo After Save. This is useful because ASP.NET applications automatically save some file on compile (see Automatic File Saving).

File/New Menu

When Delphi installs, the File/New menu is configured with commands to create commonly used project and module types, such as VCL Forms Application, VCL Form, and Unit. Some of these types only show in the File/New menu when a particular project type is active. For example, VCL Form shows after a VCL Forms Application is created. All of the project and module types shown on the File/New menu may be created using the File/New/Other dialog box, but an entry on the File/New menu is more convenient. Use the File/New/Customize command to add addition ASP.NET project and file types such as ASP.NET Page. See Customizing the File Menu

New ASP.NET Application

To create a new ASP.NET project choose File/New/ASP.NET Application. (or use File/New/Other). The wizard prompts for name of the project, the directory of the project, and the web server. The default directory is determined by looking for a directory that does not contain an ASP.NET project. By default, the name of the project is same as the name of the project directory. You can change either of these fields. However, you will need to choose a directory that does not already contain a project (See One Project Allowed in a Directory?).

 

The server that you choose affects how your project options are configured. The three choices are IIS, Cassini, and Not Specified. In the case of Not Specified, the project will not be configured to use a server. Before you can run or debug your project from the IDE, you will need to modify project options. If you choose Cassini then your project will be configured to run or debug using Cassini. See Cassini. If you choose IIS then your project will be configured to run or debug using IIS. This option will also create an IIS virtual directory. See IIS Virtual Directories.

Project Files

A new ASP.NET application has assembly references, a web.config file, a global module, and a web form module. A new ASP.NET Web Service application has different assembly references and a web service module instead of a web form module.

 

 

The References node is first node shown in the project manager. Expand References to see the projects assembly references. The new project wizards add a set of assembly references typically needed in an ASP.NET application. However, not all references are required to build a new application. See Assembly References for more information

 

The Global.asax is the next sibling node after References. The Global module consists of the Global.asax markup file the Global.pas codebehind file. You would use this class to implement code that executes every page request, for example a hit counter. See Global.asax for more information.

 

After Global.asax in the project manager is Web.config. Web.config is an XML file that, as you would expect, configures your web application. See Web.Config for more information.

 

Following Global.asax in the project manager is WebForm1.aspx. The WebForm1 module consists of the WebForm1.aspx markup file and the WebForm1.pas codebehind file. See web forms for more information.

 

Delphi generates web.config, the Global module, and WebForm1 from templates in the objreposdelphidotnet directory. You can customize the templates to change the contents of new files generated by File/New wizards. See Customizing New File Templates.

Saving the Project

You do not need to save the project at this point. However, if you plan to change the project name or the name of the projects web form or web service then it is a good time to do so. By renaming now, rather than after building you will avoid creating files on disk that will need deleting.

 

Renaming a project or a markup file can result on leftover files in your project directory that the can be processed by the ASP.NET runtime, potentially resulting in runtime compilation error or unexpected results. See Problems with Leftover Files.

 

Using the File/Save Project Ascommand to save a project in a different directory is not recommended for ASP.NET projects because the project can end up in a different directory than the rest of the project files. Instead of using File/Save Project As save all of the project files and use the Windows Explorer or a command prompt to xcopy the project directory to a new directory.

Building the Project

The new ASP.NET application is ready to compile. All of the .pas files (i.e.; Global.pas and WebForm1.pas) will be compiled into an assembly in the bin directory (See Bin Directory for information about this directory). After the project has compiled, Delphi automatically saves some of your project files to keep the assembly and the markup files consistent. See Automatic File Saving.

Running the Project

If you have configured your ASP.NET application to use IIS or Cassini, then your application is ready to run or debug. If you created your project without specifying a server, then you will need to configure a server in project options. See Debugging Options.

 

The first time that you run your application there is a delay while the ASP.NET runtime compiles your markup files (See Compiling Markup Files). After this delay, you should see a blank page displayed in the web browser. This is WebForm1.aspx, which the new project wizard configured as the start page. See Debugging Options for more information about the start page.

 

Three types of problems prevent your ASP.NET application from running: markup compilation error, debugger error, and server error. See Run Problems.

 

As you make changes to your application, you may be able to test the changes without restarting your application. See Refreshing A Page.

Project File Types

This section discusses the types of files that make up an ASP.NET project.

Assembly References

The References node is first node shown in the project manager. Expand references to see the projects assembly references. The new project wizards add default assembly references. Not all of the default assembly references are required to build a new project. The assembly references that are required to build a new Web Form application are System.Web.dll and System.Dll. The assembly references required to build a new Web service project are System.Web and System.Web.Services.Dll. As you add controls to your project, assembly references may by added. This is important to realize because all of the referenced assemblies must be available on the computer where your ASP.NET application is deployed. See Deploying Projects.

 

Copy local is an option that can be checked on each assembly. This option is checked automatically when you reference an assembly that is not in the GAC (Global Assembly Cache). See Copy Local.

Web.Config

Web.config is an XML file that, as you would expect, configures how your application runs. You would modify this file to set up forms authentication, for example. Delphi must add a web.config with debug=true to enable Debug mode.

Codebehind

Codebehind is the term used to describe the relationship between the markup file (e.g.; webform1.aspx, usercontrol1.ascx, global.asax, or webservice.asmx) and the .pas file that makes up an ASP.NET module.

The .pas file is called the codebehind file because it implements an ancestor class. When the markup is compiled (See Compiling markup files) by the ASP.NET runtime, a descendent class is generated.

A directive in the markup file indicates the ancestor class name. For example, an .aspx file contains a page directive that looks like this:

<%@ Page language="c#" Debug="true" Codebehind="WebForm1.pas" AutoEventWireup="false" Inherits="WebForm1.TWebForm1" %>

The Inherits attribute indicates that the ASP.NET runtime should generate a class that derives from WebForm1.TWebForm1. This class is implemented in the codebehind assembly built when Delphi compiled the application. This class will be found in the codebehind assembly because the names of all of the assemblies in the project's bin directory, including the codebehind assembly, are passed to the compiler by the ASP.NET runtime.

Global.asax

The Global module consists of the Global.asax markup file and the Global.pas codebehind file The Global module implements a descendent of System.Web.HttpApplication. This class is instantiated by the ASP.NET runtime to handle requests to any page. You would use this class to implement code that executes on a request to any page, for example a hit counter. If the application does not define a descendent of System.Web.HttpApplication, the ASP.NET runtime will instantiate its own HttpApplication. Global.asax can be removed from your application if it is not needed. The designer for Global.asax is used to drop non-visual controls such as data components.

Web Forms (*.aspx)

A Web Form module consists of the WebForm*.aspx markup file and the WebForm*.pas codebehind file. Web Forms implements a descendent of System.Web.UI.Page. The designer for descendents of System.Web.UI.Page is an HTML designer that will show a component tray when a non-visual control is dropped on the page.

Web Services (*.asmx)

A Web Service module consists of the WebService*.asmx markup file and the WebService*.pas codebehind file. Web Services implements a descendent of System.Web.Services.WebService. The designer for descendents of System.Web.Services.WebService is a non-visual component designer.

UserControls (*.ascx)

An ASP.NET user control is not to be confused with a WinForm user control or a custom control. One way to think of it is as an include file. A user control module is made up of a markup file and a codebehind file. The markup is a little different from a web forms markup because a user control does not have <html, ><heading> or <body> tags. This is because a user control represents a fragment of markup that will be inserted into a web form or other user control at runtime.

 

To insert a User Control into a Web Form, use the Insert/Insert User Control command. Inserted user controls always display as a gray box. See also Absolute Positioning User Controls.

Managing Project Files

This section highlights the features that manage the files in your ASP.NET project.

Adding New Files

Use the File/New/Other gallery to add new files to your project.

 

 

New web forms, web services, and user controls are generated with a name that does not conflict with an files in your project or in your project directory. The markup file (e.g.; webform2.aspx) and codebehind file (e.g.; webform2.pas) will have the same base name. At this point, neither file is saved to disk. If you want the module to have a different name or be located in a subdirectory, now is a good time to use Save As or the Rename Commands. Changing the name of a markup file now, before it has been saved, avoids problems with leftover files.

 

A new Web.Config file is always called Web.Config. If your project already has a Web.Config and you want to add an additional Web.Config to your project, use the Rename Commands to change the name of the existing Web.Config or move the existing Web.Config to a subdirectory. (A Web.Config file in a subdirectory is sometimes used to indicate that the authentication requirements are different between the project root directory and the subdirectory.).

Adding Existing Files

The Project/Add to Project command adds existing files to your project. When a markup file (e.g.; *.aspx, *.ascx, *.asmx, *.asax) is added to the project, Delphi automatically looks for a matching .pas codebehind file in the same directory to add. Likewise, when a .pas file is added to the project, Delphi looks for a matching markup file to add. If Delphi does not find both markup and codebehind then the designer will not display.

 

ASP.NET markup files must be located within the project directory in order for the ASP.NET runtime to find them. So when adding ASP.NET files to a project, copy the markup and codebehind (and .resx, if any) to the project directory or subdirectory before using Project/Add to Project.

Removing Files

The Project/Remove from Project command removes a module from your project. When you remove an ASP.NET file, Delphi will remove both the markup and codebehind files from the project.

 

Project/Remove from Project does not delete files from disk. The ASP.NET runtime can access any of the markup files in your project directory, so it is important that you delete at least the markup files that are no longer in your project. See Problems with leftover files.

Renaming Projects

The Project/Save As command is used to save the project using a different name and/or to a new location. Rename is also supported, either through in-place rename in the project manager (click on the project name), or using the object inspector.

 

Renaming a project can result in leftover assemblies in your projects bin directory that can result in ASP.NET runtime compile errors. Be sure to delete any assemblies from you bin directory that have the old project name. See Problems with Leftover Files.

Renaming Files

The name of a module can be changed using the File/Save As Command, in place rename in the project manager, and by using the object inspector. It is also possible to rename an ASP.NET modules codebehind file independently of the markup file.

 

The Save As command creates a new module with a different name. This can be a problem when using Save As with ASP.NET modules because the user may be able to browse to the old markup file. See Problems with Leftover Files.

 

Renaming a module using either in-place rename in the project manager, or the object inspector does not create another file. So use either of these techniques to change the name of an ASP.NET module to avoid creating leftover files in your project directory.

 

When an ASP.NET markup file is renamed, the associated .pas file and .resx (if any) will also be renamed if the files have the same base name (e.g.; webform1.aspx and webform1.pas). The markup files directive (i.e.; @Page, @WebService, @Control, or @Application) updates to indicate the name of the .pas codebehind file.

 

In, for some reason, you want the codebehind file to have a different base name from the markup file, use in-place rename or the object inspector to rename the codebehind .pas file.

See also Renaming UserControl Modules and Rename Commands.

Subdirectories

Project subdirectories are used to group different types of ASP.NET applications files such as images, web form, and web user controls. Subdirectories are also used for functional reasons. For example, using web.config, a subdirectory may be configured with different authentication requirements than the project root directory.

 

Delphi always adds new files to the project root directory. You can use the File Save As command to move a new file to a sub directory. If you have already saved a file, it is best to use the project managers in-place rename feature (or object inspector) to move the module to a subdirectory. See Rename Commands.

 

Delphi does not support markup and codebehind in separate directories so do not put webform1.pas in a different subdirectory from webform1.aspx.

 

If you move a user controls in a different subdirectory from the web forms or user control that references it, then you will need to update the @Register directive. See Renaming UserControl Modules.

Saving Files

In order for the ASP.NET runtime to access the markup files and web.config in your project they must be saved to disk. These files are automatically saved when you compile the application in Delphi. See Automatic File Saving. However, if you make changes to a markup file or web.config while the application is showing in a browser, save the file before refreshing the page so that ASP.NET will reload the markup. See Refreshing A Page.

Running, Debugging, and Deployment

IIS Virtual Directories

If your project is configured to use IIS , it will not run from the IDE unless project directory is a properly configured IIS virtual directory. When you choose IIS as the server for a new project, Delphi creates an IIS virtual directory for you. The New Project dialog gives you a few options for configuring the virtual directory when you click the View Server Options button. The dialog looks like this after this button is clicked:

The Read and Run scripts options are checked by default. Run Scripts is required for ASP.NET applications.

When you choose OK, the location (project directory) and Alias (IIS virtual directory name) are validated. If the location exists and already contains a project files then you will get an error. See One Project Allowed in a Directory? for why this is an error. At this point, either choose a different location or remove the files from the directory. If the Alias exists and is not associated with the Location then you will get an error because an alias cannot be associated with multiple directories (however, you can have multiple aliases associated with the same location) You will need to change either the location or the alias. See to how the virtual directory gets defined in IIS, use the MS Windows Internet Information Services Administrative Tool. You will find the virtual directories listed under the local computer/Web Sites/Default Web Site node.

When you change an existing project to use IIS you may need to create a virtual directory. The Delphi Project Options dialog will do this for you. Select Internet Information Server (IIS). When you choose OK, Delphi will create a virtual directory unless it already exists.

In some cases your project may be configured to use IIS but your computer does not have the virtual directory defined in the project. This can happen with a project that was created on another computer. You can trick the Delphi into creating a virtual directory by overtyping one of the characters in the Project Options Virtual Directory field and choosing OK.

If you save your project to a new location then you will need to change the virtual directory configuration. You can use the Internet Information Services Administrative Tool to change the physical directory associated with the projects virtual directory or use Project Options to create a new virtual directory.

If you are not sure whether the virtual directory is configured. Click the Server Options button. The Configure Virtual Directory button will tell you whether the virtual directory exists and how it is configured. You cannot change the configuration of a virtual directory here (e.g.; Enable Browse). Use The Internet Information Services Administrative Tool for that.

Cassini

Cassini is an HTTP server that is designed to run ASP.NET applications. For your convenience, the Cassini source code is included with Delphi in the demoscassini directory. To build Cassini, change directory to demoscassini and execute the build.bat file. The c# compiler is used to build Cassini, so you will need to have Csc.exe on the path. Typically the path is c:windowsmicrosoft.netframeworkv1.1.4322. A common mistake is to build Cassini with the wrong framework version. Be sure that Cassini is built with the version 1.1.4322.

 

You can configure Delphi to use Cassini to run and debug ASP.NET applications. You must specify the location of the CassiniWebServer.exe file and the port to use in Tools/Options/ASP.NET. The BDS environment variable may be used to identify the directory where Delphi is installed. Choose a port that is not used by another application. For example, don't use port 80 because is typically used by IIS.

 

 

If Cassini will be your preferred server for new application, select Cassini Web Server in the Web Server drop down so that the New Project wizard will select Cassini selected by default.

 

When creating a new project, the File/New wizard lets you specify Cassini. You can configure an existing project to use Cassini in the Project/Options dialog.

 

When running or debugging with Cassini, Delphi passes the correct parameters to CassiniWebServer.Exe. The first parameter is the directory where the project is located, the second parameter is the port, and the third parameter is the virtual directory. Cassini looks like this when it is started:

 

 

Debugging an HTTP server with Cassini can be more reliable than IIS. However, it does not support the directory structure of IIS. For example, in IIS you can have a /Images directory. Cassini only knows about the project directory. It can only access files in this directory and sub directories. Therefore when using Cassini, you will will need to have all of your project files under the project directory. This limitation of Cassini causes problems with validation controls. By default, the client-side file WebUIValidation.js is located in an IIS virtual directory called aspnet_client. The element <webControls clientScriptsLocation="/aspnet_client/{0}/{1}/"/> in machine.config tells ASP.NET to reference this virtual directory. ASP.NET applications running under IIS will be able to find WebUIValidate.js. The same application running under Cassini will not. You can workaround this problem by copying WebUIValidation.js into your project directory and modifying web.config as follows:

 

  1. Create a directory in the project called aspnet_client
  2. Copy WebUIValidation.js from the aspnet_client virtual directory into your projects aspnet_client
  3. Add this element to web.config under <system.web>: <webControls clientScriptsLocation="aspnet_client/"/>

If you run without debugging be sure to shut down Cassini before running again. Otherwise, Cassini will report an error because the port is in use by another application (the running instance of Cassini).

Deploying ASP.NET Projects

Deploying your application to another computer or another virtual directory on your computer is a matter of copying the files that are needed to run your application. Your deployment directory should have the same subdirectory structure as your development directory.

Files to deploy (from project root directory and subdirectories)

Markup files

*.aspx, *.ascx, *.asmx, *.asax

Config files

Web.Config

Image Files

*.jpg,*.gif, etc.

Html files

*.html, *.htm, *.css, *.js

Executables

Bin/*.dll

Some of the files that you wont need include:

Source files

*.pas

Object files

*.dcuil, *.dcpil

Project files

*.bdsproj, *.dpk, *.dpr

In some cases, you may need additional assemblies in your deployment bin directory because the deployment computer does not have all of your assemblies installed in the GAC. In this case you can use the Copy Local option to copy files to your projects bin directory before you copy assemblies from your projects bin to the deployment bin.

One of the assemblies that often needs to be copied is Borland.Delphi.Dll. Borland.Delphi.Dll will be referenced by your ASP.NET application if it is built with any Delphi.Net packages. For example, your ASP.NET application will reference Borland.Delphi.dll if it contains ASP.NET custom controls built with Delphi. (The custom control assembly will probably also need to be copied).

ASP.NET Run Problems

Three types of problems prevent your ASP.NET application from running: markup compilation error, debugger error, and server error.

 

A markup compilation error occurs during ASP.NET runtime compilation of the markup file. (See Compiling Markup Files). You will see an error message in the browser.

7        If the error is caused by duplicate class then you may have a left over assembly in bin. See Problems With Leftover Files.

7        When running on localhost, ASP.NET will provide detailed compiler output in the browser. Examine this output to determine the cause of the problem.

 

A debugger error happens when the Delphi debugger cannot attach to the ASP.NET process.

7        This error can happen under IIS and may be caused by a problem in the installation of ASP.NET in IIS. The utility aspnet_regiis.exe will reinstall asp.net into IIS. Use the i option. This utility is typically located in c:windowsmicrosoft.netframeworkv1.1.432.

7        The Delphi debugger is not always successful in attaching to IIS. Additional attempts to debug may succeed.

 

A server error occurs when the server (Cassini or IIS) is not configured properly or when the project options are not correct.

7        Verify that your project options are correct. See Debugging options.

7        If using IIS, verify that you have a virtual directory. See Server Options.

7        If using Cassini, verify that Cassini is using your project directory and is using an available port. Verify that an instance of Cassini is not already running.

 

ASP.NET Debug Mode

Debug mode tells ASP.NET to generate symbols for dynamically generated files and enables the debugger to attach to the ASP.NET application.

Because this creates a larger file that executes more slowly, you should set this value to true only when debugging and to false at all other times.

New Delphi ASP.NET applications enable debug mode by the following entry in Web.Config:

 

<configuration>

<system.web>

<compilation

debug="true"

 

Disable debug mode by setting debug=false.

 

ASP.NET Debugging Options

Project/Options/Debugger/ASP.NET displays the options for configuring your project for ASP.NET debugging. The debugger will not start unless both Launch Browser and Host with Web Server are checked.

When using IIS, you can verify the existence of a virtual directory by clicking the Server Options button.

There are additional debugging options on the Debugging page. The ASP.NET debugging options supercedes these options, do not modify the options on this page.

Refreshing a Page

When you are debugging an ASP.NET application, you can test the affect of some types of file changes without rebuilding, restarting, or closing the web browser. In general, if you have not modified a .pas file but only markup files or web.config, then you only need to save the modified files and refresh the page. When you refresh the page shown in the web browser or browse to another page in your application, ASP.NET will automatically detect changes to markup files (See Compiling Markup) and recompile the markup.

 

If you are running without debugging, then you can also recompile the project and test changes without restarting the browser. The ASP.NET runtime will automatically detect that an assembly in the bin directory has been modified and that markup files should be recompiled.

 

If the page displayed by the browser is posting back (e.g.; you clicked a button), some modifications to the markup files may cause problems when the page is refreshed. For reliable results, browse to a different page in your application rather than use the browsers refresh command.

Compiling Markup Files

Each time you browse to a web form in your ASP.NET application, the ASP.NET runtime determines whether the markup file has changed or is new and recompiles if necessary.

 

To compile a markup file, the ASP.NET runtime generate c# from the markup files (global.asax, webform1.aspx) then compiles the c# into an assembly. By default, the names of all of the assemblies in your projects bin directory (this can be customized in web.config) are passed as references to the compiler. Typically the bin directory contains your codebehind assembly and any assemblies that you have marked as copy local.

 

If you had renamed your project there may be a leftover assembly in the bin directory that can cause a compiler error. See Problems With Leftover Files.

Copy Local

The Copy Local option is checked on a referenced assembly (see the references node in the project manager) to cause the assembly to be copied to the projects bin directory when your project is compiled. Copy Local is checked by default when using an assembly that is not in the GAC (Global Assembly Cache). Without a local copy in the projects bin directory, the ASP.NET runtime would not be able to load the assembly.

 

In most cases, you will not need to check Copy Local for assemblies in the GAC. However, if you plan to deploy your application to another computer that does not have your assemblies in the GAC then the Copy Local option is a convenient way to get a copy of those assemblies in your projects bin directory.

Designer

Relationship between Tool Palette and Form Loading 

In web forms and win forms a form can be loaded even if the components on the form are not installed on the palette. This is because the project has references to the components. On the other hand, a web form or win form may not be able to load a component even if the component is installed on the palette. Reasons for load failure can be an assembly reference missing from a project or an assembly file that cant be found. Sometimes adding a path in Component/Install .NET Components/Assembly Search Path will help the IDE find an assembly file.

Absolute Positioning User Controls

User controls do not support absolute position.  Neither does asp:literal. However, you can put a either of these controls inside a flow panel and absolute position the panel.

In general, ASP controls that derive from WebControl support absolute positioning because WebControl has a Style property.  User control and asp:literal do not derive from WebControl.

The ms_positioning Attribute

The ms_positioning attribute is used in the <body> tag <div> tags and asp:panel to indicate the default layout mode of controls dropped on a container.

 

Value

Designer Behavior

Ms_positioning=Grid

Draw grid on the control. Controls dragged onto the container will be absolute positioned (if possible, see Absolute Positioning User Controls).

Ms_positioning=Flow

Do not draw a grid. Controls dragged on the container will be text positioned.

No attribute.

Same as ms_positioning=Grid

 

Note that you if you would like new web forms or new html pages to default to flow layout, you can add ms_positioning=Flow to the templates. See Customizing File New Templates.

What Happened to My Component Tray?

The component tray on web forms and user controls displays non-visual components such as DataSet. In some cases, the component tray will stop showing your non-visual components because the designer has failed to detect non-visual components in the codebehind file. This can lead to removal of non-visual components from the codebehind fileand probably a very frustrated developer.

When the designer fails to show non-visual components, an error occurred while parsing the codebehind file. The InitializeComponent procedure in the codebehind file initializes all of the non-visual components by constructing them and setting their properties. The InitializeComponent procedure is executed when the form is loaded at runtime. At design time, the code in this procedure must be parsed to determine which non-visual components to instantiate and how to set their properties. If errors occur while parsing the InitializeComponent procedure then one or more non-visual components may not be detected and consequently will not show in the component tray. At this point your codebehind files InitializeComponent procedure is intact. However if you make changes to the designer at this point and save, the designer will update the InitializeComponent procedure removing the components that the designer was not aware ofcausing permanent loss of some or all of your non-visual components.

The most important thing that you can do to avoid permanent loss of non-visual component is to enable Undo After Save. This will allow you to recover your non-visual components even after you have saved.

Usually compiling your application will indicate where the parsing problem occurred. It could be caused by a syntax error or a missing assembly reference. Correct the problem in the codebehind and then show the designer. The designer will automatically detect that the codebehind has been modified and needs a reparse.

Customizing the IDE

Customizing the File Menu

When Delphi is installed, the File/New menu is configured with commands to create commonly used project and module types, such as VCL Forms Application, VCL Form, and Unit. Some of these types only show in the File/New menu when a particular project type is active. For example, VCL Form shows after a VCL Forms Application is created. All of the project and module types shown on the File/New menu may be created using the File/New/Other dialog box, but an entry on the File/New menu is more convenient.

 

 

 

By default the File/New menu includes ASP.NET Web Application, however you may want to customize the File/New menu to include other ASP.NET project and file types such an ASP.NET Web Service Application, ASP.NET Page, ASP.NET User Control, and ASP.NET Web Service. Choose the File/New/Customize command to display the customize dialog box. Drag from left to right to add to the File/New menu. Drag from right to left to remove from the File/New menu. The File/New menu is updated when you choose OK. You will not see ASP.NET module types such as ASP.NET Page in the File/New menu until you create an ASP.NET project.

 

Customizing HTML Snippets

The names, images, and content of the elements on the HTML palette are loaded from the objreposhtmlsnippets.xml file. Modify this file to add new HTML controls to the palette or change the content generated when an item from the HTML palette is dropped on a web form or HTML page. You must restart the IDE in order for Delphi to reflect changes made to htmlsnippets.xml. Each element in htmlsnippets has the following attributes:

 

Attribute Name

Value

ID

Numeric id. Each element must have a unique ID.

Title

Title shown in the tool palette.

Image

Internal image name. When adding a new element you must use an existing image name.

 

The content of each element is the html that is inserted when the item is dropped on a web form or HTML file. For best results, use an XML editor to modify element content so that < is translated into &lt; etc.

Customizing New File Templates

Template files are used to generate contents of new ASP.NET project files including web.config, Global, web forms, web services, web custom controls, and user controls. The template files are located in the objreposdelphidotnet directory (c:program filesborlandbds2.0objreposdelphidotnet by default). You can customize the template files. For example, there may be standard comments that you want in all of your new .pas files. The File New wizards always load templates from disk, so it is not necessary to restart the Delphi after modifying and saving template file.

 

File/New Wizard

Template File(s)

ASP.NET Web Application

WebFormProjectTemplate.dpr

ASP Net Web Service Application

WebServiceProjectTemplate.dpr

Web Control Library

WebControlLibraryProjectTemplate.dpk

ASP.NET Page

Page.aspx.pas, Page.pas

ASP.NET User Control

Control.ascx.pas, Control.pas

ASP.NET Web Service

WebService.asmx.pas, WebServices.pas

Global.asax

Global.asax.pas, Global.pas

Web Configuration Files

Web.config

Web Custom Control

WebCustomControl.pas

Grab Bag

This section covers topics that are worth including in this paper but did not fit in any of the other sections.

One Project Allowed in a Directory?

Delphi will not let you create multiple ASP.NET project in the same directory. The reason is to prevent ASP.NET runtime errors that can occur when the project directory contains files that are not part of the project. See Problems With Leftover rFiles.

If you would like to reuse a directory, delete the content before using File/New.. wizard

Named and Unnamed Projects and Modules

If you are a long time Delphi developer, you may wonder why an new ASP.NET project needs a directory location. Traditionally, new Delphi projects were unnamed. Delphi prompted the developer for the name and location of the project the first time it was saved. You may have also noticed that you are not prompted for the name and location of new web forms the first time they are saved. Why do ASP.NET projects behave this way?

The ASP.NET runtime expects all web forms, web.config files, and user controls to have a common root directory. Therefore, Delphi names a new project and new web forms, web.config files, and user controls to ensure that they are saved into the project directory. Simple Unit source files are not processed by ASP.NET at runtime. So, when you create a unit using File/New/Class, youll get an unnamed file. Delphi will prompt for the name and location of a class file when it is saved the first time.

Automatic File Saving

Delphi will automatically save web.config, web forms, user controls, and global are after your ASP.NET application compiles. This keeps your markup files and the codebehind assembly from being mismatched (for example, the name of a control in the markup file does not match the name of the control in the codebehind assembly).

If you change a markup file while your application is running you will need to explicitly save the file in order to see changes in the browser. See Refreshing a Page.

Undo After Save

Undo after save is a particularly useful feature when working with ASP.NET projects for a couple of reasons. First, because Delphi automatically saves some types of ASP.NET project files (See Automatic File Saving), you will not be able to undo changes after a compile unless Undo after save is enabled. Second, if you lose components in a component tray because of syntax errors or missing assembly references (See What Happened to My Component Tray?), Undo after save will allow you to restore the lost components.

Undo after save is an editor feature that is disabled by default. To enable, check Undo after save in Tools/Options/Editor Options

Bin Directory

Delphi automatically configures new ASP.NET applications output directory to bin. In addition to the codebehind assembly built when your project is compiled, the bin directory will also contain any assemblies marked as Copy Local.

 

When the ASP.NET runtime compiles a markup file, all of the file names of the assemblies in the bin directory are passed as references to the compiler (e.g.; csc.exe). The ASP.NET runtime will encounter a compile error if the bin directory does not contain the correct assemblies. To avoid this problems do not change your projects output path and be sure to remove any assemblies that are no longer part of your project. For example, if you rename your project, remove the assembly with the old name from bin. See Problems with Leftover files.

Problems with File/Save As

Delphi developers are familiar with the File/Save As command and have used this command to change the name of modules in their projects. The problem with Save As, when used on markup modules (e.g.; webform1), is that it tends to leave behind copies of files that, though no longer referenced by the project, may be accessed though the web browser when the project is running. If Save As is used on a markup module, be sure to remove the markup (.aspx, .ascx, or .asmx) from the project directory. Alternatively, rename the file using in-place rename or the object inspector. See Rename Commands.

Rename Commands

Right click on the file and choose the Rename command. To use the object inspector, select the file in the project manager and then edit the File Name property in the object inspector. Both in-place rename and rename using the object inspector allow you to specify a subdirectory as long as the subdirectory already exists. This is a convenient way to move a file into a subdirectory. For example, if you have a folder called forms you can rename webform1.aspx to formswebform1.aspx.

 

When an ASP.NET markup file (e.g.; webform.aspx) is renamed, the associated .pas file and .resx (if any) will also be renamed if the files have the same base name (e.g.; webform1.aspx and webform1.pas). The markup files directive (i.e.; @Page, @Server, @Control, or @Application) updates to indicate the name of the .pas codebehind file.

 

In, for some reason, you want the codebehind file to have a different base name from the markup file, use in-place rename or the object inspector to rename the codebehind .pas file by selecting the .pas file in the project manager.

Renaming UserControl Modules

A rename of a user control module requires special care because other user controls or web forms in you project may reference the renamed user control by file name. At the top of the referencing markup file, you will see a directive that looks something like this:

<%@ Register TagPrefix="uc1" TagName="WebUsersControl1" Src=" WebUsersControl1.ascx" %>. Change the value of the Src attribute to reference the new user control filename. If you move a user control to a subdirectory, you will also need to include the directory of the user control in the Src attribute. Consider using the ~ character to construct a project relative path. See Using ~ in filenames.

Using ~ in File Names

The ~ is used in filenames to refer to the root directory of the web application. It is a shortcut for the HttpRuntime.AppDomainAppVirtualPath property. The MSDN documentation for this property says this Gets the virtual path of the directory that contains the application hosted in the current application domain.

 

Use ~ to create project relative references:

 

  • User control references. Src=~controlswebcontrol1.ascx in the @Register directive creates a reference to a webcontrol1.ascx in the controls subdirectory that works no matter where the web form or user control containing the directive is located within the project subdirectories.

 

  • Images. Use ~ to create a project relative reference to an image.

 

<asp:image id=image1 runat="server" imageurl="~imagesbanner.jpg"></asp:image>

 

when ~ is used in an html <img>, runat=server is required

 

<img runat=server src="~imagesbanner.jpg" >

 

  • Hyperlinks. Use ~ to create a project relative reference to a webform:

 

<asp:hyperlink id=HyperLink1 runat="server" navigateurl="~WebForm2.aspx">Goto WebForm2</asp:hyperlink>

 

when ~ is used in an html <a>, runat=server is required:

 

<a href="~Webform2.aspx" runat=server>WebForm2</a>

 

Problems with Leftover Files

The term leftover files refers to files that are in an ASP.NET project directory but are no longer part of the project. For example, you may have a WebForm1.aspx file in your project directory because File/Save As renamed WebForm1. You may have WebApplication1.dll in your bin directory because File/Save Project As renamed WebApplication1 and then you compiled the project.

 

Leftover markup files and leftover assemblies can cause problems at runtime. Markup files that are no longer part of the project may cause ASP.NET runtime compilation errors and other unexpected results if an end user browses to the file. Assemblies that are no longer part of your project may also cause runtime compilation errors because the ASP.NET runtime will attempt to resolve types using all assemblies in the bin directory.

 

To avoid problems, delete leftover files after using File/Save As. Use the Rename Commands instead of Save As to rename ASP.NET modules such as web forms. See also Bin Directory.

Summary

This paper has provided quite a lot of information about the details of ASP.NET support in Delphi. I hope that you have learned a few things about Delphi you will be able to use right away to improve your productivity, and a few things that will help you in the future.

0 Comments: