Procedura dettagliata: sviluppo e utilizzo di un controllo server personalizzato

Articolo
09/12/2008

Aggiornamento: novembre 2007

In questa procedura dettagliata viene illustrato come creare e compilare un controllo server ASP.NET e utilizzarlo in una pagina.

In particolare, vengono illustrate le seguenti operazioni:

Creare un controllo server ASP.NET.
Aggiungere metadati al controllo e ai suoi membri per controllarne la sicurezza e il comportamento in fase di progettazione.
Utilizzare la directory App_Code in un sito Web ASP.NET per sottoporre il controllo personalizzato a test senza effettuare passaggi di compilazione manuale.
Specificare un prefisso di tag in un file di configurazione e nell'assembly del controllo.
Compilare il controllo in un assembly e aggiungerlo alla directory Bin.
Incorporare una bitmap nell'assembly del controllo da utilizzare come icona nella casella degli strumenti di una finestra di progettazione visiva.
Utilizzare il controllo compilato in una pagina.

A visual design tool such as Microsoft Visual Studio 2005 simplifies control development but is not essential for creating or building custom controls. You can create your controls using any text editor and build them from the command line using the compilers that are part of the Windows Software Development Kit (SDK). Indipendentemente dal metodo utilizzato per creare i controlli personalizzati, il loro aspetto e comportamento in fase di progettazione in una finestra di progettazione visiva non varia. Lo sviluppatore di pagine potrà aggiungere il controllo personalizzato alla casella degli strumenti della finestra di progettazione visiva, trascinarlo nell'area di progettazione e accedere alle proprietà e agli eventi del controllo dal Visualizzatore proprietà. In some visual designers such as Visual Studio 2005, a custom control also has IntelliSense support without any work on your part.

Creazione del controllo server

Il controllo creato, WelcomeLabel, è un controllo semplice simile al controllo Label standard. La classe WelcomeLabel è derivata da WebControl e in essa è definita una proprietà, Text, che consente allo sviluppatore di creare una stringa di testo contenente un messaggio di benvenuto all'utente. Se il nome dell'utente è presente nell'intestazione inviata dal browser, WelcomeLabel lo aggiungerà alla stringa. Per ulteriori informazioni su come recuperare il nome utente, vedere User. Ad esempio, se lo sviluppatore imposta "Benvenuto" come valore della proprietà Text, WelcomeLabel restituirà il valore "Benvenuto, userName!" oppure "Benvenuto!", a seconda che il nome utente sia presente o meno nell'intestazione.

Per creare il codice per il controllo server personalizzato

Creare un file denominato WelcomeLabel.cs o WelcomeLabel.vb.

Aggiungere il seguente codice al file di origine del controllo:

' WelcomeLabel.vb
Option Strict On
Imports System
Imports System.ComponentModel
Imports System.Security.Permissions
Imports System.Web
Imports System.Web.UI
Imports System.Web.UI.WebControls

