Classe GenericWebPart

Il controllo GenericWebPart fornisce un wrapper in fase di esecuzione per i controlli server che non sono controlli WebPart, in modo che tali controlli possano essere utilizzati in applicazioni e pagine Web part. Quando gli sviluppatori aggiungono controlli server, ad esempio controlli utente, controlli server ASP.NET o controlli personalizzati esistenti, a un controllo WebPartZoneBase, il controllo GenericWebPart esegue automaticamente il wrapping dei controlli server in fase di esecuzione, in modo che possano presentare le stesse funzionalità dei veri controlli WebPart.

Nella tabella riportata di seguito vengono confrontati i controlli GenericWebPart e WebPart.

Gli utenti traggono vantaggio dal controllo GenericWebPart in quanto fornisce un'esperienza uniforme. È possibile impostare qualsiasi controllo server in modo che funzioni come un controllo WebPart e disponga degli stessi elementi coerenti dell'interfaccia utente, quali verbi, icone, un titolo e un'intestazione. Gli sviluppatori traggono vantaggio dal controllo GenericWebPart in quanto consente di riutilizzare i controlli utente e i controlli server esistenti all'interno di applicazioni Web part.

Nota

Quando si creano pagine Web part, non è necessario effettuare alcuna operazione per consentire il wrapping di un controllo utente o di un controllo personalizzato esistente con il controllo GenericWebPart. È sufficiente aggiungere il controllo server o utente in una zona WebPartZoneBase, a livello di codice oppure dichiarandolo nel markup della pagina. Il set dei controlli Web part esegue automaticamente il wrapping del controllo con un oggetto GenericWebPart in fase di esecuzione.

Poiché viene eseguito il wrapping dei controlli server inseriti nelle zone WebPartZoneBase con un controllo GenericWebPart in fase di esecuzione, gli sviluppatori possono utilizzare controlli server e utente normali come se si trattasse di controlli WebPart. Se si dichiarano controlli personalizzati che ereditano dalla classe base Control nell'ambito di una classe WebPartZone, tali controlli non supportano l'uso delle proprietà del controllo WebPart intrinseche. Non sarà quindi possibile dichiarare le proprietà di IWebPart per tali controlli, comprese proprietà quali Title e Description. Al contrario, altri tipi di controlli server, ad esempio i controlli WebPart, i controlli utente e i controlli personalizzati che ereditano dalla classe WebControl, sono in grado di dichiarare queste proprietà perché supportano l'uso delle proprietà expando.

Le proprietà expando sono in realtà stringhe che possono essere aggiunte dinamicamente a una classe come proprietà mediante l'interfaccia IAttributeAccessor. I controlli che implementano questa interfaccia, tra cui la classe WebControl e le relative classi figlio, possono utilizzare le proprietà expando. Poiché la classe base Control non supporta le proprietà expando, quando si inserisce un controllo personalizzato che eredita dalla classe Control in una classe WebPartZone e se ne esegue il wrapping con un controllo GenericWebPart in fase di esecuzione, il controllo Web part impostato non è in grado di aggiungere dinamicamente le proprietà di IWebPart intrinseche al controllo personalizzato. In questo caso sono disponibili due opzioni. È possibile utilizzare il controllo personalizzato senza le proprietà di IWebPart oppure implementare l'interfaccia IWebPart nel controllo personalizzato per consentire l'uso delle proprietà.

