共用方式為

擴充 Visual Basic 中的 My 命名空間

  • 發行項

Visual Basic 中的 My 命名空間會公開屬性和方法，讓您輕鬆利用 .NET Framework 的強大功能。 My 命名空間可簡化常見的程式設計問題，通常可將困難的工作縮減為一行程式碼。 此外，My 命名空間完全可延伸，因此您可以自訂 My 的行為，並將新的服務新增至其階層，以因應特定的應用程式需求。 本主題討論如何自訂 My 命名空間的現有成員，以及如何將您的自訂類別新增至 My 命名空間。

自訂現有的 My 命名空間成員

Visual Basic 中的 My 命名空間會公開關於應用程式、您的電腦等常用資訊。 如需My 命名空間中物件的完整清單，請參閱 My 參考。 您可能需要自訂 My 命名空間的現有成員，使其更符合應用程式的需求。 My 命名空間中非唯讀物件的任何屬性都可以設定為自訂值。

例如，假設您經常使用 My.User 物件來存取執行應用程式使用者的目前資訊安全性內容。 但您的公司使用自訂使用者物件來公開公司內使用者的其他資訊和功能。 在此情況中，您可以將 My.User.CurrentPrincipal 屬性的預設值取代為您自訂主體物件的執行個體，如下列範例所示：

My.User.CurrentPrincipal = CustomPrincipal

在 My.User 物件上設定 CurrentPrincipal 屬性會變更執行應用程式的身分識別。 My.User 物件接著會傳回新指定使用者的相關資訊。

將成員新增至 My 物件

從 My.Application 和 My.Computer 傳回的類型會定義為 Partial 類別。 因此，您可以建立名為 MyApplication 或 MyComputer 的 Partial 類別來擴充 My.Application 和 My.Computer 物件。 類別不可是 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 就像其他命名空間一樣，所以只要新增模組並指定 My 的 Namespace，即可將最上層屬性加入其中。 使用 HideModuleName 屬性標註模組，如下列範例所示。 HideModuleName 屬性可確保 IntelliSense 在顯示 My 命名空間的成員時，不會顯示模組名稱。

Namespace My
  <HideModuleName()> 
  Module MyCustomModule

  End Module
End Namespace

若要將成員新增至 My 命名空間，請視需要將屬性新增至模組。 針對新增至 My 命名空間的每個屬性，請新增 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 物件的事件，方法是擴充 My 命名空間中的 MyApplication 部分類別。 針對以 Windows 為基礎的專案，您可以針對專案中的 [我的專案] 節點按兩下 [方案總管]。 在 Visual Basic 專案設計工具中，按一下 [應用程式] 索引標籤，然後按一下 [檢視應用程式事件] 按鈕。 隨即會建立名為 ApplicationEvents.vb 的新檔案。 該檔案會包含下列程式碼用於擴充 MyApplication 類別：

Namespace My
  Partial Friend Class MyApplication
  End Class
End Namespace

您可以將自訂事件處理常式新增至 MyApplication 類別，以新增自訂 My 物件的事件處理常式。 自訂事件可讓您新增程式碼，用於在新增、移除事件處理常式或引發事件時執行。 請注意，只有在使用者新增程式碼來處理事件時，才會執行自訂事件的 AddHandler 程式碼。 例如，假設上一節中的 SampleExtension 物件有您想要新增自訂事件處理常式的 Load 事件。 下列程式碼範例顯示名為 SampleExtensionLoad 的自訂事件處理常式，在 My.SampleExtension.Load 事件發生時會叫用該處理常式。 新增程式碼以處理新的 My.SampleExtensionLoad 事件時，將會執行這個自訂事件程式碼的 AddHandler 部分。 MyApplication_SampleExtensionLoad 方法會包含在程式碼範例中，以顯示處理 My.SampleExtensionLoad 事件的事件處理常式範例。 請注意，在編輯 ApplicationEvents.vb 檔案時，當您從程式碼編輯器上方的左側下拉式清單中選取 [我的應用程式事件] 選項時，系統便會提供 SampleExtensionLoad 事件。

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 命名空間中的方法應該提供特定工作的完整解決方案。 請確定傳遞至方法的參數值會提供完成特定工作所需的所有輸入。 避免建立依賴先前狀態的方法，例如對資源的開放連線。
  • 全域執行個體。 My 命名空間中唯一受維護的狀態是專案的全域狀態。 例如，My.Application.Info 會封裝整個應用程式共用的狀態。
  • 簡化參數型別。 避免複雜的參數型別，讓專案保持簡單。 作為替代，請建立不採用任何參數輸入的方法，或採用簡單輸入型別，例如字串、簡單型別等等。
  • Factory 方法。 某些型別不可避免地較難具現化。 請提供 Factory 方法做為 My 命名空間的延伸模組，以便更輕鬆地探索和使用屬於此類別的型別。 正常運作的 Factory 方法範例之一為 My.Computer.FileSystem.OpenTextFileReader。 .NET Framework 中提供數種資料流型別。 藉由特別指定具體的文字檔，OpenTextFileReader 可協助使用者了解要使用的資料流。

這些指導方針不會排擠類別庫的一般設計原則。 相反地，這些指導方針是針對使用 Visual Basic 和 My 命名空間的開發人員最佳化建議。 如需建立類別庫的一般設計原則，請參閱架構設計指導方針。

封裝和部署延伸模組

您可以在 Visual Studio 專案範本中包含 My 命名空間延伸模組，也可以封裝延伸模組，並將其部署為 Visual Studio 專案範本。 如果將 My 命名空間延伸模組封裝為 Visual Studio 專案範本，便可以利用 Visual Basic 所提供的其他功能。 這些功能可讓您在專案參考特定元件時包含延伸模組，或讓使用者使用 Visual Basic 專案設計工具的 [My 擴充] 頁面明確新增 My 命名空間延伸模組。

如需部署 My 命名空間延伸模組的詳細資訊，請參閱封裝及部署自訂的 My 延伸模組。

另請參閱