My Расширение пространства имен в Visual Basic

Пространство My имен в Visual Basic предоставляет свойства и методы, которые позволяют легко воспользоваться преимуществами платформы .NET Framework. Пространство My имен упрощает распространенные проблемы программирования, часто сокращая сложную задачу до одной строки кода. Кроме того, пространство имен My полностью расширяемо, так что вы можете настроить поведение My и добавить новые службы в его иерархию, чтобы адаптироваться к конкретным потребностям приложения. В этом разделе обсуждается настройка существующих членов пространства имен My и добавление собственных пользовательских классов в пространство имен My.

Настройка существующих My элементов пространства имен

Пространство My имен в Visual Basic предоставляет часто используемые сведения о вашем приложении и компьютере, а также многое другое. Полный список объектов в пространстве имен см. в My разделе "Моя ссылка". Возможно, необходимо настроить существующие члены My пространства имен, чтобы они лучше соответствовали потребностям приложения. Любое свойство объекта в My пространстве имен, которое не доступно только для чтения, можно задать для пользовательского значения.

Например, предположим, что вы часто используете объект My.User для доступа к текущему контексту безопасности пользователя, выполняющего ваше приложение. Однако ваша компания использует настраиваемый объект пользователя для предоставления дополнительных сведений и возможностей для пользователей внутри компании. В этом сценарии можно заменить значение My.User.CurrentPrincipal по умолчанию свойства экземпляром собственного пользовательского основного объекта, как показано в следующем примере:

My.User.CurrentPrincipal = CustomPrincipal

Установка свойства CurrentPrincipal на объекте My.User изменяет идентификатор, от имени которого выполняется приложение. Объект My.User , в свою очередь, возвращает сведения о только что указанном пользователе.

Добавление элементов в My объекты

Типы, возвращаемые из My.Application и My.Computer определяются как Partial классы. Таким образом, можно расширить My.Application и My.Computer объекты, создав Partial класс с именем MyApplication или MyComputer. Класс не может быть классом Private . Если вы указываете класс как часть пространства имен My, можно добавить свойства и методы, которые будут включены в объекты My.Application или My.Computer.

В следующем примере свойство с именем DnsServerIPAddresses добавляется к объекту 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

Добавление пользовательских объектов в My пространство имен

My Хотя пространство имен предоставляет решения для многих распространенных задач программирования, вы можете столкнуться с задачами, которые My пространство имен не обрабатывает. Например, приложение может получить доступ к пользовательским службам каталогов для пользовательских данных, или приложение может использовать сборки, которые не установлены по умолчанию с Visual Basic. Пространство имен можно расширить My , чтобы включить пользовательские решения для распространенных задач, относящихся к вашей среде. Пространство My имен можно легко расширить, чтобы добавить новых членов в соответствии с растущими потребностями приложения. Кроме того, вы можете развернуть My расширения пространства имен для других разработчиков, используя шаблон Visual Basic.

Добавление элементов в My пространство имен

Так как My это пространство имен, как и любое другое пространство имен, вы можете добавить в него свойства верхнего уровня, просто добавив модуль и указав значение NamespaceMy. Заметите модуль атрибутом HideModuleName , как показано в следующем примере. Атрибут HideModuleName гарантирует, что IntelliSense не будет отображать имя модуля при отображении элементов My пространства имен.

Namespace My
  <HideModuleName()> 
  Module MyCustomModule

  End Module
End Namespace

Чтобы добавить члены в пространство имен My, при необходимости добавьте свойства в модуль. Для каждого свойства, добавленного в пространство имен My, добавьте закрытое поле типа ThreadSafeObjectProvider(Of T), где ThreadSafeObjectProvider(Of T) — это тип, возвращаемый вашим пользовательским свойством. Это поле используется для создания потокобезопасных экземпляров объектов, возвращаемых свойством, вызывая метод GetInstance. В результате каждый поток, обращаюющийся к расширенному свойству, получает собственный экземпляр возвращаемого типа. В следующем примере добавляется свойство с именем SampleExtension типа SampleExtension в 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

Добавление событий в пользовательские My объекты

Вы можете использовать объект My.Application для вызова событий для пользовательских объектов My путем расширения частичного класса MyApplication в пространстве имен My. Для проектов под управлением Windows можно дважды щелкнуть узел "Мой проект " для проекта в обозревателе решений. В конструкторе проектов Visual Basic перейдите на вкладку "Приложение " и нажмите кнопку "Просмотреть события приложения ". Будет создан новый файл с именем ApplicationEvents.vb . Он содержит следующий код для расширения MyApplication класса:

Namespace My
  Partial Friend Class MyApplication
  End Class
End Namespace

