@ Register

[Questa documentazione ha solo scopo di anteprima ed è soggetta a modifiche nelle versioni successive. Gli argomenti vuoti sono inclusi come segnaposto.]

Crea un'associazione tra un prefisso di tag e un controllo personalizzato che consente agli sviluppatori di fare riferimento in modo conciso ai controlli personalizzati in un file di applicazione ASP.NET (compresi pagine Web, controlli utente e pagine master).

<%@ Register tagprefix="tagprefix"
   namespace="namespace"
   assembly="assembly" %>
<%@ Register tagprefix="tagprefix"
   namespace="namespace" %>
<%@ Register tagprefix="tagprefix"
   tagname="tagname"
   src="pathname" %>

Attributi

  • assembly
    Assembly in cui si trova lo spazio dei nomi associato all'attributo tagprefix.

    Nota

    Il nome dell'assembly non può includere un'estensione file.Si noti inoltre che, se l'attributo assembly manca, il parser ASP.NET presume che ci sia codice sorgente nella cartella App_Code dell'applicazione.Se si dispone di codice sorgente per un controllo che si desidera registrare in una pagina senza dover compilarlo, inserire il codice sorgente nella cartella App_Code.In fase di esecuzione, ASP.NET compila in modo dinamico i file di origine nella cartella App_Code.

  • namespace
    Lo spazio dei nomi del controllo personalizzato sottoposto a registrazione.

  • src
    Percorso (relativo o assoluto) del file ASP.NET User Controls dichiarativo da associare alla coppia tagprefix:tagname.

  • tagname
    Alias arbitrario da associare a una classe. Questo attributo viene utilizzato solo per i controlli utente.

  • tagprefix
    Alias arbitrario che fornisce un riferimento rapido allo spazio dei nomi del markup utilizzato nel file contenente la direttiva.

Note

Se si include la direttiva @ Register in una pagina o in un controllo utente, è possibile disporre controlli server o controlli utente personalizzati tramite la sintassi Sintassi di controlli server personalizzati dichiarativa.

Nota

È inoltre possibile registrare controlli personalizzati in tutte le pagine di un'applicazione utilizzando Elemento controls per pages (schema delle impostazioni ASP.NET) nel file Web.config.

Utilizzare la direttiva @ Register nelle situazioni seguenti:

  • Per aggiungere un controllo server personalizzato in modo dichiarativo a una pagina Web, a un controllo utente, a una pagina master o a un file di interfaccia (vedere ASP.NET Themes Overview).

  • Per aggiungere un controllo utente in modo dichiarativo a una pagina Web, a un controllo utente, a una pagina master o a un file di interfaccia.

Nota

Il valore tagprefix "mobile" è utilizzato da ASP.NET per identificare i controlli Web mobili nello spazio dei nomi System.Web.UI.MobileControls.È consigliabile evitare di utilizzare questo prefisso per i controlli.

Quando si utilizza la direttiva @ Register per fare riferimento a un controllo, è possibile inserire il codice per il controllo nelle posizioni seguenti:

  • Come codice sorgente nella cartella App_Code dell'applicazione, dove verrà compilato in modo dinamico in fase di esecuzione. Si tratta di un'opzione pratica durante lo sviluppo. Se si sceglie questa opzione, non si utilizza l'attributo assembly nella direttiva @ Register.

  • Come assembly compilato nella cartella Bin dell'applicazione. È un'opzione comune per le applicazioni Web distribuite.

  • Come assembly compilato e firmato nella Global Assembly Cache (GAC). È un'opzione comune se si desidera condividere un controllo compilato fra più applicazioni. È possibile fare riferimento a un controllo nella Global Assembly Cache assegnando una stringa di identificazione all'attributo assembly. La stringa specifica i dettagli obbligatori per il controllo, incluso il nome del tipo completo, la versione, il token di chiave pubblica e le impostazioni cultura. La stringa fittizia seguente illustra un riferimento a un controllo personalizzato nella Global Assembly Cache:

    <%@ Register  tagprefix="custom"
         namespace="Mycompany.namespace"
         assembly="Mycompany.namespace.control, Version=1.2.3.4, 
            PublicKeyToken=12345678abcdefgh, Culture=neutral"  %>
    

    Per ulteriori informazioni sugli assembly di riferimento, vedere Elemento add per assemblies per compilation (schema delle impostazioni ASP.NET).

