Создание элементов управления пользовательским интерфейсом в виде пакетов NuGet
Начиная с версии Visual Studio 2017, вы можете использовать возможности добавления элементов управления UWP и WPF в пакеты NuGet. В руководстве описано, как использовать эти возможности в контексте элементов управления UWP с использованием примера ExtensionSDKasNuGetPackage. Это же применимо к элементам управления WPF, если не указано иное.
Предварительные требования
- Visual Studio 2017
- Умение создавать пакеты UWP
Создание структуры библиотеки
Примечание
Это применимо только к элементам управления UWP.
Настраивая свойство GenerateLibraryLayout, вы обеспечите создание результатов сборки проекта в макете, который готов к упаковке без необходимости включать записи отдельных файлов в nuspec.
В окне свойств проекта перейдите на вкладку сборки и установите флажок "Создать структуру библиотеки". Это изменит файл проекта и задаст для флага GenerateLibraryLayout значение true для текущее выбранной конфигурации сборки и платформы.
Можно также изменить файл проекта, чтобы добавить <GenerateLibraryLayout>true</GenerateLibraryLayout> в первую безусловную группу свойств. Так свойство будет применено независимо от конфигурации сборки и платформы.
Добавление поддержки элементов управления XAML на панели элементов или в области ресурсов
Чтобы элемент управления XAML отображался на панели элементов конструктора XAML в Visual Studio и в области ресурсов Blend, создайте файл VisualStudioToolsManifest.xml в корне папки tools проекта пакета. Этот файл не требуется, если не нужно, чтобы элемент управления отображался на панели элементов или в области ресурсов.
\build
\lib
\tools
VisualStudioToolsManifest.xml
Файл имеет следующую структуру:
<FileList>
<File Reference = "your_package_file">
<ToolboxItems UIFramework="WPF" VSCategory="vs_category" BlendCategory="blend_category">
<Item Type="type_full_name_1" />
<!-- Any number of additional Items -->
<Item Type="type_full_name_2" />
<Item Type="type_full_name_3" />
</ToolboxItems>
</File>
</FileList>
Здесь:
- your_package_file — имя файла элемента управления, например
ManagedPackage.winmd(ManagedPackage — это произвольное имя, которое взято для примера и не имеет особого значения). - vs_category: метка группы, в которой должен отображаться элемент управления на панели элементов в конструкторе Visual Studio. Элемент
VSCategoryнеобходим для отображения элемента управления на панели элементов. ui_framework. Имя платформы, например WPF. Обратите внимание, что атрибутUIFrameworkтребуется для узлов ToolboxItems в Visual Studio 16.7 Preview 3 и более поздних версиях, чтобы элемент управления отображался в панели элементов. - blend_category — метка группы, в которой должен отображаться элемент управления в области ресурсов конструктора Blend. Элемент
BlendCategoryнеобходим для отображения элемента управления в области ресурсов. - type_full_name_n — полное имя каждого элемента управления, включая пространство имен, например
ManagedPackage.MyCustomControl. Обратите внимание на то, что нотация с точкой используется как для управляемых, так и для собственных типов.
Если один пакет содержит несколько сборок элементов управления, можно включить несколько элементов <File> в элемент <FileList>. Вы также можете добавить несколько узлов <ToolboxItems> в один элемент <File>, чтобы упорядочить элементы управления по отдельным категориям.
В приведенном ниже примере элемент управления, реализованный в файле ManagedPackage.winmd, будет отображаться в Visual Studio и Blend в группе "Managed Package" (Управляемый пакет) и иметь имя MyCustomControl. Все эти имена являются произвольными.
<FileList>
<File Reference = "ManagedPackage.winmd">
<ToolboxItems UIFramework="WPF" VSCategory="Managed Package" BlendCategory="Managed Package">
<Item Type="ManagedPackage.MyCustomControl" />
</ToolboxItems>
</File>
</FileList>
Примечание
Каждый элемент, который должен отображаться на панели элементов или в области ресурсов, необходимо указывать явным образом. При этом следует использовать формат Namespace.ControlName.
Добавление пользовательских значков для элементов управления
Чтобы на панели элементов или в области ресурсов отображался пользовательский значок, добавьте изображение в свой проект или соответствующий проект design.dll с именем Namespace.ControlName.extension и выберите действие сборки "Внедренный ресурс". Также нужно убедиться, что в соответствующем файле AssemblyInfo.cs указан атрибут ProvideMetadata — [assembly: ProvideMetadata(typeof(RegisterMetadata))]. См. этот пример.
Поддерживаемые форматы: .png, .jpg, .jpeg, .gif и .bmp. Рекомендуемый формат — BMP24 размером 16 на 16 пикселей.
Розовый фон заменяется во время выполнения. Цвет значков меняется при изменении темы Visual Studio и если ожидается этот цвет фона. Дополнительные сведения см. в разделе Изображения и значки для Visual Studio.
В приведенном ниже примере проект содержит файл изображения с именем ManagedPackage.MyCustomControl.png.
Примечание
Для собственных элементов управления значки следует добавлять в качестве ресурсов в проект design.dll.
Поддержка определенных версий платформы Windows
Пакеты UWP имеют свойства TargetPlatformVersion (TPV) и TargetPlatformMinVersion (TPMinV), которые определяют самую позднюю и самую раннюю версии ОС, в которых может быть установлено приложение. Кроме того, свойство TPV определяет версию пакета SDK, на основе которой создается приложение. Учитывайте эти свойства при разработке пакета UWP: использование интерфейсов API, которые выходят за пределы определенных в приложении версий платформы, приведет либо к сбою сборки, либо к ошибке приложения во время выполнения.
Например, предположим, что вы указали в качестве значения свойства TPMinV для пакета элементов управления юбилейное обновление Windows 10 (версия 10.0, сборка 14393), и вам нужно, чтобы пакет использовался проектами UWP, предназначенными только для этой или более поздних версий. Чтобы пакет могли потреблять проекты UWP, необходимо упаковать элементы управления, используя следующие имена папок:
\lib\uap10.0.14393\*
\ref\uap10.0.14393\*
NuGet автоматически проверит TPMinV для используемого проекта и отменит установку, если версия будет ниже Windows 10 Anniversary Edition (10.0; сборка 14393).
Для WPF вы можете настроить использование пакета элементов управления WPF в проектах, предназначенных для .NET Framework версии 4.6.1 и выше. Для этого вам нужно упаковать элементы управления, используя следующие имена папок:
\lib\net461\*
\ref\net461\*
Добавление поддержки на этапе разработки
Чтобы указать, где должны отображаться свойства элемента управления в инспекторе свойств, добавьте пользовательские графические элементы и другие элементы, а затем поместите файл design.dll в папку lib\uap10.0.14393\Design для соответствующей целевой платформы. Кроме того, чтобы убедиться, что функция редактирования шаблона > редактирования копии работает, необходимо включить Generic.xaml и все словари ресурсов, которые он объединяет в папку <your_assembly_name>\Themes (опять же, используя фактическое имя сборки). (Этот файл не влияет на поведение элемента управления во время выполнения.) В результате структура папок будет выглядеть следующим образом.
\lib
\uap10.0.14393
\Design
\MyControl.design.dll
\your_assembly_name
\Themes
Generic.xaml
Пример, в котором можно настроить использование пакета средств управления WPF в проектах, предназначенных для .NET Framework версии 4.6.1 и выше:
\lib
\net461
\Design
\MyControl.design.dll
\your_assembly_name
\Themes
Generic.xaml
Примечание
По умолчанию свойства элемента управления отображаются в инспекторе свойств в категории "Прочее".
Использование строк и ресурсов
В пакет можно внедрить строковые ресурсы (.resw), которые могут использоваться элементом управления или проектом UWP. Выберите для свойства Действие сборки файла .resw значение PRIResource.
Пример можно найти в файле MyCustomControl.cs в образце пакета ExtensionSDKasNuGetPackage.
Примечание
Это применимо только к элементам управления UWP.
См. также
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по