Создание комплекта SDK
Пакет средств разработки программного обеспечения (SDK) — это коллекция API, на которые можно ссылаться как на один элемент в Visual Studio. В диалоговом окне диспетчера ссылок перечислены все пакеты SDK, относящиеся к проекту. При добавлении пакета SDK в проект API доступны в Visual Studio.
Существует два типа пакетов SDK:
Пакеты SDK платформы являются обязательными компонентами для разработки приложений для платформы. Например, пакет SDK для Windows 8.1 требуется для разработки приложений Магазина Windows 8.x.
Пакеты SDK расширения — это необязательные компоненты, расширяющие платформу, но не являются обязательными для разработки приложений для этой платформы.
В следующих разделах описывается общая инфраструктура пакетов SDK и создание пакета SDK для платформы и пакета SDK расширения.
Пакеты SDK для платформ
Пакеты SDK платформы необходимы для разработки приложений для платформы. Например, пакет SDK для Windows 8.1 требуется для разработки приложений для Windows 8.1.
Установка
Все пакеты SDK для платформы будут установлены в HKLM\Software\Microsoft\Microsoft SDK\[TPI]\v[TPV]\@InstallationFolder = [корневой каталог ПАКЕТА SDK]. Соответственно, пакет SDK для Windows 8.1 устанавливается в HKLM\Software\Microsoft\Microsoft SDKs\Windows\v8.1.
Макет
Пакеты SDK для платформы имеют следующий макет:
\[InstallationFolder root]
SDKManifest.xml
\References
\[config]
\[arch]
\DesignTime
\[config]
\[arch]
| Узел | Description |
|---|---|
| Папка ссылок | Содержит двоичные файлы, содержащие API-интерфейсы, которые можно закодировать. К ним могут относиться файлы или сборки метаданных Windows (WinMD). |
| Папка DesignTime | Содержит файлы, необходимые только во время предварительного выполнения или отладки. К ним могут относиться XML-документы, библиотеки, заголовки, двоичные файлы панели элементов во время разработки, артефакты MSBuild и т. д. Xml-документы, в идеале, будут помещены в папку \DesignTime , но XML-документы для ссылок будут по-прежнему размещаться вместе с эталонным файлом в Visual Studio. Например, XML-документ для ссылки\References\[config]\[arch]\sample.dll будет \References\[config]\[arch]\sample.xml, а локализованная версия этого документа будет \References\[config]\[arch]\[locale]\sample.xml. |
| Папка конфигурации | Существует только три папки: отладка, розничная торговля и CommonConfiguration. Авторы пакета SDK могут поместить свои файлы в CommonConfiguration , если тот же набор файлов SDK должен использоваться независимо от конфигурации, на которую будет нацелен потребитель пакета SDK. |
| Папка архитектуры | Может существовать любая поддерживаемая папка архитектуры . Visual Studio поддерживает следующие архитектуры: x86, x64, ARM и нейтральные. Примечание. Win32 сопоставляется с x86 и AnyCPU сопоставляется с нейтральным. MSBuild выглядит только в разделе \CommonConfiguration\neutral для пакетов SDK для платформы. |
| SDKManifest.xml | В этом файле описывается, как Visual Studio должен использовать пакет SDK. Ознакомьтесь с манифестом пакета SDK для Windows 8.1:<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 для обеспечения того, чтобы только проекты, предназначенные для одинаковых платформ, указанных в значении этого атрибута, могли использовать пакет SDK. MinVSVersion: этот атрибут используется Visual Studio для использования только пакетов SDK, применяемых к нему. Справочник. Этот атрибут должен быть указан только для тех ссылок, которые содержат элементы управления. Сведения о том, как указать, содержит ли ссылка элементы управления, см. ниже. |
Пакеты SDK расширения
В следующих разделах описывается, что необходимо сделать для развертывания пакета SDK расширения.
Установка
Пакеты SDK расширения можно установить для конкретного пользователя или для всех пользователей без указания раздела реестра. Чтобы установить пакет SDK для всех пользователей, используйте следующий путь:
%Program Files%\Microsoft SDK<Target platform>\v<platform number>\ExtensionSDKs
Для установки для конкретного пользователя используйте следующий путь:
%USERPROFILE%\AppData\Local\Microsoft SDKKs<target platform>\v<platform number>\ExtensionSDKs
Если вы хотите использовать другое расположение, необходимо выполнить одно из двух действий.
Укажите его в разделе реестра:
HKLM\Software\Microsoft\Microsoft SDKKs<целевая платформа\номер> версии платформы>\<ExtensionSDKs<SDKVersion><>\
и добавьте подключ (по умолчанию), имеющий значение
<path to SDK><SDKName><SDKVersion>.Добавьте свойство
SDKReferenceDirectoryRootMSBuild в файл проекта. Значение этого свойства — это список каталогов с запятой, в которых должны находиться пакеты SDK расширения.
Макет установки
Пакеты SDK расширения имеют следующий макет установки:
\<ExtensionSDKs root>
\<SDKName>
\<SDKVersion>
SDKManifest.xml
\References
\<config>
\<arch>
\Redist
\<config>
\<arch>
\DesignTime
\<config>
\<arch>
\<SDKName>\<SDKVersion>: имя и версия пакета SDK расширения являются производными от соответствующих имен папок в пути к корневому каталогу ПАКЕТА SDK. MSBuild использует это удостоверение для поиска пакета SDK на диске, а Visual Studio отображает это удостоверение в окне свойств и диалоговом окне диспетчера ссылок.
Папка ссылок : двоичные файлы, содержащие API. Это могут быть файлы или сборки метаданных Windows (WinMD).
Папка Redist : файлы, необходимые для выполнения или отладки, и должны упаковаться в составе приложения пользователя. Все двоичные файлы должны размещаться под \redist\<config>\<arch>, а двоичные имена должны иметь следующий формат, чтобы обеспечить уникальность: ]<company.<>продукт>.<назначение>.<расширение>. Например, *Microsoft.Cpp.Build.dll. Все файлы с именами, которые могут столкнуться с именами файлов из других пакетов SDK (например, javascript, css, pri, xaml, png и jpg-файлов), должны быть помещены под \redist\<config>\arch>\<<sdkname>* за исключением файлов, связанных с элементами управления XAML. Эти файлы следует поместить под *\redist\<config>\<arch>\<componentname>\.
Папка 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 размещаются вместе с эталонным файлом. Например, XML-справочный документ для сборки \References\<config>\arch>\<sample.dll — \References\<config\arch>\sample.xml, а локализованная версия этого документа — \References\config<>>\<arch>\<<locale>\sample.xml.
Папка конфигурации : три вложенных папки: отладка, розничная торговля и CommonConfiguration. Авторы пакета SDK могут размещать свои файлы в CommonConfiguration , если тот же набор файлов SDK должен использоваться независимо от конфигурации, целевой для потребителя пакета SDK.
Папка архитектуры : поддерживаются следующие архитектуры: 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>
Следующий список содержит элементы файла:
DisplayName: значение, которое отображается в диспетчере ссылок, Обозреватель решений, браузере объектов и других расположениях в пользовательском интерфейсе Для Visual Studio.
ProductFamilyName: общее имя продукта пакета SDK. Например, пакет SDK для Библиотеки Windows для JavaScript (WinJS) называется "Microsoft.WinJS.1.0" и "Microsoft.WinJS.2.0", которые относятся к той же семейству продуктов SDK, "Microsoft.WinJS". Этот атрибут позволяет Visual Studio и MSBuild сделать это подключение. Если этот атрибут не существует, имя пакета SDK используется в качестве имени семейства продуктов.
FrameworkIdentity: указывает зависимость от одной или нескольких библиотек компонентов Windows. Значение этого атрибута помещается в манифест используемого приложения. Этот атрибут применим только к библиотекам компонентов Windows.
TargetFramework: указывает пакеты SDK, доступные в диспетчере ссылок и панели элементов. Это список моникеров целевой платформы с запятой, например "платформа .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=Windows Телефон" фильтрует диспетчер ссылок только в профиле Windows Телефон; Проект, предназначенный для полной платформы Silverlight 4.0, не отображает пакет SDK в диспетчере ссылок.
MinVSVersion: минимальная версия Visual Studio.
MaxPlatformVerson: максимальная целевая версия платформы должна использоваться для указания версий платформы, для которых пакет SDK расширений не будет работать. Например, пакет среды выполнения Microsoft Visual C++ версии 11.0 должен ссылаться только на проекты Windows 8. Таким образом, проект Windows 8 MaxPlatformVersion равен 8.0. Это означает, что диспетчер ссылок фильтрует пакет среды выполнения Microsoft Visual C++ для проекта Windows 8.1, а MSBuild выдает ошибку, когда проект Windows 8.1 ссылается на него. Примечание. Этот элемент поддерживается начиная с Visual Studio 2013.
Область применения: указывает пакеты SDK, доступные в диспетчере ссылок, указав применимые типы проектов Visual Studio. Девять значений распознаются: WindowsAppContainer, VisualC, VB, CSharp, WindowsXAML, JavaScript, Managed и Native. Автор пакета SDK может использовать и ("+") или ("|"), а не ("!") операторы, указывающие именно область типов проектов, применяемых к пакету SDK.
WindowsAppContainer определяет проекты для приложений Магазина Windows 8.x.
SupportPrefer32Bit: поддерживаемые значения: True и False. Значение по умолчанию — True. Если для значения задано значение False, MSBuild возвращает ошибку для проектов Магазина Windows 8.x (или предупреждение для классических проектов), если проект, ссылающийся на пакет SDK, включает Prefer32Bit. Дополнительные сведения о Prefer32Bit см. на странице сборки, конструкторе проектов (C#) или на странице компиляции конструктора проектов (Visual Basic).
SupportedArchitectures: список архитектур с запятой, поддерживаемых пакетом SDK. MSBuild отображает предупреждение, если целевая архитектура пакета SDK в используемом проекте не поддерживается. Если этот атрибут не указан, MSBuild никогда не отображает этот тип предупреждения.
ПоддерживаетMultipleVersions: если для этого атрибута задано значение Error или Warning, MSBuild указывает, что один и тот же проект не может ссылаться на несколько версий одного семейства SDK. Если этот атрибут не существует или задано значение Allow, MSBuild не отображает этот тип ошибки или предупреждения.
AppX: указывает путь к пакетам приложений для библиотеки компонентов Windows на диске. Это значение передается компоненту регистрации библиотеки компонентов Windows во время локальной отладки. Соглашение об именовании для имени файла — <Company>.<Продукт>.<Архитектура>.<Конфигурация>.<Версия>.appx. Конфигурация и архитектура являются необязательными в имени атрибута и значении атрибута, если они не применяются к библиотеке компонентов Windows. Это значение применимо только к библиотекам компонентов Windows.
CopyRedistToSubDirectory: указывает, где файлы в папке \redist должны быть скопированы относительно корневого каталога пакета приложения (то есть расположение пакета, выбранное в мастере создания пакета приложений) и корневой каталог макета среды выполнения. Расположение по умолчанию является корнем пакета приложения и макета F5 .
DependsOn: список удостоверений пакета SDK, определяющих пакеты SDK, от которых зависит этот пакет SDK. Этот атрибут отображается в области сведений диспетчера ссылок.
MoreInfo: URL-адрес веб-страницы, предоставляющей справку и дополнительные сведения. Это значение используется в ссылке "Дополнительные сведения" в правой области диспетчера ссылок.
Тип регистрации: указывает регистрацию WinMD в манифесте приложения и требуется для собственной библиотеки WinMD, которая имеет библиотеку DLL реализации.
Ссылка на файл: указана только для тех ссылок, которые содержат элементы управления или являются собственными winMD. Сведения о том, как указать, содержит ли ссылка элементы управления, см. в разделе "Указание расположения элементов элементов" ниже.
Укажите расположение элементов панели элементов
Элемент ToolBoxItems схемы SDKManifest.xml указывает имена элементов управления, исходные сборки и имена вкладок панели элементов в пакетах SDK для платформы и расширения. В следующих примерах показаны различные сценарии. Это применимо к ссылкам WinMD или DLL.
Обратите внимание, что в Visual Studio 2019 и более ранних версиях, а не перечисление имен элементов элементов в манифесте, Visual Studio динамически перечисляет типы элементов в сборках пакета SDK. Начиная с Visual Studio 2022, это больше не поддерживается; Элементы панели элементов должны быть явно перечислены в SDKManifest.xml.
Поместите элементы управления в категорию панели элементов по умолчанию.
<File Reference = "sample.winmd"> <ToolboxItems VSCategory = "Toolbox.Default"> <Item Type = "Namespace.ControlName1" /> <Item Type = "Namespace.ControlName2" /> </ToolboxItems> </File>Поместите элементы управления под определенным именем категории.
<File Reference = "sample.winmd"> <ToolboxItems VSCategory= "MyCategoryName"> <Item Type = "Namespace.ControlName1" /> <Item Type = "Namespace.ControlName2" /> </ToolboxItems> </File>Поместите элементы управления под определенными именами категорий.
<File Reference = "sample.winmd"> <ToolboxItems VSCategory = "Graph"> <Item Type = "Namespace.ControlName1" /> </ToolboxItems> <ToolboxItems VSCategory = "Data"> <Item Type = "Namespace.ControlName2" /> </ToolboxItems> </File>Поместите элементы управления под различными именами категорий в 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>Перечисляйте определенные элементы управления по-разному в 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>Перечислите определенные элементы управления и поместите их под путь Visual Studio Common Path или только в группе "Все элементы управления".
<File Reference = "sample.winmd"> <ToolboxItems VSCategory = "Toolbox.Common"> <Item Type = "Namespace.ControlName1" /> </ToolboxItems> <ToolboxItems VSCategory = "Toolbox.All"> <Item Type = "Namespace.ControlName2" /> </ToolboxItems> </File>Перечисление определенных элементов управления и отображение только определенного набора в ChooseItems без их использования на панели элементов.
<File Reference = "sample.winmd"> <ToolboxItems VSCategory = "Toolbox.ChooseItemsOnly"> <Item Type = "Namespace.ControlName1" /> <Item Type = "Namespace.ControlName2" /> </ToolboxItems> </File>