Tutorial for Visual Studio .NET 2003

This tutorial demonstrates the use of PageMethods for VS.NET 2003 through a step-by-step sample.

Sample application

We won't go into a complex application here. The goal is to demonstrate the use of PageMethods as simply as possible.
We will just consider two web pages, that should be sufficient to get an overwiew of the functionalities.

The first page will be used to edit details about a customer, or to create a new one. Let's name it FrmCustomer.aspx.
The second page will contain a list of the customers. That will be ListCustomer.aspx.

Step by step

1 - FrmCustomer

We will start by creating the FrmCustomer page.

First, make sure the PageMethods add-in is installed and activated.

Next, create a new web project named PageMethodsTutorial.

Add a new web page named FrmCustomer.aspx.

Let's say this page will enable specifying a name and a country for a customer.
Add three labels, three EditBox controls (txtID, txtName, txtCountry), and a button to the page, as follows:

We said this page would be used to edit details about a customer or to create a new one, so we will add two methods to the page that will represent these two ways to use the page.
Switch to the code view, and add the two methods:

Until now, all we have is standard code. We will add an attribute to these methods to start using PageMethods.
This requires adding a reference to the PageMethods Library (PageMethods.dll assembly).

Make sure you select the library for .NET 1.1. The version and the runtime may vary depending on the version you are using.

Let's use the MetaSapiens.PageMethods namespace:

Here is how to add the attributes:

We will now be able to refer to these methods from outside.
We still need to do a few last things before that.

Add a call to the PageMethods framework in the Page_Load event handler:

Activate PageMethods for this project.

Compile to have PageMethods generate its magic code.

A file named PageList.xml and a code file depending upon it will be generated, but you don't have to care about this. It is important that you never touch these files and leave them as is. PageMethods will manage them for you.

2 - Referring to FrmCustomer

The page we just created is only useful if we are able to access it, of course.
Usually, we would create a link to it using either an HTML anchor (<A href=...> tag) or the ASP.NET HyperLink control with a static value for the NavigateUrl property.

With PageMethods, we can choose between two methods: databinding and code-behind.
We recommend the second method because it allows us to take advantage of compile-time checks. This way we can be sure before deployment that the links we use are valid. We will demonstrate here the two ways.

We will test this in the Default.aspx page.

Add two HyperLink controls to the page.

2.1 - DataBinding

The first HyperLink control will use the databinding solution.
Edit the (DataBindings) property of the HyperLink control and set its NavigateUrl property as follows:

This method requires the DataBind method to be called to work.

2.2 - Code-behind

The second HyperLink control will be set from the code-behind:

Hint: you can use the code completion to help you.

Linking to a page this way is easy because you can see the available pages and the ways to invoke them. It is also safer because you can get the guarantee at compile-time that your links are valid.

You can now test the links by compiling the application and running the Default.aspx page.

Click on the links to test the navigation.

3 - Improving FrmCustomer

Some other attributes help you better define your query methods.

You can mark a parameter as mandatory using the ParamRequired attribute. This can be used with parameters that are not value types, such as String. Value types are always required because they cannot be null.

If no value is provided for a parameter marked as required or value type, an exception is raised.

The ParamName attribute can be used, in case you wish to specify the name used in the URL for a parameter, allowing parameter aliasing:

Now, the old custID parameter is changed to CustomerID in the links to this method.

For some types of parameters, a format string can be used. This is the case for data types implementing the IFormattable interface. IFormattable is implemented by the base data types, such as System.DateTime, System.Int32, or System.Guid. The ParamFormat attribute can be used to format a parameter.

Here we wish the parameter to be formatted on four digits.
Learn more about formats and format strings on MSDN.

4 - ListCustomer

The ListCustomer page contains a list of the customers.

Create a new page named ListCustomer.aspx.

Add a DataList control to the page.

Customize the DataList by editing the Item template.

An a HyperLink control to the ItemTemplate.

We will bind the DataList to a typed DataSet.
We need to create that DataSet:

Now, let's simulate some data coming from a database:

Add an event handler for the ItemDataBound event of the DataList.

This can also be done using databinding on the HyperLink instead. But again, we would not have the full benefits.

You can now test the ListCustomer page and look at the links.

More features

Base class for pages

You noticed that we added a call to PageMethodsEngine.InvokeMethod() in the code for FrmCustomer. You could put that call in a base class for your pages, or have your pages inherit from the MetaSapiens.PageMethods.BasePage class, which does just that. See the documentation about MetaSapiens.PageMethods.BasePage to learn more.

Default method

URLs managed with PageMethods have an additional parameter (named PageMethod by default) that is used to identify the target method during a page call. If there is only one method in the page or a main method, you can mark that method as the default method using [PageMethod(true)] instead of simply [PageMethod]. The result is that no additional parameter gets added to the URLs for that method.

URL formatting

If you are using URL rewriting (also called URL aliasing), you can provide PageMethods with a format string to format the URL for each method.

Let's take an example. With the following code,

a link to customer 12 would look like this: http://myserver/PageMethodsTutorial/Pages/FrmCustomer.aspx?PageMethodd=EditCustomer&CustomerID=12

Using the PageMethods.UrlFormat attribute like this,

the same link would be like that instead: http://myserver/PageMethodsTutorial/Customer12.aspx

You refer to a parameter using the {parameter name} syntax. You can refer to the method name using {{METHOD}}.

Going further

Basically, you've seen in this tutorial all that your need to know to be able to work with PageMethods.
PageMethods has more features than what is demonstrated here, but those will be explained somewhere else.

For example, if you want to see more code, you can take a look at the provided samples in C# and VB.NET.