共用方式為


建立軟體開發套件

軟體開發套件 (SDK) 是您可以在 Visual Studio 中作為單一項目所參考的 API 集合。 [參考管理員] 對話方塊列出了與專案相關的所有 SDK。 當您將 SDK 新增至專案時,可以在 Visual Studio 中使用 API。

SDK 有兩種類型:

  • 平台 SDK 是開發平台應用程式的必要元件。 例如,開發 Windows 8.x 市集應用程式需要 Windows 8.1 SDK。

  • 延伸模組 SDK 是擴充平台的選用元件,但不是針對該平台開發應用程式的必要元件。

下列各節說明 SDK 的一般基礎結構,以及如何建立平台 SDK 和延伸模組 SDK。

平台 SDK

為平台開發應用程式必須使用平台 SDK。 例如,開發適用於 Windows 8.1 的應用程式需要 Windows 8.1 SDK。

安裝

所有平台 SDK 都會安裝在 HKLM\Software\Microsoft\Microsoft\Microsoft SDKs\[TPI]\v[TPV]\@InstallationFolder = [SDK 根目錄]。 因此,Windows 8.1 SDK 會安裝在 HKLM\Software\Microsoft\Microsoft SDKs\Windows\v8.1

版面配置

平台 SDK 具有下列設定:

\[InstallationFolder root]
            SDKManifest.xml
            \References
                  \[config]
                        \[arch]
            \DesignTime
                  \[config]
                        \[arch]
節點 描述
References 資料夾 包含二進位檔,其中包含可對其編碼的 API。 這些可能包含 Windows 中繼資料 (WinMD) 檔案或組件。
DesignTime 資料夾 包含只在執行前/偵錯階段才需要的檔案。 這些可能包含 XML 文件、程式庫、標頭、工具箱設計階段二進位檔、MSBuild 成品等等

在理想情況下,XML 文件會放在 \DesignTime 資料夾中,但供參考的 XML 文件會繼續放在 Visual Studio 中的參考檔案旁邊。 例如,參考 \References\[config]\[arch]\sample.dll 的 XML 文件會是 \References\[config]\[arch]\sample.xml,而該文件的當地語系化版本將會是 \References\[config]\[arch]\[locale]\sample.xml
Configuration 資料夾 只能有三個資料夾:Debug、Retail 和 CommonConfiguration。 無論 SDK 取用者將目標設定為何,如果應該取用相同的 SDK 檔案集,SDK 作者都可以將其檔案放在 CommonConfiguration 之下。
Architecture 資料夾 任何支援的 [architecture] 資料夾都可以存在。 Visual Studio 支援下列架構:x86、x64、ARM 和中立。 注意:Win32 對應至 x86,而 AnyCPU 對應至中立。

MSBuild 只會在平台 SDK 的 \CommonConfiguration\neutral 下尋找。
SDKManifest.xml 此檔案描述 Visual Studio 應該如何使用 SDK。 看看適用於 Windows 8.1 的 SDK 資訊清單:

<FileList DisplayName = "Windows" PlatformIdentity = "Windows, version=8.1" TargetFramework = ".NET for Windows Store apps, version=v4.5.1; .NET Framework, version=v4.5.1" MinVSVersion = "14.0"> <File Reference = "Windows.winmd"> <ToolboxItems VSCategory = "Toolbox.Default" /> </File> </FileList>

DisplayName:物件瀏覽器顯示在 [瀏覽] 清單中的值。

PlatformIdentity:這個屬性的存在會告知 Visual Studio 和 MSBuild,SDK 是平台 SDK,而且不應該將從它新增的參考複製在本機。

TargetFramework:Visual Studio 使用這個屬性來確保只有以此屬性值中指定的相同 Framework 為目標的專案才能取用 SDK。

MinVSVersion:Visual Studio 使用此屬性只取用套用至它的 SDK。

Reference:必須只針對包含控制項的參考指定這個屬性。 如需如何指定參考是否包含控制項的資訊,請參閱下方。

擴充功能 SDK

下列各節說明部署延伸模組 SDK 所需的動作。

安裝

延伸模組 SDK 可以針對特定使用者或所有使用者安裝,而無須指定登錄機碼。 若要為所有使用者安裝 SDK,請使用下列路徑:

%Program Files%\Microsoft SDKs<目標平台>\v<平台版本號碼>\ExtensionSDKs

對於使用者特定的安裝,請使用下列路徑:

%USERPROFILE%\AppData\Local\Microsoft SDKs<目標平台>\v<平台版本號碼>\ExtensionSDKs

