Como: Tratar um controle de usuário sistema autônomo um controle de Web Parts

Artigo
10/15/2014

O conjunto de controles ASP.NET Web Parts habilita você a usar controles de servidor Web existentes, como controle Web Parts, a fim de obter reutilização máxima de código e as vantagens de personalização Web Parts.Controles de usuário são um tipo de controle de servidor que você pode usar como controles Web Parts.Este tópico demonstra como tratar um controle de usuário existente como um controle Web Parts.

Observação:
Para este procedimento funcionar, é necessário um site da Web ASP.NET que possa identificar usuários individuais.Se você tiver um site já configurado, você pode usá-lo.Caso contrário, para detalhes na criação de um diretório virtual ou site, veja Como: Criar e configurar diretórios virtual no IIS 5.0 e 6.0.Você também precisa de um controle de usuário que esteja ativado para trabalhar com personalização Web Parts.Se você não tem um controle de usuário como solicitado, um exemplo é fornecido na seção Code.

Para este procedimento funcionar, é necessário um site da Web ASP.NET que possa identificar usuários individuais.Se você tiver um site já configurado, você pode usá-lo.Caso contrário, para detalhes na criação de um diretório virtual ou site, veja Como: Criar e configurar diretórios virtual no IIS 5.0 e 6.0.Você também precisa de um controle de usuário que esteja ativado para trabalhar com personalização Web Parts.Se você não tem um controle de usuário como solicitado, um exemplo é fornecido na seção Code.

Quando você usa um controle de usuário em um aplicativo Web Parts, ele usa todas os recursos de um controle WebPart em tempo de execução.Para obter detalhes, consulte:Usando controles do servidor ASP.NET em aplicativos Web Parts.O controle de usuário também manterá seus recursos normais sistema autônomo um controle de servidor, com uma exceção: cache de saída é desabilitado em controles de usuário que estão sendo usados em aplicativos Web Parts.O conjunto de controles Web Parts requer que todos os controles sejam adicionados à árvore do controle para cada solicitação da página.Isso é necessário para que o recurso de personalização possam funcionar, e dados de personalização possam ser processados pelos controles.No entanto, quando a saída de cache está ativada em um controle de usuário, ele não é incluído à árvore do controle, o que poderia interferir com os recursos Web Parts.Por isso a saída de cache é, por padrão, desativada em controles de usuário em aplicativos Web Parts.

Para criar uma página Web Parts para hospedar o controle de usuário

Crie uma nova página ASP.NET.Adicione a seguinte declaração de página na parte superior da página.
```
<@page language="VB" %>
```
```
<@page language="C#" %>
```

Sob a declaração de página que você acabou de adicionar, adicione a seguinte estrutura de página básica com marcas HTML.

<html>
<head>
  <title>Web Parts Demo Page</title>
</head>
<body>
  <h1>Web Parts User Control Demonstration</h1>
  <form >
  <table cellspacing="0" cellpadding="0" border="0">
    <tr>
      <td valign="top">
      </td>
      <td valign="top">
      </td>
      <td valign="top">
      </td>
    </tr>
  </table>
  </form>
</body>
</html>

Salve a página em um diretório abaixo do site que está ativado para personalização.

Para adicionar controles Web Parts à página

Logo abaixo do elemento <form> na sua página, adicione um controle WebPartManager.
```
<asp:webpartmanager id="WebPartManager1"  />
```
Logo abaixo do elemento <asp:webpartmanager> e dentro do primeiro conjunto de marcas <td> da tabela (a primeira coluna de tabela) adicionar um controle WebPartZone para conter o controle de usuário que você irá adicionar em uma etapa posterior.
```
<asp:webpartzone id="SideBarZone"  
  headertext="Sidebar Zone">
  <zonetemplate>
  </zonetemplate>
</asp:webpartzone>
```
Dentro do elemento <zonetemplate> da zona que você acabou de adicionar, adicione um controle de servidor existente e algum conteúdo estático que será tratado como um outro controle Web Parts (como está dentro de uma zona Web Parts) em tempo de execução:
```
<asp:label  id="linksPart" title="My Links">
  <a href="www.asp.net">ASP.NET site</a> 
  <br />
  <a href="www.gotdotnet.com">GotDotNet</a> 
  <br />
  <a href="www.contoso.com">Contoso.com</a> 
  <br />
</asp:label>
```
Dentro do segundo conjunto de marcas <td> da tabela (a segunda coluna de tabela) adicione outro controle WebPartZone para conter o controle de usuário que você irá adicionar em uma etapa posterior.
```
<asp:webpartzone id="MainZone"  
  headertext="Main Zone">
  <zonetemplate>
  </zonetemplate>
</asp:webpartzone>
```
Adicione no terceiro elemento <td> da tabela (a terceira coluna) adicione um elemento <asp:editorzone>.Adicionar um elemento <zonetemplate>, então adicione um elemento <asp:appearanceeditorpart> e um <asp:layouteditorpart>.O código na zona do editor deve parecer com o seguinte:
```
<asp:editorzone id="EditorZone1" >
  <zonetemplate>
    <asp:appearanceeditorpart  
      id="AppearanceEditorPart1" />
    <asp:layouteditorpart  
      id="LayoutEditorPart1" />
  </zonetemplate>
</asp:editorzone>
```
Salve a página.