Come esempio di utilizzo delle proprietà di IWebPart da parte di controlli che ereditano dalla classe WebControl considerare la situazione in cui si dichiara un controllo Calendar ASP.NET nel markup di una pagina (all'interno di una zona WebPartZoneBase) in fase di progettazione ed è possibile trattare il controllo esattamente come un controllo WebPart, anche se il controllo non eredita dalla classe WebPart e non contiene membri WebPart a livello nativo. È possibile dichiarare proprietà WebPart per il controllo calendario, ad esempio Title, Description e altre. In fase di esecuzione è possibile utilizzare il metodo GetGenericWebPart, che restituisce il controllo GenericWebPart che esegue dinamicamente il wrapping del controllo calendario, e utilizzarlo a livello di codice come se si trattasse di un controllo WebPart, con l'accesso alle stesse proprietà, agli stessi eventi e agli stessi metodi.

Il controllo GenericWebPart comprende una proprietà critica che consente di accedere al relativo controllo server sottostante, ovvero la proprietà ChildControl, Tale proprietà permette infatti agli sviluppatori di accedere a livello di codice al controllo server. La proprietà ChildControl viene inoltre utilizzata dal controllo WebPartManager per l'accesso ai dati sulla personalizzazione del controllo figlio, nonché per eseguire l'autorizzazione, se la proprietà AuthorizationFilter è impostata.

Il controllo GenericWebPart comprende diverse altre proprietà, che eseguono tutte l'override delle proprietà ereditate dalla classe base WebPart. È possibile utilizzare queste proprietà con qualsiasi controllo figlio, in modo che possa comportarsi come un controllo WebPart. La proprietà ExportMode è particolarmente importante, in quanto determina se è possibile esportare tutte le proprietà esportabili oppure solo quelle contrassegnate come non sensibili. Le proprietà orientate all'interfaccia utente ereditate dalla classe WebPart, ad esempio CatalogIconImageUrl, Description, Height, Title, TitleUrl e Width, possono essere impostate nel markup dichiarativo per qualsiasi controllo server inserito in una zona WebPartZoneBase.

I metodi importanti nella classe GenericWebPart comprendono il metodo CreateControlCollection, che crea l'insieme di controlli (compresi i controlli figlio) associati a un controllo GenericWebPart, e il metodo Render, che delega tutto il rendering ai controlli figlio di cui è stato eseguito il wrapping. I costruttori sulla classe GenericWebPart sono protetti e sono progettati per utilizzo interno o per scenari di estensibilità.

Di seguito sono riportate ulteriori informazioni utili sull'utilizzo dei controlli GenericWebPart. Se si desidera impostare i valori predefiniti per le proprietà sottoposte a override nella classe GenericWebPart, il controllo utente o il controllo server personalizzato può implementare le interfacce di IWebPart e IWebActionable ed eseguire l'override dei relativi membri. In fase di esecuzione il controllo GenericWebPart otterrà i valori per le proprietà implementate dal controllo figlio che implementa le interfacce. Se il controllo definisce una delle proprie proprietà come personalizzabile (utilizzando l'attributo dei metadati Personalizable), il controllo GenericWebPart abilita automaticamente tali proprietà per la personalizzazione in fase di esecuzione, in modo analogo alle proprietà personalizzabili di un controllo WebPart.

Se si desidera fornire funzionalità di modifica di Web part per il controllo, è possibile implementare l'interfaccia di IWebEditable. In fase di esecuzione quando viene chiamato il metodo CreateEditorParts, il codice del controllo GenericWebPart per la proprietà WebBrowsableObject chiamerà la stessa proprietà nel controllo figlio e utilizzerà l'implementazione del controllo figlio per creare controlli EditorPart personalizzati associati.

in alcune circostanze è necessario ereditare dalla classe GenericWebPart, ad esempio se uno sviluppatore desidera implementare alcune operazioni personalizzate nel costruttore durante la creazione di un controllo GenericWebPart. Si potrebbe decidere, ad esempio, di archiviare il controllo figlio in un punto diverso dall'insieme di controlli all'interno della classe GenericWebPart. Se si eredita dalla classe GenericWebPart, è necessario ereditare anche dalla classe WebPartManager ed eseguire l'override del relativo metodo CreateWebPart per consentire la creazione del controllo personalizzato.

Nell'esempio di codice riportato di seguito il controllo GenericWebPart esegue automaticamente il wrapping di un controllo server che non è un controllo WebPart in fase di esecuzione.

La prima parte dell'esempio di codice contiene una pagina Web part con due controlli WebPartZone. All'interno di ciascuna zona è presente un controllo server ASP.NET standard. Poiché i controlli si trovano in una zona WebPartZone, di questi verrà automaticamente eseguito il wrapping con un controllo GenericWebPart durante la compilazione della pagina. È quindi possibile dichiarare le proprietà della classe WebPart su questi controlli. Se dopo il caricamento della pagina in un browser si fa clic sul pulsante Display All Property Values, verranno visualizzati i dettagli relativi a ciascun controllo in un'etichetta. Per dimostrare il funzionamento del controllo GenericWebPart, il controllo Calendar nella prima zona presenta alcune delle proprietà GenericWebPart impostate nel markup dichiarativo della pagina ASPX, a differenza del controllo BulletedList. Dopo il caricamento della pagina, si notino le differenze nei valori delle proprietà per i due controlli e si osservi che entrambi dispongono di un controllo GenericWebPart padre.

<%@ Page Language="C#" 
  Codefile="genericwebpart.cs" 
  Inherits="genericwebpart_sample" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>GenericWebPart Example</title>
</head>
<body>
    <form id="form1" runat="server">
      <asp:WebPartManager ID="WebPartManager1" runat="server">
      </asp:WebPartManager>
      <asp:WebPartZone ID="WebPartZone1" runat="server">
        <ZoneTemplate>
          <asp:Calendar ID="Calendar1" runat="server"
            Title="My Calendar"
            Description="A calendar used as a GenericWebPart control."
            CatalogIconImageUrl="MyCatalogIcon.gif"
            TitleIconimageUrl ="MyTitleIcon.gif"
            TitleUrl="MyInfoUrl.htm" 
            Width="250"/>
        </ZoneTemplate>
      </asp:WebPartZone>
      <asp:WebPartZone ID="WebPartZone2" runat="server">
        <ZoneTemplate>
          <asp:BulletedList ID="BulletedList1" 
            Runat="server"
            DisplayMode="HyperLink">
            <asp:ListItem Value="http://msdn.microsoft.com">
              MSDN
            </asp:ListItem>
            <asp:ListItem Value="http://www.asp.net">
              ASP.NET
            </asp:ListItem>
            <asp:ListItem Value="http://www.msn.com">
              MSN
            </asp:ListItem>
          </asp:BulletedList>        
        </ZoneTemplate>
      </asp:WebPartZone>
      <hr />
      <asp:Button ID="Button1" width="200"
        runat="server" 
        Text="Display All Property Values" OnClick="Button1_Click" /> 
      <br />
      <asp:Label ID="Label2" runat="server" Text="" />
      <br />   
      <asp:Label ID="Label3" runat="server" Text="" />
    </form>
</body>
</html>

Nella seconda parte dell'esempio di codice viene illustrata una classe parziale che accede ad alcune delle proprietà del controllo GenericWebPart a livello di codice. Nel metodo Page_Load viene utilizzato il metodo GetGenericWebPart per recuperare l'istanza in fase di esecuzione del controllo GenericWebPart che esegue il wrapping di un controllo server. L'approccio che prevede di ottenere un riferimento al controllo GenericWebPart padre consente di utilizzare un controllo server o utente ordinario a livello di codice come se si trattasse di un controllo WebPart in fase di esecuzione.

using System;
using System.Data;
using System.Configuration;
using System.Web;
using System.Web.Security;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Web.UI.HtmlControls;

public partial class genericwebpart_sample : System.Web.UI.Page
{
  GenericWebPart calendarPart;
  GenericWebPart listPart;

  protected void Page_Load(Object sender, EventArgs e)
  {
    calendarPart = WebPartManager1.GetGenericWebPart(Calendar1);
    listPart = WebPartManager1.GetGenericWebPart(BulletedList1);

    if (!IsPostBack)
    {
      Label2.Text = String.Empty;
      Label3.Text = String.Empty;
    }
  }

  protected void Button1_Click(object sender, EventArgs e)
  {

    Label2.Text =
      @"<h3>Calendar GenericWebPart Properties</h3>" +
      "<em>Title: </em>" + calendarPart.Title +
      "<br />" +
      "<em>CatalogIconImageUrl:  </em>" + calendarPart.CatalogIconImageUrl +
      "<br />" +
      "<em>TitleUrl: </em>" + calendarPart.TitleUrl +
      "<br />" +
      "<em>Decription: </em>" + calendarPart.Description +
      "<br />" +
      "<em>TitleIconImageUrl: </em>" + calendarPart.TitleIconImageUrl +
      "<br />" +
      "<em>ChildControl ID: </em>" + calendarPart.ChildControl.ID +
      "<br />" +
      "<em>ChildControl Type: </em>" + calendarPart.ChildControl.GetType().Name +
      "<br />" +
      "<em>GenericWebPart ID: </em>" + calendarPart.ID +
      "<br />" +
      "<em>GenericWebPart Type: </em>" + calendarPart.GetType().Name +
      "<br />" +
      "<em>GenericWebPart Parent ID: </em>" + calendarPart.Parent.ID;

    Label3.Text =
      @"<h3>BulletedList GenericWebPart Properties</h3>" +
      "<em>Title: </em>" + listPart.Title +
      "<br />" +
      "<em>CatalogIconImageUrl:  </em>" + listPart.CatalogIconImageUrl +
      "<br />" +
      "<em>TitleUrl: </em>" + listPart.TitleUrl +
      "<br />" +
      "<em>Decription: </em>" + listPart.Description +
      "<br />" +
      "<em>TitleIconImageUrl: </em>" + listPart.TitleIconImageUrl +
      "<br />" +
      "<em>ChildControl ID: </em>" + listPart.ChildControl.ID +
      "<br />" +
      "<em>ChildControl Type: </em>" + listPart.ChildControl.GetType().Name +
      "<br />" +
      "<em>GenericWebPart ID: </em>" + listPart.ID +
      "<br />" +
      "<em>GenericWebPart Type: </em>" + listPart.GetType().Name +
      "<br />" +
      "<em>GenericWebPart Parent ID: </em>" + listPart.Parent.ID;
  }

}

.NET Framework

Windows 7, Windows Vista SP1 o versione successiva, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (componenti di base del server non supportati), Windows Server 2008 R2 (componenti di base del server supportati con SP1 o versione successiva), Windows Server 2003 SP2

Riferimenti

Altre risorse