AdRotator Class

Displays an advertisement banner on a Web page.

Syntax

[System.Web.UI.ToolboxData("<{0}:AdRotator runat="server"></{0}:AdRotator>")]
[System.ComponentModel.Designer("System.Web.UI.Design.WebControls.AdRotatorDesigner, System.Design, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a", "System.ComponentModel.Design.IDesigner")]
[System.ComponentModel.DefaultProperty("AdvertisementFile")]
[System.ComponentModel.DefaultEvent("AdCreated")]
public class AdRotator : DataBoundControl

Remarks

In this topic:

Introduction
XML Advertisement File Format
Declarative Syntax

Introduction

Use the System.Web.UI.WebControls.AdRotator control to display a randomly selected advertisement banner on the Web page. The displayed advertisement changes whenever the page refreshes.

Advertisement information is stored in a separate XML file. The XML file allows you to maintain a list of advertisements and their associated attributes. Attributes include the path to an image to display, the URL to link to when the control is clicked, the alternate text to display when the image is not available, a keyword, and the frequency of the advertisement. Information in this file is not validated by the System.Web.UI.WebControls.AdRotator control. To prevent ads from executing malicious scripts, you should always check the data before releasing it, or accept ad information only from trusted sources.

To secure your advertisement file from unauthorized Internet access, do one or more of the following:

Store it in the App_Data directory, which is configured to deny Internet access for files of any type.
Rename the file with an extension that is not .xml, and map the extension to the HttpForbiddenHandler in Web.config. For more information, see the httpHandlers section in your Machine.config file.

As an alternative to an XML file as the source of data, it is possible to provide advertisement information through a callback event. This event can also be used in combination with the XML file to extend the behavior of the System.Web.UI.WebControls.AdRotator control, such as redirecting to another page. See the AdRotator.AdvertisementFile property for additional information on the file format.

Note:

When page caching is enabled, an System.Web.UI.WebControls.AdRotator control is not cached. A new advertisement is selected whenever the Web page refreshes. A new advertisement is not selected, however, if you provide an event handler for the AdRotator.AdCreated event.

XML Advertisement File Format

The System.Web.UI.WebControls.AdRotator control uses a separate XML advertisement file to store the advertisement information, such as the location of the image to display and the URL of the page to link to. The AdRotator.AdvertisementFile property of the System.Web.UI.WebControls.AdRotator control specifies the path to this file.

When creating the advertisement file, opening and closing <Advertisements> tags mark the beginning and the end of the file, respectively. Opening and closing <Ad> tags delimit each advertisement. All advertisements are nested between the opening and closing <Advertisements> tags. If the file contains multiple <Advertisements> tags, only the first set of <Advertisements> tags in the file will be parsed by the System.Web.UI.WebControls.AdRotator control. All other <Advertisements> tags will be ignored.

The data elements for each advertisement are nested between the opening and closing <Ad> tags. Although certain data elements are predefined (such as AdCreatedEventArgs.ImageUrl and AdCreatedEventArgs.NavigateUrl), you can place custom elements between the <Ad> tags. These elements will be read by the System.Web.UI.WebControls.AdRotator control when it parses the file. The information is then passed to the AdRotator.AdCreated event in the AdCreatedEventArgs.AdProperties dictionary property.

The following table lists the data elements that are predefined for the XML advertisement file.


ImageUrl	The absolute or relative URL to an image file (optional).
NavigateUrl	The URL of a page to link to if the user clicks the ad (optional). If this element is not set, the HRef property is not rendered on the anchor tag.
Height	The height of the image, in pixels (optional).
Width	The width of the image, in pixels (optional).
AlternateText	The text display in place of the image when the image specified by the AdCreatedEventArgs.ImageUrl property is not available (optional). In some browsers, this text also appears as a ToolTip for the advertisement.
Keyword	A category for the advertisement (for example, "computers") that you can filter by (optional).
Impressions	A number that indicates the importance of the ad in the schedule of rotation relative to the other ads in the file (optional). The larger the number, the more often the ad is displayed. The total of all <Impressions> values in the XML file cannot exceed 2,047,999,999. If it does, the System.Web.UI.WebControls.AdRotator control throws a run-time exception.

The following example shows the format for the XML advertisement file.

Example

<Advertisements>
  <Ad>
    <ImageUrl>
      URL of image to display for Advertisement #1
    </ImageUrl>
    <NavigateUrl>
      URL of page to link to for Advertisement #1
    </NavigateUrl>
    <AlternateText>
      Text to show as a ToolTip for Advertisement #1
    </AlternateText>
    <Keyword>
      Keyword used to filter for Advertisement #1
    </Keyword>
    <Impressions>
       Relative importance of Advertisement #1
    </Impressions>
    <CustomInformation>
      Custom Data about Advertisement #1
    </CustomInformation>
  </Ad>
</Advertisements>

Declarative Syntax

Example

<asp:AdRotator
    AccessKey="string"
    AdvertisementFile="uri"
    AlternateTextField="string"
    BackColor="color name|#dddddd"
    BorderColor="color name|#dddddd"
    BorderStyle="

Requirements

Namespace: System.Web.UI.WebControls
Assembly: System.Web (in System.Web.dll)
Assembly Versions: 1.0.5000.0, 2.0.0.0