Para criar um controle de usuário

Crie um novo arquivo no seu editor de texto.Esse arquivo irá conter um controle de usuário, que também pode ser adicionado à página como um controle Web Parts.

Observação:

O controle de pesquisa para esta explicação passo a passo não implementa a funcionalidade de pesquisa real; ele é usado somente para demonstrar recursos Web Parts.

Observação:
O controle de pesquisa para esta explicação passo a passo não implementa a funcionalidade de pesquisa real; ele é usado somente para demonstrar recursos Web Parts.

Na parte superior do novo arquivo, adicione uma declaração de controle como mostrado no exemplo a seguir.

<%@ control language="VB" classname="SearchUserControl" %>

<%@ control language="C#" classname="SearchUserControl" %>

Sob a declaração de controle, adicione um par de marcas <script>, e dentro deles adicione código para criar uma propriedade personalizável.Observe que a propriedade ResultsPerPage possui um atributo Personalizable.Esta propriedade deve permitir que os usuários do controle personalizem quantos resultados retornar por página, se você tiver fornecido um controle de edição com interface com o usuário (UI) para alterar a configuração em modo Design.O código para o controle deve ter a aparência do exemplo de código a seguir.
```
<%@ control language="VB" classname="SearchUserControl" %>
<script >
  Private results As Integer

  <Personalizable()> _
  Property ResultsPerPage() As Integer

    Get
      Return results
    End Get

    Set(ByVal value As Integer)
      results = value
    End Set

  End Property
</script>
```
```
<%@ control language="C#" classname="SearchUserControl" %>
<script >
  private int results;

  [Personalizable]
  public int ResultsPerPage
  {
    get
      {return results;}

    set
      {results = value;}
  }    
</script>
```
Adicione uma caixa de texto e um botão abaixo do elemento <script> para fornecer interface básica com um usuário para um controle de pesquisa, como mostrado no exemplo de código a seguir.
```
<asp:textbox  id="inputBox"></asp:textbox>
<br />
<asp:button  id="searchButton" text="Search" />
```

Nomeie o arquivo SearchUserControlVB.ascx ou SearchUserControlCS.ascx (dependendo da linguagem que você está usando) e salve o no mesmo diretório que a página WebPartsDemo.aspx.

Observação de segurança:
Esse controle tem um caixa de texto que aceita a entrada do usuário, o que é uma ameaça potencial de segurança.A entrada do usuário em uma página da Web pode conter script de cliente mal-intencionado.Por padrão, páginas da Web ASP.NET validam a entrada do usuário para garantir que a entrada não contenha elementos HTML ou script.Contanto que essa validação esteja ativada, não é preciso explicitamente verificar script ou elementos HTML na entrada do usuário.Para obter mais informações, consulte Visão Geral de Scripts Maliciosos.

Esse controle tem um caixa de texto que aceita a entrada do usuário, o que é uma ameaça potencial de segurança.A entrada do usuário em uma página da Web pode conter script de cliente mal-intencionado.Por padrão, páginas da Web ASP.NET validam a entrada do usuário para garantir que a entrada não contenha elementos HTML ou script.Contanto que essa validação esteja ativada, não é preciso explicitamente verificar script ou elementos HTML na entrada do usuário.Para obter mais informações, consulte Visão Geral de Scripts Maliciosos.

Para fazer referência ao controle de usuário dentro da zona Web Parts principal

Na parte superior da página da Web, logo após a declaração da página, adicione a declaração a seguir para fazer referência ao controle de usuário recém-criado.Se você não estiver usando a amostra de controle de usuário fornecida neste tópico, o atributo src precisará ser definido como o caminho e nome do arquivo do controle de usuário que você está usando, e você pode também opcionalmente atribuir um valor diferente para o atributo tagname.

