System.Web 1.0.5000.0 2.0.0.0 Gtk# is thread aware, but not thread safe; See the <link location="node:gtk-sharp/programming/threads">Gtk# Thread Programming</link> for details. System.Web.UI.WebControls.DataBoundControl 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") In this topic: Introduction XML Advertisement File Format Declarative Syntax

Introduction

Use the 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 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 control, such as redirecting to another page. See the property for additional information on the file format. When page caching is enabled, an 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 event.

XML Advertisement File Format

The 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 property of the 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 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 and ), you can place custom elements between the <Ad> tags. These elements will be read by the control when it parses the file. The information is then passed to the event in the 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). 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 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 control throws a run-time exception. The following example 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>

Declarative Syntax

<asp:AdRotator     AccessKey="string"     AdvertisementFile="uri"     AlternateTextField="string"     BackColor="color name|#dddddd"     BorderColor="color name|#dddddd"     BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|Groove|Ridge| Inset|Outset"     BorderWidth="size"     CssClass="string"     DataMember="string"     DataSource="string"     DataSourceID="string"     Enabled="True|False"     EnableTheming="True|False"     EnableViewState="True|False"     ForeColor="color name|#dddddd"     Height="size"     ID="string"     ImageUrlField="string"     KeywordFilter="string"     NavigateUrlField="string"     OnAdCreated="AdCreated event handler"     OnDataBinding="DataBinding event handler"     OnDataBound="DataBound event handler"     OnDisposed="Disposed event handler"     OnInit="Init event handler"     OnLoad="Load event handler"     OnPreRender="PreRender event handler"     OnUnload="Unload event handler"     runat="server"     SkinID="string"     Style="string"     TabIndex="integer"     Target="string|_blank|_parent|_search|_self|_top"     ToolTip="string"     Visible="True|False"     Width="size" />

Displays an advertisement banner on a Web page.

Constructor Use this constructor to create and initialize a new instance of the class.

Initializes a new instance of the class.

1.0.5000.0 2.0.0.0 Event System.Web.UI.WebControls.AdCreatedEventHandler This event is raised once per round trip to the server after the creation of the control, but before the page is rendered. When the property is set, this event occurs after the advertisement has been selected from the file. You can control how the control is displayed by modifying the arguments passed to the event handler of the event. If the property is not set, this allows you to specify the advertisement information directly, without using a separate advertisement file. If the property is set, this allows you to extend the behavior of the control, such as redirecting to another page. When page caching is enabled, an 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 event. For more information about handling events, see Handling and Raising Events.

Occurs once per round trip to the server after the creation of the control, but before the page is rendered.

1.0.5000.0 2.0.0.0 Property System.String To be added: an object of type 'string' Use the property to specify the location of an XML file that contains advertisement information. The XML file must reside within the same Web site. For deployment and security purposes, it is strongly recommended that you place the file in the same Web application. It is only possible to access an XML file that is located in a different application on the same site if the application has sufficient trust. You can set this property to either an absolute path or a path relative to the XML file. Use a relative path to simplify deployment. If you use a relative path, that path is relative to the location of the page or user control that contains the control. The property is optional. An advertisement can also be programmatically set in the event. The XML file contains the following predefined attributes. Only the ImageUrl attribute is required. Attribute Description ImageUrl The URL of the image to display. Height The height of the image, in pixels (optional). Width The width of the image, in pixels (optional). NavigateUrl The URL of the page to navigate to when the control is clicked. AlternateText The text to display if the image is unavailable. On some browsers, this text is displayed as a ToolTip. Keyword The category for the advertisement. This is used by the control to filter the list of advertisements for a specific category. Impressions A value that indicates how often an advertisement is displayed in relation to other advertisements in the XML file. The ImageUrl and NavigateUrl attributes can be a full URL, a root-relative path, or a relative path. If you use a root-relative path, the path is relative to the same Web site. If you use a relative path, the path is relative to the directory that contains the advertisement file. You can also include custom attributes by using custom tags in the XML file. All attribute tags are parsed from the advertisement file, and the values are placed in the dictionary. You can use the dictionary to programmatically access your custom attributes. Information in this file is not validated by the 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 Data directory, which is configured in Machine.config to deny Internet access for files of any type. Rename the file with an extension that is not .xml, and map the extension to HttpForbiddenHandler in Web.config. For more information, see the httpHandlers section in your Machine.config file.

Gets or sets the path to an XML file that contains advertisement information.

1.0.5000.0 2.0.0.0 System.ComponentModel.Editor("System.Web.UI.Design.XmlUrlEditor, System.Design, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a", typeof(System.Drawing.Design.UITypeEditor)) System.ComponentModel.DefaultValue("") System.ComponentModel.Bindable(true) System.Web.UI.UrlProperty Property 2.0.0.0 System.ComponentModel.DefaultValue("AlternateText") System.String To be added. The property is used to select a custom data field to use in place of the AlternateText attribute for an advertisement. Like AlternateText, this custom field is defined in the XML file that contains advertisement information.

