Tutorial for Visual Studio 2005

This tutorial demonstrates the use of PageMethods for VS 2005 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 Site or Web Application named PageMethodsTutorial.

Here is how to create a new Web Site (File | New | Web Site...):

Here is how to create a new Web Application project (File | New | Project... | ASP.NET Web Application):

Add a new web form 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 2.0. 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.

Register PageMethods' custom build provider in the configuration file (this is NOT needed for a Web Application project):

<?xml version="1.0"?>
<configuration >

<appSettings />

<system.web>
    <compilation debug="true">
      <buildProviders>
        <add
            extension=".xml"
            type="MetaSapiens.PageMethods.PageMethodsBuildProvider, PageMethods" />
      </buildProviders>
    </compilation>
</system.web>

</configuration>

Of course, you need to add a Web Configuration File (Web.config if your project does not already have one. If you already have an existing web.config file, make sure you put the extra data in the right place (under system.web/compilation).

Compile to have PageMethods generate its magic code.

You won't see the generated code, but you may find the PageList.xml file located in the App_Code folder of the project. It is important that you never touch this file and leave it as is. PageMethods will manage it 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 will use code-behind to take advantage of compile-time checks. This way we can be sure before deployment that the links we use are valid.

We will test this in the Default.aspx page.

Add a HyperLink control to the page.

Then set the HyperLink control's NavigateUrl as follows:

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 link by running the Default.aspx page.

If you are not using Internet Explorer, you should deactivate the NTLM Authentication option in the project properties before.

Click on the link 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:

Note that we do not need any connection or TableAdapter, but only a DataTable named Customer, with three fields: CustID (System.Int32), Name (System.String), Country (System.String).

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 we would not have the full benefits and so we do not recommend it.

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?PageMethod=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.