[VB]
```
<%@ register tagprefix="uc1" tagname="SearchUserControl" 
    src="searchusercontrolvb.ascx" %>
```
[C#]
```
<%@ register tagprefix="uc1" tagname="SearchUserControl" 
    src="searchusercontrolcs.ascx" %>
```
Dentro do elemento <zonetemplate> da zona Main, referencie o controle de usuário criado anteriormente.
```
<uc1:SearchUserControl id="searchPart" 
  title="Search" />
```
Salve e feche a página.

Exemplo

O exemplo de código a seguir fornece uma listagem de código completa do exemplo de página Web Parts usado para hospedar o controle de usuário.Ele também fornece código para o exemplo de controle de usuário que é referenciado na página como um controle Web Parts.Observe que para o controle de usuário ser tratado como um verdadeiro controle Web Parts capaz de personalização, ele deve expor uma propriedade pública usando o atributo de código [Personalizable].

<!-- Web Parts page to host the user control -->
<%@ page language="VB" %>
<%@ register tagprefix="uc1" tagname="SearchUserControl" 
  src="searchusercontrol.ascx" %>

<html>
<head>
  <title>Web Parts Demo Page</title>
</head>
<body>
  <h1>Web Parts User Control Demonstration</h1>
  <form  id="form1">
  <asp:webpartmanager id="WebPartManager1"  />
  <asp:webpartpagemenu
    id="pagemenu1"
    
    Mode="Menu"
    MenuStyle-BorderWidth="1">
    <browsemodeverb text="Browse" />
    <designmodeverb text="Design" />
    <editmodeverb text="Edit" />
  </asp:webpartpagemenu>
  <table cellspacing="0" cellpadding="0" border="0">
    <tr>
      <td valign="top">
        <asp:webpartzone id="SideBarZone"  
          headertext="Sidebar Zone">
          <zonetemplate>
            <asp:label  id="linksPart" title="My Links">
              <a href="www.asp.net">ASP.NET site</a> 
              <br />
              <a href="www.gotdotnet.com">GotDotNet</a> 
              <br />
              <a href="www.contoso.com">Contoso.com</a> 
              <br />
            </asp:label>
          </zonetemplate>
        </asp:webpartzone>
      </td>
      <td valign="top">
        <asp:webpartzone id="MainZone"  
          headertext="Main Zone">
          <zonetemplate>
            <uc1:SearchUserControl id="searchPart" 
              title="Search" />
          </zonetemplate>
        </asp:webpartzone>
      </td>
      <td valign="top">
        <asp:editorzone id="EditorZone1" >
          <zonetemplate>
            <asp:appearanceeditorpart  
              id="AppearanceEditorPart1" />
            <asp:layouteditorpart  
              id="LayoutEditorPart1" />
          </zonetemplate>
        </asp:editorzone>
      </td>
    </tr>
  </table>
  </form>
</body>
</html>


<!-- Web Parts user control -->
<%@ control language="VB" classname="SearchUserControl" %>
<script >
  Private results As Integer
  
  <Personalizable()> _
  Property ResultsPerPage() As Integer
    
    Get
      Return results
    End Get
    
    Set(ByVal value As Integer)
      results = value
    End Set
    
  End Property
</script>
<asp:textbox  id="inputBox"></asp:textbox>
<br />
<asp:button  id="searchButton" text="Search" />

<!-- Web Parts page to host the user control -->
<%@ page language="C#" %>
<%@ register tagprefix="uc1" tagname="SearchUserControl" 
  src="searchusercontrol.ascx" %>

<html>
<head>
  <title>Web Parts Demo Page</title>
</head>
<body>
  <h1>Web Parts User Control Demonstration</h1>
  <form  id="form1">
  <asp:webpartmanager id="WebPartManager1"  />
  <asp:webpartpagemenu
    id="pagemenu1"
    
    Mode="Menu"
    MenuStyle-BorderWidth="1">
    <browsemodeverb text="Browse" />
    <designmodeverb text="Design" />
    <editmodeverb text="Edit" />
  </asp:webpartpagemenu>
  <table cellspacing="0" cellpadding="0" border="0">
    <tr>
      <td valign="top">
        <asp:webpartzone id="SideBarZone"  
          headertext="Sidebar Zone">
          <zonetemplate>
            <asp:label  id="linksPart" title="My Links">
              <a href="www.asp.net">ASP.NET site</a> 
              <br />
              <a href="www.gotdotnet.com">GotDotNet</a> 
              <br />
              <a href="www.contoso.com">Contoso.com</a> 
              <br />
            </asp:label>
          </zonetemplate>
        </asp:webpartzone>
      </td>
      <td valign="top">
        <asp:webpartzone id="MainZone"  
          headertext="Main Zone">
          <zonetemplate>
            <uc1:SearchUserControl id="searchPart" 
              title="Search" />
          </zonetemplate>
        </asp:webpartzone>
      </td>
      <td valign="top">
        <asp:editorzone id="EditorZone1" >
          <zonetemplate>
            <asp:appearanceeditorpart  
              id="AppearanceEditorPart1" />
            <asp:layouteditorpart  
              id="LayoutEditorPart1" />
          </zonetemplate>
        </asp:editorzone>
      </td>
    </tr>
  </table>
  </form>
</body>
</html>


<!-- Web Parts user control -->
<%@ control language="C#" classname="SearchUserControl" %>
<script >
  private int results;
  
  [Personalizable]
  public int ResultsPerPage
  {
    get
      {return results;}
    
    set
      {results = value;}
  }    
</script>
<asp:textbox  id="inputBox"></asp:textbox>
<br />
<asp:button  id="searchButton" text="Search" />

Se você executa o código de exemplo e clicar no menu de página modo de exibição, você pode alternar entre os modos de personalização diferentes no menu: Procurar, Design, and edição.No modo Design, você pode organizar o layout da página, clicando no cabeçalho dos dois controles Web Parts e arrastando-os para outras zonas.No modo Edit, você pode clicar na imagem de edição no cabeçalho de um dos controles Web Parts, e depois definir várias propriedades de interface com o usuário nesse controle.