如果您想要使用不同的位置,必須執行下列兩個動作之一:

  1. 在登錄機碼中指定:

    HKLM\Software\Microsoft\Microsoft SDKs<目標平台>\v<平台版本號碼>\ExtensionSDKs<SDKName><SDKVersion>\

    並新增具有 <path to SDK><SDKName><SDKVersion> 值的 (預設) 子機碼。

  2. 將 MSBuild 屬性 SDKReferenceDirectoryRoot 新增至您的專案檔。 這個屬性的值是以分號分隔的清單,您要參考的延伸模組 SDK 位於其中。

安裝配置

延伸模組 SDK 具有下列安裝配置:

\<ExtensionSDKs root>
           \<SDKName>
                 \<SDKVersion>
                        SDKManifest.xml
                        \References
                              \<config>
                                    \<arch>
                        \Redist
                              \<config>
                                    \<arch>
                        \DesignTime
                               \<config>
                                     \<arch>

  1. \<SDKName>\<SDKVersion>:延伸模組 SDK 的名稱和版本衍生自 SDK 根目錄路徑中的相對應資料夾名稱。 MSBuild 使用此身分識別在磁碟上尋找 SDK,而 Visual Studio 會在 [屬性] 視窗和 [參考管理員] 對話方塊中顯示此身分識別。

  2. References 資料夾:包含 API 的二進位檔。 這些可能是 Windows 中繼資料 (WinMD) 檔案或組件。

  3. Redist 資料夾:執行階段/偵錯所需的檔案,而且應該封裝為使用者應用程式的一部分。 所有二進位檔都應該放在 \redist\<config>\<arch> 底下,而且二進位檔名稱應具有下列格式,以確保唯一性:]<公司>.<產品>.<>.<延伸模組>。例如,*Microsoft.Cpp.Build.dll。 名稱可能與其他 SDK 的檔名相衝突的所有檔案 (例如,javascript、css、pri、xaml、png 和 jpg 檔案) 都應該放在 \redist\<config>\<arch>\<sdkname>* 底下,但與 XAML 控制項相關聯的檔案除外。這些檔案應該放在 *\redist\<config>\<arch>\<componentname>\ 下方。

  4. DesignTime 資料夾:只有在預先執行/偵錯階段才需要且不應該封裝為使用者應用程式的一部分的檔案。 這些可能是 XML 文件、程式庫、標頭、工具箱設計階段二進位檔、MSBuild 成品等等。 任何要供原生詹案取用的 SDK 都必須有 SDKName.props 檔案。 以下顯示這種類型的檔案範例。

    <?xml version="1.0" encoding="utf-8"?>
    <Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
      <PropertyGroup>
        <ExecutablePath>C:\Temp\ExecutablePath;$(ExecutablePath)</ExecutablePath>
        <IncludePath>$(FrameworkSDKRoot)\..\v8.1\ExtensionSDKs\cppimagingsdk\1.0\DesignTime\CommonConfiguration\Neutral\include;$(IncludePath)</IncludePath>
        <AssemblyReferencePath>C:\Temp\AssemblyReferencePath;(AssemblyReferencePath)</AssemblyReferencePath>
        <LibraryPath>$(FrameworkSDKRoot)\..\v8.1\ExtensionSDKs\cppimagingsdk\1.0\DesignTime\Debug\ARM;$(LibraryPath)</LibraryPath>
        <SourcePath>C:\Temp\SourcePath\X64;$(SourcePath)</SourcePath>
        <ExcludePath>C:\Temp\ExcludePath\X64;$(ExcludePath)</ExcludePath>
        <_PropertySheetDisplayName>DevILSDK, 1.0</_PropertySheetDisplayName>
      </PropertyGroup>
    </Project>
    
    

    XML 參考文件會放在參考檔案旁邊。 例如,\References\<config>\<arch>\sample.dll 組件的 XML 參考文件是 \References\<config>\<arch>\sample.xml,而該檔案的當地語系化版本是 \References\<config>\<arch>\<locale>\sample.xml

  5. Configuration 資料夾:三個子資料夾:Debug、Retail 和 CommonConfiguration。 無論 SDK 取用者將組態目標為何,當應該取用相同的 SDK 檔案集,SDK 作者都可以將其檔案放在 CommonConfiguration 之下。

  6. Architecture 資料夾:支援下列架構:x86、x64、ARM、中立。 Win32 對應至 x86,而 AnyCPU 對應至中立。

SDKManifest.xml

SDKManifest.xml 檔案描述 Visual Studio 如何使用 SDK。 以下是一個範例:

