Compartilhar via

Estendendo o namespace My no Visual Basic

  • Artigo

O namespace My no Visual Basic expõe propriedades e métodos que permitem a você aproveitar facilmente o poder do .NET Framework. O namespace My simplifica problemas comuns de programação, geralmente reduzindo uma tarefa difícil para uma única linha de código. Além disso, o namespace My é totalmente extensível para que você possa personalizar o comportamento de My e adicionar novos serviços à sua hierarquia para se adaptar às necessidades específicas do aplicativo. Este tópico discute como personalizar os membros existentes do namespace My e como adicionar suas próprias classes personalizadas ao namespace My.

Personalizando membros de namespace existentes My

O namespace My do Visual Basic expõe informações usadas com frequência sobre seu aplicativo, seu computador e muito mais. Para obter uma lista completa dos objetos no namespace My, confira Minha Referência. Talvez seja necessário personalizar os membros existentes do namespace My para que eles correspondam melhor às necessidades do aplicativo. Qualquer propriedade de um objeto no namespace My que não seja somente leitura pode ser definida como um valor personalizado.

Por exemplo, suponha que você use frequentemente o objeto My.User para acessar o contexto de segurança atual para o usuário que executa seu aplicativo. No entanto, sua empresa usa um objeto de usuário personalizado para expor informações e recursos adicionais para usuários dentro da empresa. Nesse cenário, você pode substituir o valor padrão da propriedade My.User.CurrentPrincipal por uma instância do seu próprio objeto principal personalizado, conforme mostrado no exemplo a seguir:

My.User.CurrentPrincipal = CustomPrincipal

Definir a propriedade CurrentPrincipal no objeto My.User altera a identidade sob a qual o aplicativo é executado. O objeto My.User, por sua vez, retorna informações sobre o usuário recém-especificado.

Adicionando membros a objetos My

Os tipos retornados de My.Application e My.Computer são definidos como classes Partial. Portanto, você pode estender os objetos My.Application e My.Computer, criando uma classe Partial chamada MyApplication ou MyComputer. A classe não pode ser uma classe Private. Se você especificar a classe como parte do namespace My, poderá adicionar propriedades e métodos que serão incluídos com os objetos My.Application ou My.Computer.

O exemplo a seguir adiciona uma propriedade chamada DnsServerIPAddresses ao objeto My.Computer:

Imports System.Net.NetworkInformation

Namespace My

  Partial Class MyComputer
    Friend ReadOnly Property DnsServerIPAddresses() As IPAddressCollection
      Get
        Dim dnsAddressList As IPAddressCollection = Nothing

        For Each adapter In System.Net.NetworkInformation.
          NetworkInterface.GetAllNetworkInterfaces()

          Dim adapterProperties = adapter.GetIPProperties()
          Dim dnsServers As IPAddressCollection = adapterProperties.DnsAddresses
          If dnsAddressList Is Nothing Then
            dnsAddressList = dnsServers
          Else
            dnsAddressList.Union(dnsServers)
          End If
        Next adapter

        Return dnsAddressList
      End Get
    End Property
  End Class

End Namespace

Adicionando objetos personalizados ao namespace My

Embora o namespace My forneça soluções para muitas tarefas comuns de programação, você pode encontrar tarefas que o namespace My não aborda. Por exemplo, seu aplicativo pode acessar serviços de diretório personalizados para dados do usuário ou seu aplicativo pode usar assemblies que não são instalados por padrão com o Visual Basic. Você pode estender o namespace My para incluir soluções personalizadas para tarefas comuns específicas ao seu ambiente. O namespace My pode ser facilmente estendido para adicionar novos membros a fim de atender às necessidades crescentes do aplicativo. Além disso, você pode implantar suas extensões de namespace My para outros desenvolvedores como um modelo do Visual Basic.

Adicionando membros ao namespace My

Como My é um namespace como qualquer outro namespace, você pode adicionar propriedades de nível superior a ele apenas adicionando um módulo e especificando um Namespace de My. Anotar o módulo com o atributo HideModuleName, conforme mostrado no exemplo a seguir. O atributo HideModuleName garante que o IntelliSense não exibirá o nome do módulo quando exibir os membros do namespace My.

Namespace My
  <HideModuleName()> 
  Module MyCustomModule

  End Module