Per i controlli utente dichiarativi, utilizzare gli attributi tagname, tagprefix e src. I primi due vengono sempre utilizzati insieme come coppia separata dal segno di due punti (tagprefix:tagname) quando si dichiara il controllo nella pagina. È possibile eseguire il mapping di più spazi dei nomi allo stesso tagname, come illustrato nell'esempio seguente:

<% @Register tagprefix="tag1" namespace="MyNamespace1"/>
<% @Register tagprefix="tag1" namespace="MyNamespace2"/> 

Il valore dell'attributo src può essere un percorso relativo o assoluto per il file di origine del controllo utente a partire dalla directory radice dell'applicazione. Per praticità, si consiglia di utilizzare un percorso relativo. Si supponga, ad esempio, di memorizzare tutti i file dei controlli utente dell'applicazione in una directory \Usercontrol che è una sottodirectory della directory radice dell'applicazione. Per includere il controllo utente presente nel file Usercontrol1.ascx, inserire nella direttiva @ Register la stringa seguente:

Src="~\usercontrol\usercontrol1.ascx" 

Il carattere tilde (~) rappresenta la directory radice dell'applicazione.

Nota

Se il controllo utente si trova nella stessa directory della pagina che lo contiene, il valore dell'attributo src deve corrispondere al nome e all'estensione del file ascx.

Quando si includono controlli server personalizzati che sono stati compilati in un file dll per essere utilizzati con l'applicazione, utilizzare l'attributo tagprefix insieme agli attributi assembly e namespace. Se non si include l'attributo namespace o se si assegna una stringa vuota ("") a tale attributo, si verificherà un errore del parser.

Avviso

Quando si sviluppa un controllo server personalizzato, è necessario includerlo in uno spazio dei nomi,altrimenti non risulterà accessibile da una pagina ASP.NET.Per ulteriori informazioni sullo sviluppo di controlli server ASP.NET, vedere Developing Custom ASP.NET Server Controls.

Esempio

Nell'esempio di codice riportato di seguito vengono utilizzate le direttive @ Register per dichiarare gli alias tagprefix e tagname assegnando nel contempo un attributo src per fare riferimento a un controllo utente all'interno di una pagina Web. La prima parte del codice è un controllo utente semplice costituito da un controllo Calendar ASP.NET. La seconda parte del codice è una pagina che contiene il controllo. Si noti che l'attributo tagprefix assegna un valore di prefisso arbitrario da utilizzare con il tag. L'attributo tagname utilizza il valore del nome della classe assegnato al controllo utente (sebbene il valore di questo attributo sia arbitrario e possa essere utilizzato qualsiasi valore di stringa, non è necessario utilizzare il nome della classe del controllo a cui si fa riferimento). L'attributo src fa riferimento al file di origine per il controllo utente relativo alla cartella radice dell'applicazione. Al controllo utente viene fatto riferimento all'interno del corpo della pagina mediante il prefisso, il segno di due punti e il nome del tag, nel formato seguente: <uc1:CalendarUserControl runat="server" />.

<%@ Control ClassName="CalendarUserControl" %>
<asp:calendar id="Calendar1" runat="server" />


<%@ Page %>
<%@ register tagprefix="uc1" 
    tagname="CalendarUserControl" 
    src="~/CalendarUserControl.ascx" %>

<!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>Calendar Page</title>
</head>
<body>
  <form id="form1" runat="server">
    <uc1:calendarusercontrol runat="server" />
  </form>
</body>
</html>

Vedere anche

Riferimenti

Sintassi della direttiva template di testo

Concetti

ASP.NET Web Page Syntax Overview

Altre risorse

ASP.NET User Controls