Gets or sets a custom data field to use in place of the AlternateText attribute for an advertisement.

Property System.Web.UI.WebControls.FontInfo a To be added

Gets the font properties associated with the advertisement banner control.

1.0.5000.0 2.0.0.0 System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Never) System.ComponentModel.DesignerSerializationVisibility(System.ComponentModel.DesignerSerializationVisibility.Hidden) System.ComponentModel.Browsable(false) Property 2.0.0.0 System.ComponentModel.DefaultValue("ImageUrl") System.String To be added. The property is used for selecting a custom data field used in place of the ImageUrl attribute for an advertisement. Like ImageUrl, this custom field is defined in the XML file that contains advertisement information.

Gets or sets a custom data field to use in place of the ImageUrl attribute for an advertisement.

Property System.String To be added: an object of type 'string' Each advertisement in the XML advertisement file can be assigned a category keyword. Use the property to filter the advertisements for the specified keyword. Only advertisements containing the keyword will be selected for the control. The property can be programmatically set to match the profile of the user. The property is a very simple filter that searches for the specified keyword. It is not possible to specify more than one keyword in the property, nor is it possible to declare multiple keywords in the advertisement file. The property needs to be set for this property to have any effect. If the specified keyword is not found in the XML advertisement file, no advertisement is displayed in the control. Be sure to specify a keyword for this property with at least one match in the advertisement file.

Gets or sets a category keyword to filter for specific types of advertisements in the XML advertisement file.

1.0.5000.0 2.0.0.0 System.ComponentModel.DefaultValue("") System.ComponentModel.Bindable(true) Property 2.0.0.0 System.ComponentModel.DefaultValue("NavigateUrl") System.String To be added. The property is used to select a custom data field used in place of the NavigateUrl attribute for an advertisement. Like NavigateUrl, this custom field is defined in the XML file that contains advertisement information.

Gets or sets a custom data field to use in place of the NavigateUrl attribute for an advertisement.

Method System.Void The event is raised on the server after the control is created, but before the page is rendered. If the property is set, the event is raised after an advertisement has been selected by the control. Raising an event invokes the event-handling method through a delegate. For more information, see How to: Consume Events in a Web Forms Application.

Raises the event for the control.

An that contains event data. 1.0.5000.0 2.0.0.0 Method 2.0.0.0 System.Void To be added.

Raises the event.

The event arguments. Method System.Void a To be added

Gets the advertisement information for rendering by looking up the file data or calling the user event.

1.0.5000.0 2.0.0.0 Method 2.0.0.0 System.Void This method is used primarily by control developers. The method is called by the base class methods to bind the advertisement data from a data source to the control.

Binds the specified data source to the control.

An object that represents the data source; the object must implement the interface. Method 2.0.0.0 System.Void This method is used primarily by control developers. The method for an object retrieves the advertisement data from the , and then calls the and methods. If the property is not set, then the method calls the method of the base class.

Retrieves the advertisement data from the associated data source.

Method System.Void a Displays an image obtained from the advertisement chosen in .

Displays the control on the client.

1.0.5000.0 2.0.0.0 Property 1.0.5000.0 2.0.0.0 System.Web.UI.HtmlTextWriterTag To be added. This property is used primarily by control developers. Use the property to determine the value associated with an control. This property overrides the base implementation to always return .

Gets the HTML tag for the control.

Property System.String To be added: an object of type 'string' Use the property to specify the target window or frame that displays the contents of the Web page linked to when the control is clicked. The property renders as a target attribute . The target attribute on anchor (a) elements is not allowed in XHTML 1.1. Therefore, if rendered markup must conform to XHTML standards or must conform to accessibility standards, do not set the property. For more information, see XHTML Standards in Visual Studio 2010 and ASP.NET 4 and Accessibility in Visual Studio 2010 and ASP.NET 4. The value must begin with a letter in the range of A to Z (case-insensitive), except for the following special values, which begin with an underscore. Target value Description _blank Renders the content in a new window without frames. _parent Renders the content in the immediate frameset parent. _search Renders the content in the search pane. _self Renders the content in the frame with focus. _top Renders the content in the full window without frames. Check your browser documentation to determine whether the _search value is supported. For example, Internet Explorer 5.0 or later supports the _search target value.

Gets or sets the name of the browser window or frame that displays the contents of the Web page linked to when the control is clicked.

1.0.5000.0 2.0.0.0 System.ComponentModel.TypeConverter(typeof(System.Web.UI.WebControls.TargetConverter)) System.ComponentModel.DefaultValue("_top") System.ComponentModel.Bindable(true) Property 1.0.5000.0 2.0.0.0 System.String To be added. This property differs from the property in that the property includes the identifier for the server control's naming container. This identifier is generated automatically when a page request is processed.

Gets the unique, hierarchically qualified identifier for the control.