End Namespace

Para adicionar membros ao namespace My, adicione propriedades conforme necessário ao módulo. Para cada propriedade adicionada ao namespace My, adicione um campo de tipo ThreadSafeObjectProvider(Of T) privado, onde o tipo é o tipo retornado por sua propriedade personalizada. Esse campo é usado para criar instâncias de objeto thread-safe a serem retornadas pela propriedade chamando o método GetInstance. Como resultado, cada thread que está acessando a propriedade estendida recebe sua própria instância do tipo retornado. O exemplo a seguir adiciona uma propriedade chamada SampleExtension que é do tipo SampleExtension ao namespace My:

Namespace My
  <HideModuleName()> 
  Module MyCustomExtensions
    Private _extension As New ThreadSafeObjectProvider(Of SampleExtension)
    Friend ReadOnly Property SampleExtension() As SampleExtension
      Get
        Return _extension.GetInstance()
      End Get
    End Property
  End Module
End Namespace

Adicionando eventos a objetos personalizados My

Você pode usar o objeto My.Application para expor eventos para seus objetos personalizados My, estendendo a classe parcial MyApplication no namespace My. Para projetos baseados no Windows, você pode clicar duas vezes no nó Meu Projeto para seu projeto no Gerenciador de Soluções. No Designer de Projeto do Visual Basic, clique na guia Aplicativo e clique no botão Exibir Eventos do Aplicativo. Um novo arquivo chamado ApplicationEvents.vb será criado. Ele contém o seguinte código para estender a classe MyApplication:

Namespace My
  Partial Friend Class MyApplication
  End Class
End Namespace

Você pode adicionar manipuladores de eventos para seus objetos personalizados My, adicionando manipuladores de eventos personalizados à classe MyApplication. Eventos personalizados permitem adicionar código que será executado quando um manipulador de eventos for adicionado, removido ou o evento for gerado. Observe que o código AddHandler de um evento personalizado é executado somente se o código for adicionado por um usuário para manipular o evento. Por exemplo, considere que o objeto SampleExtension da seção anterior tem um evento Load para o qual você deseja adicionar um manipulador de eventos personalizado. O exemplo de código a seguir mostra um manipulador de eventos personalizado chamado SampleExtensionLoad que será invocado quando o evento My.SampleExtension.Load ocorrer. Quando o código é adicionado para lidar com o novo evento My.SampleExtensionLoad, a parte AddHandler desse código de evento personalizado é executada. O método MyApplication_SampleExtensionLoad é incluído no exemplo de código para mostrar um exemplo de um manipulador de eventos que manipula o evento My.SampleExtensionLoad. Observe que o evento SampleExtensionLoad estará disponível quando você selecionar a opção Meus Eventos de Aplicativo na lista suspensa à esquerda acima do Editor de Código quando você estiver editando o arquivo ApplicationEvents.vb.

Namespace My

  Partial Friend Class MyApplication

    ' Custom event handler for Load event.
    Private _sampleExtensionHandlers As EventHandler

    Public Custom Event SampleExtensionLoad As EventHandler
      AddHandler(ByVal value As EventHandler)
        ' Warning: This code is not thread-safe. Do not call
        ' this code from multiple concurrent threads.
        If _sampleExtensionHandlers Is Nothing Then
          AddHandler My.SampleExtension.Load, AddressOf OnSampleExtensionLoad
        End If
        _sampleExtensionHandlers = 
            System.Delegate.Combine(_sampleExtensionHandlers, value)
      End AddHandler
      RemoveHandler(ByVal value As EventHandler)
        _sampleExtensionHandlers = 
          System.Delegate.Remove(_sampleExtensionHandlers, value)
      End RemoveHandler
      RaiseEvent(ByVal sender As Object, ByVal e As EventArgs)
        If _sampleExtensionHandlers IsNot Nothing Then
          _sampleExtensionHandlers.Invoke(sender, e)
        End If
      End RaiseEvent
    End Event

    ' Method called by custom event handler to raise user-defined
    ' event handlers.
    <Global.System.ComponentModel.EditorBrowsable( 
         Global.System.ComponentModel.EditorBrowsableState.Advanced)> 
      Protected Overridable Sub OnSampleExtensionLoad( 
                ByVal sender As Object, ByVal e As EventArgs)
      RaiseEvent SampleExtensionLoad(sender, e)
    End Sub

    ' Event handler to call My.SampleExtensionLoad event.
    Private Sub MyApplication_SampleExtensionLoad( 
        ByVal sender As Object, ByVal e As System.EventArgs
        ) Handles Me.SampleExtensionLoad

    End Sub
  End Class
