Share via

AdRotator Web Server Control

  • Article

Displays an advertisement banner on a Web Forms page.

<asp:AdRotator
     id="Value"
     AdvertisementFile="AdvertisementFile"
     KeyWordFilter="KeyWord"
     Target="Target"
     OnAdCreated="OnAdCreatedMethod"
     runat="server"/>

The 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 AdvertisementFile property of the 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 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 ImageUrl and NavigateURL), you can place custom elements between the <Ad> tags. These elements will be read by the AdRotator control when it parses the file. The information is then passed to the AdCreated event in the AdProperties dictionary property.

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

Element Description
<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).
Note   If this element is not set, the HRef property is not rendered on the anchor tag.
<AlternateText> The text display in place of the image when the image specified by the 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 AdRotator throws a run-time exception.

The following shows the format for the XML advertisement file.

<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>

Remarks

The AdRotator control displays an advertisement banner on a Web Forms page. It displays the image specified by the ImageUrl element within an anchor control. At run time, the AdRotator control uses <asp:HyperLink> and <asp:Image> controls to render the control on the Web Forms page. The source image is sized by the browser to the dimensions of the AdRotator control, regardless of its actual size.

If the AdvertisementFile property is set, an advertisement is selected based on the value of the Impressions property from the file. The event arguments are then set and the AdCreated event is raised. If the AdvertisementFile property is not set, the event arguments are empty when the AdCreated event is raised. The event arguments are used to render the AdRotator control, so you can modify the values passed to the event from the advertisement file, or set them with values you generate yourself. A common scenario is to populate the event arguments with values retrieved from a database.

When you create an advertisement file, consider the following points:

  • The XML in the advertisement file must be well formed.
  • Only the first <Advertisements> element in the file is parsed by the AdRotator control. All other <Advertisements> elements within the file are ignored.
  • You can add custom elements to the XML description of an advertisement. These values are passed to the AdCreated event in the AdProperties dictionary property.

You can use the AdCreated event to select the advertisements directly in your code or to modify the rendering of an ad selected from the advertisement file. If an advertisement file is set, the arguments to the AdCreated event are already set to the selected ad when the event is called. Whether or not the values are already set, you can modify the values in the ImageUrl, NavigateURL, and AlternateText properties to modify the rendering of the AdRotator control. Custom elements added to the XML description of the advertisement are available in the AdCreatedEventArgs.AdProperties dictionary property.

For detailed information on the AdRotator control's properties and events, see the AdRotator Class documentation.

Example

The following example demonstrates how to declare an AdRotator control in an .aspx file.

<html>
 
   <head>
   </head>
 
<body>
   <form runat="server">
 
      <h3>AdRotator Example</h3>
 
      <asp:AdRotator id="AdRotator1"
           Target="_self"
           AdvertisementFile="Ads.xml"
           runat="server"/>
 
   </form>
</body>
 
</html>

The following example demonstrates how to create an event handler for the AdCreated event to programmatically override the value of the NavigateURL property.

<%@ Page Language="VB" AutoEventWireup="True" %>

<html>
<head>

   <script runat="server">
   
      Sub AdCreated_Event(sender As Object, e As AdCreatedEventArgs) 

         e.NavigateURL = "https://www.microsoft.com"   
       
      End Sub      

   </script>
 
</head>
 
<body>
 
   <form runat="server">
 
      <h3>AdRotator Example</h3>
 
      <asp:AdRotator id="AdRotator1" runat="server"
           AdvertisementFile = "Ads.xml"
           Target="_newwwindow"
           OnAdCreated="AdCreated_Event"/>
 
   </form>
 
</body>
</html>
[C#]
<%@ Page Language="C#" AutoEventWireup="True" %>

<html>
<head>

   <script runat="server">
   
      void AdCreated_Event(Object sender, AdCreatedEventArgs e) 
      {

         e.NavigateURL = "https://www.microsoft.com";   
       
      }      

   </script>
 
</head>
 
<body>
 
   <form runat="server">
 
      <h3>AdRotator Example</h3>
 
      <asp:AdRotator id="AdRotator1" runat="server"
           AdvertisementFile = "Ads.xml"
           Target="_newwwindow"
           OnAdCreated="AdCreated_Event"/>
 
   </form>
 
</body>
</html>

The following example demonstrates how to format an XML advertisement file.

<Advertisements>
 
   <Ad>
      <ImageUrl>image1.jpg</ImageUrl>
      <NavigateURL>https://www.microsoft.com</NavigateURL>
      <AlternateText>Microsoft Main Site</AlternateText>
      <Impressions>80</Impressions>
      <Keyword>Topic1</Keyword>
      <Caption>This is the caption for Ad#1</Caption> 
   </Ad>
 
   <Ad>
      <ImageUrl>image2.jpg</ImageUrl>
      <NavigateURL>http://www.wingtiptoys.com</NavigateURL>
      <AlternateText>Wing Tip Toys</AlternateText>
      <Impressions>80</Impressions>
      <Keyword>Topic2</Keyword>
      <Caption>This is the caption for Ad#2</Caption> 
   </Ad>
 
</Advertisements>

See Also

Web Server Controls | AdRotator Class