Namespace Samples.AspNet.VB.Controls
    < _
    AspNetHostingPermission(SecurityAction.Demand, _
        Level:=AspNetHostingPermissionLevel.Minimal), _
    AspNetHostingPermission(SecurityAction.InheritanceDemand, _
        Level:=AspNetHostingPermissionLevel.Minimal), _
    DefaultProperty("Text"), _
    ToolboxData( _
        "<{0}:WelcomeLabel runat=""server""> </{0}:WelcomeLabel>") _
    > _
    Public Class WelcomeLabel
        Inherits WebControl
        < _
        Bindable(True), _
        Category("Appearance"), _
        DefaultValue(""), _
        Description("The welcome message text."), _
        Localizable(True) _
        > _
        Public Overridable Property Text() As String
            Get
                Dim s As String = CStr(ViewState("Text"))
                If s Is Nothing Then s = String.Empty
                Return s
            End Get
            Set(ByVal value As String)
                ViewState("Text") = value
            End Set
        End Property

        Protected Overrides Sub RenderContents( _
            ByVal writer As HtmlTextWriter)
            writer.WriteEncodedText(Text)
            If Context IsNot Nothing Then
                Dim s As String = Context.User.Identity.Name
                If (s IsNot Nothing) AndAlso (s <> String.Empty) Then
                    Dim split() As String = s.Split("\".ToCharArray)
                    Dim n As Integer = split.Length - 1
                    If (split(n) <> String.Empty) Then
                        writer.Write(", ")
                        writer.Write(split(n))
                    End If
                End If
            End If
            writer.Write("!")
        End Sub
    End Class
End Namespace

// WelcomeLabel.cs
using System;
using System.ComponentModel;
using System.Security.Permissions;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;

namespace Samples.AspNet.CS.Controls
{
    [
    AspNetHostingPermission(SecurityAction.Demand,
        Level = AspNetHostingPermissionLevel.Minimal),
    AspNetHostingPermission(SecurityAction.InheritanceDemand, 
        Level=AspNetHostingPermissionLevel.Minimal),
    DefaultProperty("Text"),
    ToolboxData("<{0}:WelcomeLabel runat=\"server\"> </{0}:WelcomeLabel>")
    ]
    public class WelcomeLabel : WebControl
    {
        [
        Bindable(true),
        Category("Appearance"),
        DefaultValue(""),
        Description("The welcome message text."),
        Localizable(true)
        ]
        public virtual string Text
        {
            get
            {
                string s = (string)ViewState["Text"];
                return (s == null) ? String.Empty : s;
            }
            set
            {
                ViewState["Text"] = value;
            }
        }

        protected override void RenderContents(HtmlTextWriter writer)
        {
            writer.WriteEncodedText(Text);
            if (Context != null)
            {
                string s = Context.User.Identity.Name;
                if (s != null && s != String.Empty)
                {
                    string[] split = s.Split('\\');
                    int n = split.Length - 1;
                    if (split[n] != String.Empty)
                    {
                        writer.Write(", ");
                        writer.Write(split[n]);
                    }
                }
            }
            writer.Write("!");
        }
    }
}

Illustrazione del codice

La descrizione del codice riportata di seguito non è indispensabile per eseguire i passaggi della procedura dettagliata e può essere inizialmente ignorata. Tuttavia, se non si ha esperienza nella creazione di controlli, si consiglia quantomeno di leggerla dopo aver completato la procedura dettagliata.

Se il controllo personalizzato esegue il rendering di un elemento dell'interfaccia utente o di qualsiasi altro elemento visibile sul client, è necessario derivarlo dalla classe System.Web.UI.WebControls.WebControl o da una classe derivata da quest'ultima. Se il controllo personalizzato esegue il rendering di un elemento che non è visibile nel browser client, come, ad esempio, un elemento nascosto o un elemento meta, è necessario derivarlo da System.Web.UI.Control. La classe WebControl è derivata da Control e contiene proprietà aggiuntive relative allo stile, come Font, ForeColor e BackColor. Inoltre, un controllo derivato da WebControl beneficierà delle funzionalità relative ai temi ASP.NET senza necessità di operazioni aggiuntive da parte dello sviluppatore.

Se il controllo personalizzato estende la funzionalità di un controllo esistente, come nel caso dei controlli Button, Label o Image, è possibile effettuare una derivazione da quel controllo. Poiché WelcomeLabel estende la funzionalità del controllo Label, è possibile derivarlo da Label. Tuttavia, in questa procedura dettagliata, WelcomeLabel viene derivato da WebControl per illustrare come si definisce una proprietà e i relativi metadati.

WelcomeLabel definisce un'unica proprietà, Text, e utilizza lo stato di visualizzazione per memorizzare il valore di tale proprietà. L'utilizzo dello stato di visualizzazione consente la persistenza del valore della proprietà Text durante i vari postback. Durante i postback, la pagina viene ricreata e valori vengono recuperati dallo stato di visualizzazione. Se il valore della proprietà Text non è presente nello stato di visualizzazione, in seguito a ciascun postback verrà impostato il valore predefinito Empty. La proprietà ViewState, ereditata da WebControl, è costituita da un dizionario in cui vengono salvati i valori dei dati. Tali valori sono memorizzati e recuperati utilizzando una chiave di tipo String. Nell'esempio, la chiave utilizzata è "Text". Il tipo di dati degli elementi del dizionario è Object ed è necessario eseguire il cast al tipo di dati della proprietà. Per ulteriori informazioni, consultare Cenni preliminari sulla gestione dello stato ASP.NET.

Il controllo WelcomeLabel effettua il rendering della sua proprietà Text mediante l'override del metodo RenderContents ereditato. Il parametro passato al metodo RenderContents è un oggetto di tipo HtmlTextWriter, ossia una classe di utilità in grado di eseguire il rendering di tag e di altri elementi del markup HTML (e varianti di HTML).

È da notare che, invece di concatenare le stringhe per poi richiamare il metodo Write, WelcomeLabel effettua una sequenza di chiamate al metodoWrite dell'oggetto HtmlTextWriter. In tal modo si ottengono migliori prestazioni, in quanto l'oggetto HtmlTextWriter consente di scrivere direttamente nel flusso di output. La concatenazione di stringhe richiede tempo e memoria in quanto le stringhe vengono prima create e poi scritte nel flusso. Per l'implementazione del rendering nei controlli personalizzati, si consiglia di attenersi al modello presentato in questa procedura dettagliata.

Nota:
In generale, quando un controllo personalizzato è derivato da WebControl ed esegue il rendering di un singolo elemento, è necessario eseguire l'override del metodo RenderContents (e non del metodo Render) per eseguire il rendering del contenuto dei suoi tag. Il metodo Render della classe WebControl richiama RenderContents dopo aver eseguito il rendering dei tag di apertura del controllo e dei relativi attributi di stile. Se, per la scrittura del contenuto, si effettua l'override del metodo Render, il controllo personalizzato perderà la logica di rendering dello stile, che è incorporata nel metodo Render della classe WebControl. Per ulteriori informazioni su come eseguire il rendering di un controllo derivato da WebControl, consultare Esempio di rendering di controlli Web.

In generale, quando un controllo personalizzato è derivato da WebControl ed esegue il rendering di un singolo elemento, è necessario eseguire l'override del metodo RenderContents (e non del metodo Render) per eseguire il rendering del contenuto dei suoi tag. Il metodo Render della classe WebControl richiama RenderContents dopo aver eseguito il rendering dei tag di apertura del controllo e dei relativi attributi di stile. Se, per la scrittura del contenuto, si effettua l'override del metodo Render, il controllo personalizzato perderà la logica di rendering dello stile, che è incorporata nel metodo Render della classe WebControl. Per ulteriori informazioni su come eseguire il rendering di un controllo derivato da WebControl, consultare Esempio di rendering di controlli Web.

Gli attributi applicati a WelcomeLabel contengono metadati utilizzati da Common Language Runtime e dagli strumenti della fase di progettazione.

A livello di classe, WelcomeLabel è contrassegnato dai seguenti attributi:

AspNetHostingPermissionAttribute è un attributo di sicurezza per l'accesso al codice. L'attributo consente al compilatore JIT di verificare se, quando WelcomeLabel viene richiamato, il codice che effettua la chiamata dispone del permesso AspNetHostingPermission. Tutte le classi ASP.NET pubbliche sono contrassegnate da questo attributo. È necessario applicare AspNetHostingPermissionAttribute ai controlli personalizzati come sicurezza contro i chiamanti parzialmente attendibili.
DefaultPropertyAttribute è un attributo della fase di progettazione che specifica la proprietà predefinita di un controllo. Nelle finestre di progettazione visiva, il Visualizzatore proprietà evidenzia generalmente la proprietà predefinita quando si fa clic sul controllo nell'area di progettazione.
ToolboxDataAttribute specifica la stringa di formato dell'elemento. Quando si fa doppio clic sul controllo nella casella degli strumenti o lo si trascina da questa nell'area di progettazione, la stringa verrà impiegata per la creazione del markup del controllo. Per WelcomeLabel, la stringa crea il seguente elemento:
```
<aspSample:WelcomeLabel > </aspSample:WelcomeLabel>
```

Il controllo WelcomeLabel eredita inoltre due attributi dalla classe base WebControl: ParseChildrenAttribute e PersistChildrenAttribute. Questi vengono applicati come ParseChildren(true) e PersistChildren(false). I due attributi interagiscono fra di loro e con l'attributo ToolboxDataAttribute in modo che gli elementi figlio vengano interpretati come proprietà e le proprietà vengano mantenute come attributi.

I seguenti attributi applicati alla proprietà Text di WelcomeLabel sono attributi standard della fase di progettazione che si applicano generalmente a tutte le proprietà pubbliche dei controlli personalizzati:

BindableAttribute, specificato come true o false, indica se è appropriato associare la proprietà a dati nelle finestre di progettazione visiva. For example, in Visual Studio 2005, if a property is marked with Bindable(true), the property is displayed in the DataBindings dialog box. Se la proprietà non è contrassegnata da questo attributo, il Visualizzatore proprietà utilizzerà il valore Bindable(false).
CategoryAttribute indica come categorizzare la proprietà nel Visualizzatore proprietà della finestra di progettazione visiva. Ad esempio, con Category("Appearance") il Visualizzatore proprietà visualizzerà la proprietà nella categoria Aspetto, se lo sviluppatore utilizza la visualizzazione per categorie. È possibile specificare un argomento di tipo stringa che corrisponda a una categoria esistente nel Visualizzatore proprietà, oppure creare una categoria personalizzata.
DescriptionAttribute consente di specificare una breve descrizione della proprietà. In Visual Studio 2005, the property browser displays the description of the selected property at the bottom of the Properties window.
DefaultValueAttribute consente di specificare un valore predefinito per la proprietà. Il valore deve essere uguale al valore predefinito restituito dalla funzione di accesso della proprietà (funzione Get). In Visual Studio 2005, the DefaultValueAttribute allows a page developer to reset a property value to its default by bringing up the shortcut menu in the Properties window and clicking the Reset button.

LocalizableAttribute, definito come true o false, indica se è appropriato localizzare la proprietà nelle finestre di progettazione. Se una proprietà è contrassegnata con Localizable(true), la finestra di progettazione visiva includerà la proprietà durante la serializzazione delle risorse localizzate. Quando il controllo è sottoposto al polling delle proprietà localizzabili, la finestra di progettazione mantiene il valore della proprietà nel file di risorse indipendente dalle impostazioni cultura o in un'altra risorsa localizzata.

Nota:
La proprietà LocalizableAttribute non era applicabile a controlli server personalizzati nelle versioni ASP.NET 1.0 e 1.1, in quanto in quelle versioni il modello di localizzazione di ASP.NET era diverso.

Gli attributi della fase di progettazione applicati a un controllo e ai suoi membri non hanno effetto sul funzionamento del controllo nella fase di esecuzione, ma facilitano il lavoro degli sviluppatori quando il controllo viene utilizzato in una finestra di progettazione visiva. Per un elenco completo degli attributi delle fasi di progettazione, analisi ed esecuzione per i controlli server, consultare Attributi di metadati per controlli server personalizzati.

Utilizzo della directory App_Code per testare i controlli senza compilazione

È possibile utilizzare la funzionalità di compilazione dinamica di ASP.NET per sottoporre a test il controllo personalizzato in una pagina senza compilarlo in un assembly. ASP.NET consente di compilare in modo dinamico il codice salvato nella sottodirectory App_Code della directory principale di un sito Web ASP.NET. Il tal modo, è possibile accedere alle classi definite nei file sorgente presenti nella directory App_Code direttamente dalle pagine, senza eseguirne la compilazione manuale in un assembly. Collocando i file di origine dei controlli nella directory App_Code, le modifiche apportate al codice dei controlli avranno effetto immediato nelle pagine che li utilizzano.

Nota:
La directory App_Code è una nuova funzionalità non disponibile in ASP.NET 1.0 e 1.1. L'utilizzo della directory App_Code per eseguire il test iniziale dei controlli è opzionale. I passaggi principali nella compilazione di un controllo server sono invariati rispetto alle versioni precedenti, come illustrato nella sezione successiva, "Compilazione del controllo in un assembly."

Per creare un sito Web ASP.NET e la directory App_Code

Creare un sito Web denominato ServerControlsTest. È possibile creare il sito in IIS come una directory virtuale denominata ServerControlsTest. Per informazioni dettagliate su come creare e configurare una directory virtuale in IIS, consultare Procedura: creare e configurare directory virtuali in IIS 5.0 e 6.0.
Creare la directory App_Code direttamente nella directory principale del sito Web (definita anche directory principale dell'applicazione Web).
Copiare il file di origine del controllo (WelcomeLabel.cs o WelcomeLabel.vb) nella directory App_Code.

Creazione di un prefisso di tag

Il prefisso di tag è un prefisso, ad esempio "asp" in <asp:Table /> che viene anteposto al nome del tipo del controllo quando questo viene creato in modo dichiarativo su una pagina. Per consentire l'utilizzo di un controllo in modalità dichiarativa in una pagina, ASP.NET richiede un prefisso di tag che viene mappato allo spazio dei nomi del controllo. È possibile realizzare il mapping prefisso di tag/spazio dei nomi aggiungendo una direttiva @ Register a ciascuna pagina che utilizza controllo personalizzato, come illustrato nel seguente esempio:

<%@ Register TagPrefix="aspSample" 
        Namespace="Samples.AspNet.CS.Controls"%>

[Visual Basic]

<%@ Register TagPrefix="aspSample" 
        Namespace="Samples.AspNet.VB.Controls"%>

Nota:
La direttiva @ Register in ASP.NET 2.0 è identica a quella delle versioni ASP.NET 1.0 e ASP.NET 1.1. Se si ha familiarità con la direttiva Register delle versioni precedenti di ASP.NET, si noterà che l'attributo assembly, che specifica il nome dell'assembly del controllo, manca nella direttiva Register riportata nell'esempio. Se l'attributo assembly viene omesso, l'assembly verrà compilato in modo dinamico a partire dai file di origine presenti nella directory App_Code.

La direttiva @ Register in ASP.NET 2.0 è identica a quella delle versioni ASP.NET 1.0 e ASP.NET 1.1. Se si ha familiarità con la direttiva Register delle versioni precedenti di ASP.NET, si noterà che l'attributo assembly, che specifica il nome dell'assembly del controllo, manca nella direttiva Register riportata nell'esempio. Se l'attributo assembly viene omesso, l'assembly verrà compilato in modo dinamico a partire dai file di origine presenti nella directory App_Code.

Anziché utilizzare la direttiva @ Register in ogni pagina ASPX, è possibile specificare il mapping prefisso di tag/spazio dei nomi nel file Web.config. Questa opzione risulta utile quando il controllo personalizzato è utilizzato in più pagine dell'applicazione Web. La seguente procedura illustra come specificare il mapping del prefisso di tag nel file Web.config.

Per aggiungere il mapping di un prefisso di tag nel file Web.config

Creare un file di testo denominato Web.config nella directory principale del sito Web, se tale file non è già esistente.

Se è stato creato un nuovo file Web.config, copiare il codice riportato di seguito nel file, quindi salvarlo.

<?xml version="1.0"?>
<configuration>
  <system.web>    
   <pages>
     <controls>
       <add tagPrefix="aspSample"            namespace="Samples.AspNet.CS.Controls">       </add>
     </controls>
   </pages>
  </system.web>
</configuration>

<?xml version="1.0"?>
<configuration>
  <system.web>    
   <pages>
     <controls>
       <add tagPrefix="aspSample"            namespace="Samples.AspNet.VB.Controls">       </add>
     </controls>
   </pages>
  </system.web>
</configuration>

La sezione evidenziata mostra una voce associata al prefisso di tag, in cui "aspSample" è mappato allo spazio dei nomi Samples.AspNet.CS.Controls o Samples.AspNet.VB.Controls.

Se il file Web.config è già esistente, aggiungere il testo evidenziato nel passaggio precedente come elemento figlio dell'elemento controls del file di configurazione. Se gli elementi controls e pages non sono presenti nel file Web.config, crearli come illustrato nel passaggio precedente.

Nota:

La voce del prefisso di tag è figlia della sezione controls, che deve trovarsi all'interno della sezione pages, la quale a sua volta è figlia di system.web.

Nota:
La voce del prefisso di tag è figlia della sezione controls, che deve trovarsi all'interno della sezione pages, la quale a sua volta è figlia di system.web.

Dopo aver specificato il mapping del prefisso di tag nel file di configurazione, è possibile utilizzare il controllo WelcomeLabel in modo dichiarativo (come <aspSample:WelcomeLabel />) in qualsiasi pagina del sito Web.

Nota:
La voce di configurazione per il prefisso di tag è una nuova funzionalità di ASP.NET 2.0. In ASP.NET 1.0 e 1.1, il mapping del prefisso di tag doveva essere specificato nella direttiva @ Register per ogni pagina che utilizzava il controllo personalizzato.

Creazione di una pagina che utilizza il controllo

Per creare una pagina che utilizza il controllo personalizzato

Creare un file di testo di nome WelcomeLabelTest.aspx nel sito Web.

Copiare il seguente markup nel file WelcomeLabelTest.aspx, quindi salvare il file.

<%@ Page Language="VB"%>
<!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 id="Head1" >
    <title>WelcomeLabel Test</title>
  </head>
  <body>
    <form id="form1" >
      <div>
        <aspSample:WelcomeLabel Text="Hello" ID="WelcomeLabel1" 
           BackColor="Wheat" ForeColor="SaddleBrown" />
      </div>
    </form>
  </body>
</html>

<%@ Page Language="C#"%>
<!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 id="Head1" >
    <title>WelcomeLabel Test</title>
  </head>
  <body>
    <form id="form1" >
      <div>
        <aspSample:WelcomeLabel Text="Hello" ID="WelcomeLabel1" 
           BackColor="Wheat" ForeColor="SaddleBrown" />
      </div>
    </form>
  </body>
</html>

Visualizzare WelcomeLabelTest.aspx nel browser immettendo il seguente URL nella barra degli indirizzi:
```
https://localhost/ServerControlsTest/WelcomeLabelTest.aspx
```
Modificare il codice di origine del controllo. Ad esempio, aggiungere una stringa immettendo la seguente riga di codice alla fine del metodo RenderContents :
```
writer.Write("Testing how the App_Code directory works.");
```
```
writer.Write("Testing how the App_Code directory works.")
```
Aggiornare la pagina WelcomeLabelTest.aspx nel browser.

Si noterà che le modifiche apportate si riflettono nella pagina anche se non è stata effettuata la compilazione del controllo.

Oltre alla proprietà Text del controllo WelcomeLabel, che è stata definita in modo esplicito, l'stanza del controllo presente sulla pagina presenta le proprietà BackColor e ForeColor che non sono state definite esplicitamente. Il controllo WelcomeLabel eredita queste ed altre proprietà relative allo stile dalla classe base WebControl. Inoltre, è possibile assegnare il controllo WelcomeLabel a un'interfaccia ed inserirlo in un tema senza necessità di intervento da parte dello sviluppatore.

Compilazione del controllo in un assembly

Anche se la directory App_Code consente di sottoporre a test il controllo personalizzato senza compilarlo, quest'ultima operazione è necessaria se si desidera distribuire il controllo come codice oggetto ad altri sviluppatori. Inoltre, non è possibile aggiungere un controllo alla casella degli strumenti di una finestra di progettazione visiva se non lo si è compilato in un assembly.

Per compilare il controllo in un assembly

Impostare la variabile di ambiente PATH di Windows in modo da includere il percorso dell'installazione di .NET Framework, come illustrato di seguito:
1. In Windows, fare clic con il pulsante destro del mouse su Risorse del computer, selezionare Proprietà, quindi selezionare la scheda Avanzate e fare clic sul pulsante Variabili d'ambiente.
2. Nell'elenco Variabili di sistema, fare doppio clic sulla variabile Path.
3. Nella casella di testo Valore variabile, aggiungere un punto e virgola (;) alla fine dei valori preesistenti, quindi digitare il percorso di installazione di .NET Framework. .NET Framework viene in genere installato nella directory di installazione nel percorso Windows in \Microsoft.NET\Framework\versionNumber.
4. Fare clic OK su ciascuna finestra di dialogo per chiuderla.
Nella directory creata per i file di origine nel primo passaggio della procedura, eseguire il comando riportato di seguito.

Nota:

Questa directory è diversa dalla directory App_Code in cui sono stati copiati i file di origine del controllo per eseguire il test.
```
csc /t:library /out:Samples.AspNet.CS.Controls.dll /r:System.dll /r:System.Web.dll *.cs
```
```
vbc /t:library /out:Samples.AspNet.VB.Controls.dll /r:System.dll /r:System.Web.dll *.vb
```
L'opzione /t:library richiede al compilatore di creare una libreria e non un assembly eseguibile. L'opzione /out specifica il nome dell'assembly e l'opzione /r elenca gli assembly collegati all'assembly del controllo personalizzato.

Nota:
Questa directory è diversa dalla directory App_Code in cui sono stati copiati i file di origine del controllo per eseguire il test.

Per motivi di brevità, questa procedura illustra la creazione di un assembly contenente un singolo controllo. In generale, le indicazioni per la progettazione di .NET Framework non consigliano la creazione di assembly che contengono poche classi. Per ottimizzare la distribuzione, si consiglia di creare il minor numero di assembly possibile.

Incorporazione di un'icona nell'assembly del controllo

A visual designer such as Visual Studio 2005 typically uses a default icon (such as an image of a gear) to display a control in the toolbox. Opzionalmente, è possibile personalizzare l'aspetto del controllo nella casella degli strumenti incorporando una bitmap di 16x16 pixel nell'assembly. Per convenzione, le finestre di progettazione visiva utilizzano il pixel dell'angolo inferiore sinistro della bitmap come colore trasparente.

Per incorporare un'icona nell'assembly del controllo

Creare una bitmap di 16x16 pixel, o utilizzarne una esistente, per l'icona del controllo da visualizzare della casella di strumenti.
Assegnare alla bitmap il nome WelcomeLabel.bmp.
Aggiungere il file della bitmap alla directory (CustomControlsCS o CustomControlsVB) che contiene i file di origine del controllo WelcomeLabel.
Nella directory che contiene i file di origine, eseguire il seguente comando:
```
csc /res:WelcomeLabel.bmp,Samples.AspNet.CS.Controls.WelcomeLabel.bmp 
/t:library /out:Samples.AspNet.CS.Controls.dll /r:System.dll 
/r:System.Web.dll *.cs
```
```
vbc /res:WelcomeLabel.bmp,Samples.AspNet.VB.Controls.WelcomeLabel.bmp 
/t:library /out:Samples.AspNet.VB.Controls.dll /r:System.dll 
/r:System.Web.dll *.vb
```
Il comando compila il controllo e incorpora la bitmap nell'assembly come risorsa. Il nome attribuito alla risorsa bitmap incorporata deve essere uguale al nome completo dello spazio dei nomi del controllo cui la risorsa è associata. Ad esempio, se il nome del controllo è Samples.AspNet.CS.Controls.WelcomeLabel, il nome della bitmap incorporata dovrà essere Samples.AspNet.CS.Controls.WelcomeLabel.bmp. In base a questa convenzione di denominazione, la finestra di progettazione visiva utilizzerà automaticamente la bitmap come icona del controllo personalizzato nella casella degli strumenti. Se non si utilizza la convenzione di denominazione, è necessario applicare l'attributo ToolboxBitmapAttribute al controllo per specificare il nome della risorsa bitmap incorporata.

Uso dell'attributo TagPrefixAttribute per eseguire il mapping prefisso di tag/spazio dei nomi

Precedentemente in questa procedura, nella sezione dedicata alla directory App_Code, si è illustrato come specificare un prefisso di tag nella pagina o nel file Web.config. È inoltre possibile, come opzione, indicare un prefisso di tag da utilizzare nella finestra di progettazione visiva per il controllo personalizzato includendo l'attributo System.Web.UI.TagPrefixAttribute a livello di assembly. L'attributo TagPrefixAttribute consente di assegnare un prefisso di tag da utilizzare nella finestra di progettazione visiva, se questa non individua un mapping di prefisso di tag nel file Web.config o in una direttiva Register della pagina. Il prefisso di tag è registrato sulla pagina quando si fa doppio clic per la prima volta sul controllo nella casella degli strumenti o quando lo si trascina sulla pagina.

Si può decidere di utilizzare l'attributo TagPrefixAttribute, specificandolo in un file separato che è compilato con i controlli personalizzati. Per convenzione, il file è denominato AssemblyInfo.languageExtension, ad esempio: AssemblyInfo.cs o AssembyInfo.vb. La procedura riportata di seguito descrive come specificare i metadati TagPrefixAttribute.

Nota:
Se non viene specificato l'attributo TagPrefixAttribute nell'assembly del controllo, né il mapping del prefisso di tag/spazio dei nomi nella pagina o nel file Web.config, la pagina di progettazione visiva potrebbe creare un prefisso di tag predefinito. Ad esempio, in Visual Studio 2005 verrà creato un tag predefinito come cc1 per il controllo personalizzato quando questo viene trascinato dalla casella degli strumenti.

Se non viene specificato l'attributo TagPrefixAttribute nell'assembly del controllo, né il mapping del prefisso di tag/spazio dei nomi nella pagina o nel file Web.config, la pagina di progettazione visiva potrebbe creare un prefisso di tag predefinito. Ad esempio, in Visual Studio 2005 verrà creato un tag predefinito come cc1 per il controllo personalizzato quando questo viene trascinato dalla casella degli strumenti.

Per aggiungere un mapping spazio dei nomi/prefisso di tag mediante l'attributo TagPrefixAttribute

Creare un file denominato nome AssemblyInfo.cs o AssemblyInfo.vb nella directory del codice di origine e aggiungere il seguente codice al file.
```
using System;
using System.Web.UI;
[assembly: TagPrefix("Samples.AspNet.CS.Controls", "aspSample")]
```
```
Imports System
Imports System.Web.UI
<Assembly: TagPrefix("Samples.AspNet.VB.Controls", "aspSample")> 
```
L'attributo del prefisso di tag crea un mapping fra lo spazio dei nomi Samples.AspNet.CS.Controls o Samples.AspNet.VB.Controls e il prefisso aspSample.
Ricompilare tutti i file di origine mediante il comando di compilazione già utilizzato precedentemente (con o senza la risorsa incorporata).

Utilizzo del controllo personalizzato compilato in una pagina ASP.NET

Per sottoporre a test la versione compilata del controllo personalizzato, è necessario che l'assembly del controllo sia accessibile alle pagine del sito Web.

Per rendere l'assembly del controllo personalizzato accessibile al sito Web

Creare una directory Bin nella directory principale del sito Web.
Copiare l'assembly del controllo (Samples.AspNet.CS.Controls.dll o Samples.AspNet.VB.Controls.dll) nella directory Bin.
Eliminare il file di origine del controllo dalla directory App_Code.

Se i file di origine non vengono eliminati, il tipo del controllo sarà presente sia nell'assembly compilato che nell'assembly generato in modo dinamico da ASP.NET. Ciò provocherà la creazione di un riferimento ambiguo quando il controllo viene caricato, generando un errore del compilatore in tutte le pagine che lo utilizzano.

L'assembly creato in questa procedura è un assembly privato e in quanto tale deve essere collocato in una directory Bin del sito Web ASP.NET affinché le pagine del sito Web possano utilizzare il controllo. L'accesso all'assembly non sarà consentito ad altre applicazioni applicazioni a meno che non ne venga installata una copia in ciascuna applicazione. Se si creano controlli per applicazioni host Web condivise, si consiglia di raccogliere i controlli in un assembly privato. Tuttavia, se si creano controlli da utilizzare in un ambiente host dedicato o se si crea una suite di controlli che verrà resa disponibile a tutti i clienti di un ISP, è necessario raccogliere i controlli in un assembly condiviso con nome sicuro e installarlo nella Global Assembly Cache. Per ulteriori informazioni, consultare Utilizzo di assembly e della Global Assembly Cache.

Il passaggio successivo consiste nella modifica del mapping del prefisso di tag creato nel file Web.config per specificare il nome dell'assembly del controllo.

Per modificare il mapping del prefisso di tag nel file Web.config

Modificare il file Web.config aggiungendo un attributo assembly all'elemento addtagPrefix:

<controls>
  <add tagPrefix="aspSample"   
    namespace="Samples.AspNet.CS.Controls" 
    assembly="Samples.AspNet.CS.Controls">
  </add>
</controls>

<controls>
  <add tagPrefix="aspSample"   
    namespace="Samples.AspNet.VB.Controls" 
    assembly="Samples.AspNet.VB.Controls">
  </add>
</controls>

L'attributo assembly specifica il nome dell'assembly in cui si trova il controllo. L'elemento addtagPrefix mappa un prefisso di tag alla combinazione di uno spazio dei nomi e di un assembly. Quando l'assembly è generato in modo dinamico da ASP.NET a partire dai file di origine presenti della directory App_Code, l'attributo dell'assembly non è necessario. Quando l'attributo dell'assembly non è utilizzato, ASP.NET carica il tipo di controllo dagli assembly creati in modo dinamico a partire dal contenuto della directory App_Code.

Per visualizzare la pagina che utilizza il controllo personalizzato

Visualizzare la pagina WelcomeLabelTest.aspx nel browser immettendo il seguente URL nella barra degli indirizzi:
```
https://localhost/ServerControlsTest/WelcomeLabelTest.aspx
```

Se si utilizza il controllo in una finestra di progettazione visiva come Visual Studio 2005, è possibile aggiungere il controllo alla casella degli strumenti, trascinarlo da questa nell'area di progettazione e accedere alle proprietà e agli eventi del controllo in Visualizzatore proprietà. Inoltre, in Visual Studio 2005 il controllo dispone del supporto IntelliSense completo sia nella visualizzazione Origine della finestra di progettazione delle pagine sia nell'editor di codice, incluso il completamento di istruzioni nei blocchi di script e la visualizzazione delle proprietà quando si fa clic sul tag del controllo.

Nota:
In molti strumenti di progettazione visiva, è possibile aggiungere controlli personalizzati alla casella degli strumenti. Per informazioni dettagliate, consultare la documentazione relativa allo strumento di progettazione.

Passaggi successivi

In questa procedura dettagliata si è illustrato come sviluppare un semplice controllo server ASP.NET personalizzato e come utilizzarlo in una pagina. Si è inoltre illustrato come definire una proprietà e come compilare il controllo personalizzato in un assembly. Per ulteriori informazioni, incluse le informazioni sul rendering, la definizione delle proprietà, la gestione delle informazioni sullo stato e l'implementazione dei controlli compositi, consultare Sviluppo di controlli server ASP.NET personalizzati.

Nella procedura dettagliata, si è illustrata la creazione di un'icona da visualizzare nella casella degli strumenti per il controllo personalizzato e si è mostrato come aggiungere metadati per la fase di progettazione allo scopo di personalizzare il Visualizzatore proprietà per il controllo personalizzato. I controlli complessi come il controllo GridView ottimizzano il lavoro in fase di progettazione perché usano classi di finestre di progettazione visiva che forniscono interfacce utente diverse in fase di progettazione e di esecuzione. Il modello a oggetti della finestra di progettazione ASP.NET 2.0 per i controlli server presenta differenze sognificative rispetto al modello fornito in ASP.NET 1.0 e 1.1. Per maggiori informazioni sull'implementazione di classi della finestra di progettazione personalizzate in ASP.NET 2.0, consultare Cenni preliminari sulle finestre Progettazione controlli ASP.NET.

In ASP.NET 2.0, un controllo server può definire comportamenti diversi per i browser client o le periferiche che utilizzano le classi di adattatori. Per maggiori informazioni, consultare Sviluppo di adattatori per controlli server ASP.NET

Browser diversi e versioni diverse dello stesso browser supportano funzionalità differenti. I controlli server ASP.NET determineranno automaticamente il browser che ha richiesto la pagina ASPX facendo sì che il formato del markup HTML generato sia corretto per quel browser. Non è tuttavia possibile eseguire il rendering di alcune funzionalità dei controlli in browser meno recenti, pertanto è opportuno esaminare l'output delle pagine nel maggior numero di tipi di browser diversi in modo da verificare che siano tutte visualizzate come desiderato in tutti i browser. Per ulteriori informazioni, vedere Controlli server Web ASP.NET e funzionalità del browser.

Vedere anche

Altre risorse

Sviluppo di controlli server ASP.NET personalizzati

Condividi tramite