End Namespace

Diretrizes de design

Ao desenvolver extensões para o namespace My, use as seguintes diretrizes para ajudar a minimizar os custos de manutenção dos componentes de extensão:

  • Inclua apenas a lógica de extensão. A lógica incluída na extensão do namespace My deve incluir apenas o código necessário para expor a funcionalidade necessária no namespace My. Como sua extensão residirá em projetos de usuário como código-fonte, a atualização do componente de extensão incorre em um alto custo de manutenção e deve ser evitada, se possível.
  • Minimize as suposições do projeto. Ao criar suas extensões do namespace My, não suponha um conjunto de referências, importações no nível do projeto ou configurações específicas do compilador (por exemplo, Option Strict desativado). Em vez disso, minimize as dependências e qualifique totalmente todas as referências de tipo usando a palavra-chave Global. Além disso, verifique se a extensão é compilada com Option Strict para minimizar erros na extensão.
  • Isole o código de extensão. Colocar o código em um único arquivo torna sua extensão facilmente implantável como um modelo de item do Visual Studio. Para obter mais informações, confira "Empacotamento e implantação de extensões" posteriormente neste tópico. Colocar todo o código de extensão do namespace My em um único arquivo ou uma pasta separada em um projeto também ajudará os usuários a localizar a extensão do namespace My.

Criando bibliotecas de classes para My

Como é o caso da maioria dos modelos de objeto, alguns padrões de design funcionam bem no namespace My e outros não. Ao criar uma extensão para o namespace My, considere os seguintes princípios:

  • Métodos sem estado. Os métodos no namespace My devem fornecer uma solução completa para uma tarefa específica. Verifique se os valores de parâmetro que são passados para o método fornecem todas as entradas necessárias para concluir a tarefa específica. Evite criar métodos que dependem do estado anterior, como conexões abertas com recursos.
  • Instâncias globais. O único estado que é mantido no namespace My é global para o projeto. Por exemplo, My.Application.Info encapsula o estado compartilhado em todo o aplicativo.
  • Tipos de parâmetro simples. Mantenha as coisas simples evitando tipos de parâmetros complexos. Em vez disso, crie métodos que não levem nenhuma entrada de parâmetro ou que usem tipos de entrada simples, como cadeias de caracteres, tipos primitivos e assim por diante.
  • Métodos de fábrica. Alguns tipos são necessariamente difíceis de instanciar. Fornecer métodos de fábrica como extensões para o namespace My permite que você descubra e consuma mais facilmente tipos que se enquadram nessa categoria. Um exemplo de um método de fábrica que funciona bem é My.Computer.FileSystem.OpenTextFileReader. Há vários tipos de fluxo disponíveis no .NET Framework. Ao especificar arquivos de texto especificamente, o OpenTextFileReader ajuda o usuário a entender qual fluxo usar.

Essas diretrizes não impedem princípios gerais de design para bibliotecas de classes. Em vez disso, são recomendações otimizadas para desenvolvedores que estão usando o Visual Basic e o namespace My. Para obter princípios gerais de design para criar bibliotecas de classes, confira Diretrizes de Design da Estrutura.

Empacotar e implantar extensões

Você pode incluir extensões de namespace My em um modelo de projeto do Visual Studio ou empacotar suas extensões e implantá-las como um modelo de item do Visual Studio. Ao empacotar suas extensões de namespace My como um modelo de item do Visual Studio, você pode aproveitar os recursos adicionais fornecidos pelo Visual Basic. Esses recursos permitem que você inclua uma extensão quando um projeto fizer referência a um assembly específico ou permitem que os usuários adicionem explicitamente sua extensão de namespace My usando a página Minhas Extensões do Designer de Projeto do Visual Basic.

Para obter detalhes sobre como implantar extensões de namespace My, confira Empacotando e implantando minhas extensões personalizadas.

Confira também