<FileList DisplayName = "My SDK"
          ProductFamilyName = "My SDKs"
          TargetFramework = ".NETCore, version=v4.5.1; .NETFramework, version=v4.5.1"
          MinVSVersion = "14.0"
          MaxPlatformVersion = "8.1"
          AppliesTo = "WindowsAppContainer + WindowsXAML"
          SupportPrefer32Bit = "True"
          SupportedArchitectures = "x86;x64;ARM"
          SupportsMultipleVersions = "Error"
          CopyRedistToSubDirectory = "."
          DependsOn = "SDKB, version=2.0"
          MoreInfo = "https://msdn.microsoft.com/MySDK">
  <File Reference = "MySDK.Sprint.winmd" Implementation = "XNASprintImpl.dll">
    <Registration Type = "Flipper" Implementation = "XNASprintFlipperImpl.dll" />
    <Registration Type = "Flexer" Implementation = "XNASprintFlexerImpl.dll" />
    <ToolboxItems VSCategory = "Toolbox.Default" />
  </File>
</FileList>

下列清單提供該檔案的元素:

  1. DisplayName:出現在 Visual Studio 使用者介面中參考管理員、方案總管、物件瀏覽器和其他位置的值。

  2. ProductFamilyName:整體 SDK 產品名稱。 例如,Windows Library for JavaScript (WinJS) SDK 的名稱為「Microsoft.WinJS.1.0」和「Microsoft.WinJS.2.0」,屬於同一系列 SDK 產品系列「Microsoft.WinJS」。 此屬性可讓 Visual Studio 和 MSBuild 建立該關聯。 如果此屬性不存在,SDK 名稱會當做產品系列名稱使用。

  3. FrameworkIdentity:指定一或多個 Windows 元件庫的相依性。 這個屬性的值會放入取用應用程式的資訊清單中。 此屬性僅適用於 Windows 元件庫。

  4. TargetFramework:指定參考管理員和工具箱中可用的 SDK。 這是以分號分隔的目標架構 Moniker 清單,例如 “.NET Framework, version=v2.0; .NET Framework, version=v4.5.1”。 如果指定了相同目標架構的數個版本,則參考管理員會使用指定的最低版本來進行篩選。 例如,如果指定 “.NET Framework, version=v2.0; .NET Framework, version=v4.5.1”,則參考管理員會使用 “.NET Framework, version=v2.0”。 如果指定了特定的目標架構設定檔,則只有參考管理員會使用該設定檔進行篩選。 例如,指定 "Silverlight, version=v4.0, profile=WindowsPhone" 時,參考管理員只會篩選 Windows Phone 設定檔;以完整 Silverlight 4.0 Framework 為目標的專案在參考管理員中看不到該 SDK。

  5. MinVSVersion:最低 Visual Studio 版本。

  6. MaxPlatformVerson:應該使用目標平台版本上限來指定延伸模組 SDK 無法運作的平台版本。 例如,只有 Windows 8 專案應該參考 Microsoft Visual C++ 執行階段套件 v11.0。 因此,Windows 8 專案的 MaxPlatformVersion 是 8.0。 這表示對於 Windows 8.1 專案,參考管理員會篩選出 Microsoft Visual C++ 執行階段套件,而 MSBuild 會在 Windows 8.1 專案參考時擲回錯誤。 注意:從 Visual Studio 2013 開始支援此元素。

  7. AppliesTo:藉由指定適用的 Visual Studio 專案類型,指定參考管理員中可用的 SDK。 可辨識九個值:WindowsAppContainer、VisualC、VB、CSharp、WindowsXAML、JavaScript、Managed 和 Native。 SDK 作者可以使用 and ("+"),or ("|"),not ("!") 運算子,來指定套用至 SDK 的專案類型範圍。

    WindowsAppContainer 會識別 Windows 8.x 市集應用程式的專案。

  8. SupportPrefer32Bit:支援的值為 “True” 和 “False”。 預設值為 "True"。 如果此值設定為 "False",如果參考 SDK 的專案已啟用 Prefer32Bit,MSBuild 會對 Windows 8.x 市集專案傳回錯誤 (或對桌面專案發出警告)。 如需 Prefer32Bit 的詳細資訊,請參閱建置頁面,專案設計工具 (C#)編譯頁面,專案設計工具 (Visual Basic)

  9. SupportedArchitectures:SDK 支援的架構清單 (以分號分隔)。 如果取用專案中的目標 SDK 架構不受支援,MSBuild 會顯示警告。 如果未指定此屬性,MSBuild 永遠不會顯示這類警告。

  10. SupportsMultipleVersions:如果此屬性設定為 ErrorWarning,MSBuild 會指出相同的專案無法參考相同 SDK 系列的多個版本。 如果此屬性不存在或設定為 Allow,MSBuild 就不會顯示這類的錯誤或警告。

  11. AppX:指定磁碟上 Windows 元件庫之應用程式套件的路徑。 此值會在本機偵錯期間傳遞至 Windows 元件庫的註冊元件。 檔名的命名慣例是 <公司>.<產品>.<架構>.<組態>.<版本>.appx。 如果組態和架構不適用於 Windows 元件庫,則組態和架構在屬性名稱和屬性值中是選擇性的。 此值僅適用於 Windows 元件庫。

  12. CopyRedistToSubDirectory:指定應該複製 \redist 資料夾下的檔案的應用程式套件根目錄的相對位置 (也就是「建立應用程式套件」精靈中選擇的 [套件位置]) 和執行階段配置根目錄。 預設位置是應用程式套件的根目錄和 F5 配置。

  13. DependsOn:定義此 SDK 所依賴 SDK 的 SDK 身分識別清單。 此屬性會出現在參考管理員的詳細資料窗格中。

  14. MoreInfo:提供說明和詳細資訊的網頁 URL。 此值用於參考管理員右窗格中的 [更多資訊] 連結。

  15. 註冊類型:指定應用程式資訊清單中的 WinMD 註冊,而且原生 WinMD 需要此項,其具有對應的實作 DLL。

  16. 檔案參考:僅針對包含控制項或原生 WinMD 的參考指定。 如需如何指定參考是否包含控制項的資訊,請參閱下方的指定工具箱項目的位置

指定工具箱項目的位置

SDKManifest.xml 結構描述的 ToolBoxItems 元素會指定平台和延伸模組 SDK 中工具箱項目的控制項名稱、來源組件和工具箱索引標籤名稱。 下列範例舉出各種案例。 這適用於 WinMD 或 DLL 參考。

請注意,在 Visual Studio 2019 和更早版本中,Visual Studio 不會在資訊清單中列出工具箱控制項名稱,而是動態列舉 SDK 元件中的控制項類型。 從 Visual Studio 2022 開始,不再支援這項功能;工具箱項目必須明確列在 SDKManifest.xml 中。

  1. 將控制項放在工具箱預設類別中。

    <File Reference = "sample.winmd">
      <ToolboxItems VSCategory = "Toolbox.Default">
        <Item Type = "Namespace.ControlName1" />
        <Item Type = "Namespace.ControlName2" />
      </ToolboxItems>
    </File>
    
  2. 將控制項放在特定類別名稱之下。

    <File Reference = "sample.winmd">
      <ToolboxItems VSCategory= "MyCategoryName">
        <Item Type = "Namespace.ControlName1" />
        <Item Type = "Namespace.ControlName2" />
      </ToolboxItems>
    </File>
    
  3. 將控制項放在特定類別名稱之下。

    <File Reference = "sample.winmd">
      <ToolboxItems VSCategory = "Graph">
        <Item Type = "Namespace.ControlName1" />
      </ToolboxItems>
      <ToolboxItems VSCategory = "Data">
        <Item Type = "Namespace.ControlName2" />
      </ToolboxItems>
    </File>
    
  4. 將控制項放在 Blend 和 Visual Studio 中的不同類別名稱之下。

    // Blend accepts a slightly different structure for the category name because it allows a path rather than a single category.
    <File Reference = "sample.winmd">
      <ToolboxItems VSCategory = "Graph" BlendCategory = "Controls/sample/Graph">
        <Item Type = "Namespace.ControlName1" />
        <Item Type = "Namespace.ControlName2" />
      </ToolboxItems>
    </File>
    
  5. 在 Blend 和 Visual Studio 中以不同的方式列舉特定控制項。

    <File Reference = "sample.winmd">
      <ToolboxItems VSCategory = "Graph">
        <Item Type = "Namespace.ControlName1" />
      </ToolboxItems>
      <ToolboxItems BlendCategory = "Controls/sample/Graph">
        <Item Type = "Namespace.ControlName2" />
      </ToolboxItems>
    </File>
    
  6. 列舉特定控制項,並將其放在 Visual Studio 通用路徑之下,或只放在 [所有控制項群組] 中。

    <File Reference = "sample.winmd">
      <ToolboxItems VSCategory = "Toolbox.Common">
        <Item Type = "Namespace.ControlName1" />
      </ToolboxItems>
      <ToolboxItems VSCategory = "Toolbox.All">
        <Item Type = "Namespace.ControlName2" />
      </ToolboxItems>
    </File>
    
  7. 列舉特定控制項,並且只顯示 ChooseItems 中的特定集合,而不會將它們放在工具箱中。

    <File Reference = "sample.winmd">
      <ToolboxItems VSCategory = "Toolbox.ChooseItemsOnly">
        <Item Type = "Namespace.ControlName1" />
        <Item Type = "Namespace.ControlName2" />
      </ToolboxItems>
    </File>