逐步解說：建立值控制項擴充功能

發行項
06/10/2015

本逐步解說示範如何建立 LightSwitch 的值控制項延伸。您可以使用值控制項顯示某個實體的單一欄位在 LightSwitch 螢幕的。值控制項通常是設計用來與一組使用資料型別。例如，您可以在 LightSwitch 使用文字方塊控制項的顯示字串和數字不是型別，但不是二進位資料。

若要建立值控制項的擴充功能，您必須執行下列工作：

建立控制項擴功能的專案.
指定支援的資料型別。
對 LightSwitch 資料繫結。
允許使用者程式碼存取控制項。
加入唯讀支援。
測試值控制項。

必要條件

Visual Studio 2013 Professional
Visual Studio 2013 SDK
Visual Studio 2013 的 LightSwitch 擴充性工具組

建立控制項擴充功能的專案

第一步就是建立專案並加入 [控制項] 範本。

建立擴充功能專案

在 Visual Studio的功能表列，選擇 [ 檔案]，新增，專案。
在 [新的專案] 對話方塊中，展開 [Visual Basic] 或 [Visual C#] 節點，然後展開 [LightSwitch] 節點，選取 [擴充性] 節點，然後選取 [LightSwitch 擴充程式庫] 範本。
在 [名稱] 欄位中，輸入 ValueControlExtension 做為擴充功能程式庫的名字。這個名稱會出現在 LightSwitch [應用程式設計工具] 的 [擴充功能] 索引標籤。
選擇 [好] 按鈕以建立方案，其包含七個擴充功能所需的專案。

選取擴充功能類型

在 [方案總管] 中，開啟 [ValueControlExtension.Lspkg] 專案的捷徑功能表，然後選擇 [以...開啟]。
在 [開啟檔案] 對話方塊中，選取 [XML (文字) 編輯器]，然後選擇 [好] 按鈕。
在功能表列中，選擇 [專案]、[加入新項目]。
在 [加入新項目] 對話方塊中，選擇 [控制項]。
在 [名稱] 欄位中，輸入 ValueControl 做為擴充功能的名字。這個名稱會出現在 LightSwitch 螢幕設計工具上。
選擇 [確定] 按鈕。檔案會加入至您方案中的數個專案。

更新控制項圖示。

這兩個名為 [ValueControl.png] 的影像檔案已加入至您的方案：一個在 [ValueControlExtension.Client.Design] 專案的 [ControlImages] 資料夾，其他在 [ValueControlExtension.Design] 專案的 [ControlImages] 資料夾。檔案中的影像會顯示為圖示。您可以使用其他影像取代預設的控制項影像。

修改圖示影像

在 [方案總管] 中， [ValueControlExtension.Client.Design] 專案的 [ ControlImages] 資料夾，開啟[ValueControl.png]檔案的功能表並選取 [開啟檔案]。
在 [開啟檔案] 對話方塊中，選取 [繪製]，然後選擇 [好] 按鈕。
在繪製中變更影像；舉例來說，在變更色彩或添加圖形後，儲存檔案並傳回 Visual Studio。
選取 [ValueControl.png] 檔案，然後在功能表列上，選擇 [編輯] 後，按下 [複製]。
選取 [ValueControlExtension.Design] 專案的 [ControlImages] 資料夾，然後在功能表列上，選擇 [編輯] 後，按下 [貼上]。在詢問您是否要取代檔案的訊息中，請選擇 [是] 按鈕。

指定支援的資料型別。

每個控制項有所識別的 SupportedDataTypes 集合的資料型別控制項可以顯示。使用模組名稱和資料型別的名稱，您必須指定這項資訊。對於企業會編碼成相同的擴充功能，您必須指定企業類型的名稱。您可以使用「: 」做為 Microsoft.LightSwitch:的捷徑。如需所支援資料類型的清單，請參閱支援 LightSwitch 擴充功能的資料類型。

您為 SupportedDataTypes只指定不可為 null 的型別，不過，您的控制項也必須支援您指定任何資料型別的可為 null 的版本。

指定支援的資料型別

在 [方案總管] 中，在 [中繼資料] 中開啟 [ValueControl.lsml] 檔案， [ [ValueControlExtension.Common] 專案的 [控制項] 資料夾。

尋找 <Control.SupportedDataTypes> 項目，並且加入下列程式碼至 <SupportedDataType DataType=":String"/> 項目後方。

<SupportedDataType DataType=":Boolean"/>
      <SupportedDataType DataType=":Byte"/>
      <SupportedDataType DataType=":DateTime"/>
      <SupportedDataType DataType=":Decimal"/>
      <SupportedDataType DataType=":Double"/>
      <SupportedDataType DataType=":Guid"/>
      <SupportedDataType DataType=":Int16"/>
      <SupportedDataType DataType=":Int32"/>
      <SupportedDataType DataType=":Int64"/>
      <SupportedDataType DataType=":SByte"/>
      <SupportedDataType DataType=":Single"/>

對於中定義的每個實體欄位相同的任何一種資料型別， [ValueControl] 會顯示與螢幕設計工具的選項。

對 LightSwitch 資料繫結。

基本的 Silverlight 控制項必須指定它如何繫結至並顯示 LightSwitch 應用程式的資料。LightSwitch 提供 IContentItem 做為資料內容為每個控制項。此內容項目所要顯示的包含資料和中繼資料，例如屬性、 DisplayName，以及資料是否已載入。 IContentItem 也有 Value 和包含實際目前資料控制項的 StringValue 屬性。

您的 Silverlight 控制項必須包含對 LightSwitch.Presentation.Framework 命名空間的參考，提供一些常見的預先製作好建置組塊的控制項。例如， LightSwitch 提供可用來顯示載入資訊和驗證錯誤的 StatesControl 。

繫結至資料

在 [方案總管] 中，在 [簡介] 中開啟 [ValueControl.xaml] 檔案， [ [ValueControlExtension.Client] 專案的 [控制項] 資料夾。

在 xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml" 檔後加入下列命名空間宣告。

xmlns:framework ="clr-namespace:Microsoft.LightSwitch.Presentation.Framework;assembly=Microsoft.LightSwitch.Client"

使用下列 XAML 取代 <TextBox Text="{Binding StringValue, Mode=TwoWay}"/> 項目。

<!-- 
    Bind two-way to StringValue, which will enable automatic conversion and validation from or to any of the supported data types,
    and will also automatically support Choice lists.
    You also bind several alignment properties, so the control will honor what the application developer sets in the property sheet.
    The tooltip is bound to the description provided by the application developer.

    We also put the TextBox inside StatesControl, so we can show loading states or errors correctly.
    -->
    <framework:StatesControl HorizontalAlignment="Stretch">
        <TextBox x:Name="TextBox" Text="{Binding StringValue, Mode=TwoWay}"
             TextAlignment="{Binding Properties[Microsoft.LightSwitch:RootControl/TextAlignment]}"
             HorizontalAlignment="Stretch"
             ToolTipService.ToolTip="{Binding Description}"/>
    </framework:StatesControl>

繫結至 StringValue 控制項提供建議，例如 TextBox，就會顯示許多資料型別，因為它會自動轉換資料型別有最佳驗證支援。它也會處理所有自動格式化，例如顯示選擇清單中的顯示名稱 (而非傳回值)。非資料控制項，例如 CheckBox，可以繫結至 Value。工具提示會繫結至應用程式開發人員指定的描述。 TextAlignment 繫結至 TextAlignment 屬性的值。最後， TextBox 放置在 StatesControl 內，以便 LightSwitch 會正確地顯示載入和錯誤狀態。

允許使用者程式碼存取控制項。

LightSwitch 可讓開發人員在事件可以從其熒螢幕密碼直接存取 Silverlight 控制項和登記從控制項或直接、設定屬性上的 FindControl() 方法。為了讓這個方法時，控制項必須指定使用哪個內部 Silverlight 控制項開發人員應該互動。一般而言， LightSwitch 控制項應該傳回熟悉的 Silverlight 控制項加入至這個方法。 StatesControl 在範例中，開發人員與內部 TextBox 控制項互動。

啟用對使用者程式碼的存取。

在 [方案總管] 中，在 [簡介] 中， [ [ValueControlExtension.Client] 專案的 [控制項] 資料夾，開啟 [ValueControl.xaml.vb] 或 [ValueControl.xaml.cs] 程式碼後置檔案。

加入下列程式碼以實作 IContentVisual 介面。

Public Partial Class ValueControl
    Inherits UserControl
    Implements IContentVisual

public partial class ValueControl : UserControl, IContentVisual

加入介面的基底實作。
```
Public ReadOnly Property Control As Object Implements Microsoft.LightSwitch.Presentation.IContentVisual.Control
            Get
                Return Me.TextBox
            End Get
        End Property

        Public Sub Show() Implements Microsoft.LightSwitch.Presentation.IContentVisual.Show
         End Sub
```
```
object IContentVisual.Control
        {
            get { return this.TextBox; }
        }

        void IContentVisual.Show()
        {
        }
```
介面的實作通常非常簡單。大部分的控制項必須實作只 Control 屬性。如果控制項，例如展開器，其設計是要隱藏一部分的 User Interface (UI)，您可以使用 Show 方法會顯示該區段。

某些控制項會比控制項的內部 Silverlight 控制項更複雜的存留期。例如，強制回應視窗控制項可能不會創造實際 Silverlight 視窗，直到它的按鈕被按下。對於這種，在內部控制項可以或無法使用時，在這種情況下，您應該實作 INotifyControlChanged 呼叫 LightSwitch。

加入唯讀支援。

LightSwitch 開發人員必須能夠使用控制項顯示使用者無法編輯的資料。在某些情況下，視使用者為控制項應該成為唯讀的資料已登入或在螢幕的額外留意邏輯。您可以藉由設定 IsReadOnly 屬性的值指定控制項的唯讀狀態的 IContentItem 物件，是控制項的資料內容。

加入唯讀支援。

在 [方案總管] 中，在 [簡介]， [ValueControlExtension.Client] 專案的 [控制項] 資料夾中，開啟 [ ValueControl.xaml] 檔案，。
將 TextBox x:Name="TextBox" Text="{Binding StringValue, Mode=TwoWay}" 項目之後的下列繫結項目。
```
IsReadOnly="{Binding IsReadOnly}"
```
根據控制項而定，您可能為 IsReadOnly需要不同的行為。您可能必須停用某些或所有控制項。在文字方塊中的簡單範例中， IContentItem 的 IsReadOnly 屬性繫結至文字方塊的 IsReadOnly 屬性。

此時值控制完成，因此，您可以測試在 LightSwitch。

測試值控制項。

您可以在 Visual Studio的實驗執行個體中，測試值控制項。如果您尚未測試其他 LightSwitch 擴充性專案，您必須先啟用實驗執行個體。

啟用實驗執行個體

在 [方案總管] 中，選擇 [BusinessTypeExtension.Vsix] 專案。
選擇功能表列上的 [專案]、[BusinessTypeExtension.Vsix 屬性]。
在 [偵錯] 索引標籤的 [啟動動作] 底下，選取 [啟動外部程式]。
輸入 Visual Studio 可執行檔 devenv.exe 的路徑。

在 32 位元系統上，預設路徑是 C:\Program Files\Microsoft Visual Studio 12.0\Common7\IDE\devenv.exe；在 64 位元系統上，則是 C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\devenv.exe。
在 [命令列引數] 欄位中，輸入 /rootsuffix Exp。

注意事項

所有後續的 LightSwitch 擴充性專案也會預設使用這個設定。

注意事項
所有後續的 LightSwitch 擴充性專案也會預設使用這個設定。

若要測試詳細資料控制項

在功能表列上，選擇 [偵錯]、[開始偵錯]。 Visual Studio 的實驗執行個體隨即開啟。
在 [新增專案] 對話方塊中，展開 [Visual Basic] 或 [Visual C#] 節點，然後選擇 [LightSwitch] 節點，再選擇 [LightSwitch 桌面應用程式] 範本。
在 [名稱] 欄位中，輸入 ValueControlTest，然後選擇 [好] 按鈕以建立測試專案。
在選擇功能表列上，選擇 [專案]、[ValueControlTest 屬性]。
在專案設計工具中，請在 [擴充功能] 索引標籤上，選取 [ValueControlExtension] 核取方塊。
建立具有資料表包含各種資料型別的欄位，包括 String 和 DateTime的基底 LightSwitch 應用程式。
將 [清單和詳細資料] 畫面，然後螢幕設計工具中，變更其中一個 [TextBox] 控制項 String 欄位設為 [ValueControl]。
在功能表列上，選擇 [偵錯]、[開始偵錯]。檢視 [ValueControl] 控制項的行為在應用程式並確認文字能適當地顯示。
開啟執行階段螢幕設計工具並變更其中一個 [DateTimePicker] 控制項 DateTime 欄位設為 [ValueControl]。確認 [ValueControl] 指定目前支援的資料型別。

後續步驟

現在完成了值控制項逐步解說；您應該可以在任何的 LightSwitch 專案中，重複使用控制項的擴充功能。這是值控制項的一個例子；您可以建立稍微不同的控制項外觀或行為。相同的基本步驟及原則適用於所有值控制項，但在其他情況套用其他的概念。例如，您可能想要處理驗證錯誤或支援編輯 DataGrid 控制項中。如需詳細資訊，請參閱其他 LightSwitch 控制項概念。

如果您散發您的控制項擴充功能，有幾個要採用的詳細步驟。若要確定您的擴充功能所顯示的資訊在 [專案設計工具] 和 [增益集管理員] 是正確的，您必須更新 VSIX 套件的屬性。如需詳細資訊，請參閱如何：設定 VSIX 套件屬性。此外，在您公開發佈您的擴充功能時，請務必考慮以下幾點事項。如需詳細資訊，請參閱如何：散發 LightSwitch 擴充功能。