Можно добавить обработчики событий для пользовательских My объектов, добавив пользовательские обработчики событий в MyApplication класс. Кастомные события позволяют вам добавлять код, который будет выполняться при добавлении или удалении обработчика событий, а также при вызове самого события. Обратите внимание, что код для настраиваемого события выполняется только в том случае, AddHandler если пользователь добавляет код для обработки события. Например, рассмотрим, что SampleExtension объект из предыдущего раздела имеет Load событие, для которого требуется добавить настраиваемый обработчик событий. В следующем примере кода показан настраиваемый обработчик событий с именем SampleExtensionLoad , который будет вызываться при возникновении My.SampleExtension.Load события. При добавлении кода для обработки нового My.SampleExtensionLoad события AddHandler выполняется часть этого пользовательского кода события. Метод MyApplication_SampleExtensionLoad включен в пример кода, чтобы показать пример обработчика событий, обрабатывающего My.SampleExtensionLoad событие. Обратите внимание, что SampleExtensionLoad событие будет доступно при выборе параметра "Мои события приложения " в раскрывающемся списке слева над редактором кода при редактировании файла 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

Рекомендации по проектированию

При разработке расширений в My пространстве имен используйте следующие рекомендации, чтобы свести к минимуму расходы на обслуживание компонентов расширения:

• Включите только логику расширения. Логика My , включенная в расширение пространства имен, должна содержать только код, необходимый для предоставления необходимых функций в My пространстве имен. Так как расширение будет находиться в пользовательских проектах в качестве исходного кода, обновление компонента расширения влечет за собой высокую стоимость обслуживания и следует избегать, если это возможно.
• Свести к минимуму предположения о проекте. При создании расширений пространства имен My не следует предполагать наличие набора ссылок, импорта на уровне проекта или конкретных настроек компилятора (например, Option Strict отключен). Вместо этого сведите к минимуму зависимости и полностью укажите все ссылки на тип с помощью ключевого Global слова. Кроме того, убедитесь, что расширение компилируется вместе с Option Strict тем, чтобы свести к минимуму ошибки в расширении.
• Изолируйте код расширения. Размещение кода в одном файле упрощает развертывание расширения в виде шаблона элемента Visual Studio. Дополнительные сведения см. в разделе "Упаковка и развертывание расширений" далее в этом разделе. Размещение всего кода расширения пространства имен в одном файле или отдельной папке в проекте также поможет пользователям найти расширение пространства имен.

Проектирование библиотек классов для My

Как и в большинстве объектных моделей, некоторые шаблоны проектирования хорошо работают в My пространстве имен, а другие — нет. При проектировании расширения в My пространстве имен следует учитывать следующие принципы:

• Методы без отслеживания состояния. Методы в My пространстве имен должны предоставлять полное решение для конкретной задачи. Убедитесь, что значения параметров, передаваемые методу, предоставляют все входные данные, необходимые для выполнения конкретной задачи. Избегайте создания методов, которые зависят от предыдущего состояния, например открытых подключений к ресурсам.
• Глобальные инстанции. Единственное состояние, которое сохраняется в My пространстве имен, является глобальным для проекта. Например, My.Application.Info инкапсулирует состояние, общее для всего приложения.
• Простые типы параметров. Не используйте сложные типы параметров. Вместо этого создайте методы, которые либо не принимают входные данные параметров, либо которые принимают простые типы входных данных, такие как строки, примитивные типы и т. д.
• Фабричные методы. Некоторые типы по своей природе сложно инстанцировать. Предоставление методов фабрики в качестве расширений My в пространстве имен позволяет более просто обнаруживать и использовать типы, которые попадают в эту категорию. Пример метода фабрики, который хорошо работает, — это My.Computer.FileSystem.OpenTextFileReader. В .NET Framework доступно несколько типов потоков. Указывая текстовые файлы, OpenTextFileReader помогает пользователю понять, какой поток следует использовать.

Эти рекомендации не исключают общие принципы проектирования для библиотек классов. Скорее, они являются рекомендациями, оптимизированными для разработчиков, использующих Visual Basic и My пространство имен. Общие принципы проектирования для создания библиотек классов см. в руководстве по проектированию платформы.

Упаковка и развертывание расширений

Можно включить расширения пространства имен My в шаблон проекта Visual Studio или упаковать и развернуть их в виде шаблона элемента Visual Studio. Упаковав расширения пространства имен My в качестве шаблона элемента Visual Studio, вы можете воспользоваться дополнительными возможностями, предоставляемых Visual Basic. Эти возможности позволяют добавить расширение, если проект ссылается на определенную сборку, или позволить пользователям явное добавление расширения пространства имен с помощью страницы My.

Дополнительные сведения о развертывании My расширений пространства имен см. в статье "Упаковка и развертывание пользовательских расширений".

См. также

• Упаковка и развертывание пользовательских расширений
• Расширение модели приложений Visual Basic
• Настройка объектов, доступных в my
• Страница "Мои расширения", конструктор проектов
• страница приложения, конструктор проектов (Visual Basic)
• Частично