Partilhar via

Estendendo o My namespace no Visual Basic

  • Artigo

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

Personalizando membros de namespace existentes My

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

Por exemplo, suponha que você use frequentemente o My.User objeto 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 os usuários dentro da empresa. Nesse cenário, você pode substituir o My.User.CurrentPrincipal valor padrão da propriedade por uma instância de seu próprio objeto principal personalizado, conforme mostrado no exemplo a seguir:

My.User.CurrentPrincipal = CustomPrincipal

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

Adicionando membros a My objetos

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

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

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 My namespace

Embora o My namespace forneça soluções para muitas tarefas de programação comuns, você pode encontrar tarefas que o My namespace 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 My namespace para incluir soluções personalizadas para tarefas comuns específicas do seu ambiente. O My namespace pode ser facilmente estendido para adicionar novos membros para atender às crescentes necessidades do aplicativo. Além disso, você pode implantar suas My extensões de namespace para outros desenvolvedores como um modelo do Visual Basic.

Adicionando membros ao My namespace

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. Anote o módulo com o HideModuleName atributo como mostrado no exemplo a seguir. O HideModuleName atributo garante que o IntelliSense não exibirá o nome do módulo quando exibir os My membros do namespace.

Namespace My
  <HideModuleName()> 
  Module MyCustomModule

  End Module
End Namespace

Para adicionar membros ao My namespace, adicione propriedades conforme necessário ao módulo. Para cada propriedade adicionada ao My namespace, adicione um campo privado do tipo ThreadSafeObjectProvider(Of T), onde o tipo é o tipo retornado pela sua propriedade personalizada. Este campo é usado para criar instâncias de objeto thread-safe a serem retornadas pela propriedade chamando o GetInstance método. 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 My namespace:

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 My.Application objeto para expor eventos para seus objetos personalizados My estendendo a MyApplication classe parcial no My namespace. Para projetos baseados no Windows, você pode clicar duas vezes no nó Meu Projeto no Gerenciador de Soluções. No Visual Basic Project Designer, clique na guia Aplicativo e, em seguida, 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 MyApplication classe:

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 à MyApplication classe. Os eventos personalizados permitem que você adicione código que será executado quando um manipulador de eventos for adicionado, removido ou o evento for gerado. Observe que o código de um evento personalizado é executado somente se o AddHandler código for adicionado por um usuário para manipular o evento. Por exemplo, considere que o SampleExtension objeto da seção anterior tem um Load evento 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 My.SampleExtension.Load evento ocorrer. Quando o código é adicionado para manipular o novo My.SampleExtensionLoad evento, a AddHandler parte desse código de evento personalizado é executada. O MyApplication_SampleExtensionLoad método é incluído no exemplo de código para mostrar um exemplo de um manipulador de eventos que manipula o My.SampleExtensionLoad evento. Observe que o SampleExtensionLoad evento estará disponível quando você selecionar a opção Meus eventos de aplicativo na lista suspensa à esquerda acima do Editor de Códigos quando 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

Orientações de design

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

  • Inclua apenas a lógica de extensão. A lógica incluída na extensão de My namespace deve incluir apenas o código necessário para expor a funcionalidade necessária no My namespace. Como sua extensão residirá em projetos de usuário como código-fonte, atualizar o componente de extensão incorre em um alto custo de manutenção e deve ser evitado, se possível.
  • Minimize as suposições do projeto. Ao criar suas extensões do namespace, não assuma um conjunto de referências, importações no nível do projeto ou configurações específicas do My compilador (por exemplo, Option Strict off). Em vez disso, minimize as dependências e qualifique totalmente todas as referências de tipo usando a Global palavra-chave. Além disso, certifique-se de que a extensão compila com Option Strict on para minimizar erros na extensão.
  • Isole o código da 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, consulte "Empacotando e implantando extensões" posteriormente neste tópico. Colocar todo o código de extensão de My namespace em um único arquivo ou uma pasta separada em um projeto também ajudará os usuários a localizar a extensão de My namespace.

Projetando bibliotecas de classes para My

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

  • Métodos sem estado. Os métodos no My namespace devem fornecer uma solução completa para uma tarefa específica. Certifique-se de que os valores de parâmetro que são passados para o método forneçam toda a entrada necessária 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 My namespace é global para o projeto. Por exemplo, My.Application.Info encapsula o estado que é compartilhado em todo o aplicativo.
  • Tipos de parâmetros simples. Mantenha as coisas simples, evitando tipos de parâmetros complexos. Em vez disso, crie métodos que não usem 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 My namespace 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.OpenTextFileReadero . 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.

Estas diretrizes não excluem 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 My namespace. Para obter princípios gerais de design para a criação de bibliotecas de classes, consulte Framework Design Guidelines.

Empacotamento e implantação de extensões

Você pode incluir My extensões de namespace em um modelo de projeto do Visual Studio ou pode empacotar suas extensões e implantá-las como um modelo de item do Visual Studio. Quando você empacota suas My extensões de namespace 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 faz referência a um assembly específico ou permite que os usuários adicionem explicitamente sua My extensão de namespace usando a página Minhas extensões do Designer de Projeto do Visual Basic.

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

Consulte também