Creación de un kit de desarrollo de software
Un kit de desarrollo de software (SDK) es una colección de API a las que puede hacer referencia como un solo elemento en Visual Studio. En el cuadro de diálogo Administrador de referencias se muestran todos los SDK que son pertinentes para el proyecto. Al agregar un SDK a un proyecto, las API están disponibles en Visual Studio.
Hay dos tipos de SDK:
Los SDK de plataforma son componentes obligatorios para desarrollar aplicaciones para una plataforma. Por ejemplo, el SDK de Windows 8.1 es necesario para desarrollar aplicaciones de la Tienda Windows 8.x.
Los SDK de extensión son componentes opcionales que amplían una plataforma, pero no son obligatorios para desarrollar aplicaciones para esa plataforma.
En las secciones siguientes se describe la infraestructura general de SDK y cómo crear un SDK de plataforma y un SDK de extensión.
SDK de plataforma
Los SDK de plataforma son necesarios para desarrollar aplicaciones para una plataforma. Por ejemplo, el SDK de Windows 8.1 es necesario para desarrollar aplicaciones para Windows 8.1.
Instalación
Todos los SDK de plataforma se instalarán en HKLM\Software\Microsoft\Microsoft SDKs\[TPI]\v[TPV]\@InstallationFolder = [SDK root]. En consecuencia, el SDK de Windows 8.1 se instala en HKLM\Software\Microsoft\Microsoft SDKs\Windows\v8.1.
Layout
Los SDK de plataforma tienen el siguiente diseño:
\[InstallationFolder root]
SDKManifest.xml
\References
\[config]
\[arch]
\DesignTime
\[config]
\[arch]
| Nodo | Descripción |
|---|---|
| Carpeta Referencias | Contiene binarios que incluyen API que se pueden codificar. Estos podrían incluir archivos o ensamblados de metadatos de Windows (WinMD). |
| Carpeta DesignTime | Contiene archivos que solo son necesarios en el momento de la ejecución o la depuración previos. Estos podrían incluir documentos XML, bibliotecas, encabezados, binarios en tiempo de diseño del cuadro de herramientas, artefactos de MSBuild, etc. Idealmente, los documentos XML se colocarían en la carpeta \DesignTime, pero los documentos XML para las referencias seguirán estando colocados junto con el archivo de referencia en Visual Studio. Por ejemplo, el documento XML de una referencia\References\[config]\[arch]\sample.dll será \References\[config]\[arch]\sample.xml y la versión localizada de ese documento será \References\[config]\[arch]\[locale]\sample.xml. |
| Carpeta Configuración | Solo puede haber tres carpetas: Depurar, Minorista y CommonConfiguration. Los autores del SDK pueden colocar sus archivos en CommonConfiguration si se debe consumir el mismo conjunto de archivos del SDK, independientemente de la configuración de destino del consumidor del SDK. |
| Carpeta Arquitectura | Puede existir cualquier carpeta Arquitectura compatible. Visual Studio admite las siguientes arquitecturas: x86, x64, ARM y neutral. Nota: Win32 se asigna a x86 y AnyCPU se asigna a neutral. MSBuild solo busca en \CommonConfiguration\neutral para los SDK de plataforma. |
| SDKManifest.xml | En este archivo se describe cómo Visual Studio debe consumir el SDK. Examine el manifiesto del SDK para 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: valor que el Examinador de objetos muestra en la lista Examinar. PlatformIdentity: la existencia de este atributo indica a Visual Studio y MSBuild que el SDK es un SDK de plataforma y que las referencias agregadas desde él no se deben copiar localmente. TargetFramework: Visual Studio usa este atributo para asegurarse de que solo los proyectos que tienen como destino los mismos marcos especificados en el valor de este atributo pueden consumir el SDK. MinVSVersion: Visual Studio usa este atributo para consumir solo los SDK que se aplican a él. Referencia: este atributo solo debe especificarse para las referencias que contienen controles. Para obtener información sobre cómo especificar si una referencia contiene controles, consulte a continuación. |
SDK de extensiones
En las secciones siguientes se describe lo que debe hacer para implementar un SDK de extensión.
Instalación
Los SDK de extensión se pueden instalar para un usuario específico o para todos los usuarios sin especificar una clave del registro. Para instalar un SDK para todos los usuarios, use la siguiente ruta de acceso:
%Program Files%\Microsoft SDKs<target platform>\v<platform version number>\ExtensionSDKs
Para una instalación específica del usuario, use la siguiente ruta de acceso:
%USERPROFILE%\AppData\Local\Microsoft SDKs<target platform>\v<platform version number>\ExtensionSDKs
Si desea usar una ubicación diferente, debe realizar una de estas dos acciones:
Especifíquelo en una clave del registro:
HKLM\Software\Microsoft\Microsoft SDKs<target platform>\v<platform version number>\ExtensionSDKs<SDKName><SDKVersion>\
y agregue una subclave (predeterminada) que tenga un valor de
<path to SDK><SDKName><SDKVersion>.Agregue la propiedad de MSBuild
SDKReferenceDirectoryRoota su archivo del proyecto. El valor de esta propiedad es una lista delimitada por punto y coma de directorios en los que residen los SDK de extensión a los que desea hacer referencia.
Diseño de instalación
Los SDK de extensión tienen el siguiente diseño de instalación:
\<ExtensionSDKs root>
\<SDKName>
\<SDKVersion>
SDKManifest.xml
\References
\<config>
\<arch>
\Redist
\<config>
\<arch>
\DesignTime
\<config>
\<arch>
\<SDKName>\<SDKVersion>: el nombre y la versión del SDK de extensión se derivan de los nombres de carpeta correspondientes de la ruta de acceso a la raíz del SDK. MSBuild usa esta identidad para buscar el SDK en el disco y Visual Studio muestra esta identidad en la ventana Propiedades y en el cuadro de diálogo Administrador de referencias.
Carpeta Referencias: binarios que contienen las API. Estos podrían ser archivos o ensamblados de metadatos de Windows (WinMD).
Carpeta Redist: archivos necesarios para tiempo de ejecución o depuración y que deben empaquetarse como parte de la aplicación del usuario. Todos los binarios deben colocarse debajo de \redist\<config>\<arch>, y los nombres de los binarios deben tener el siguiente formato para garantizar la exclusividad: ]<empresa>.<producto>.<finalidad>.<extensión>. Por ejemplo, *Microsoft.Cpp.Build.dll. Todos los archivos con nombres que puedan entrar en conflicto con los nombres de archivo de otros SDK (por ejemplo, javascript, css, pri, xaml, png y jpg) deben colocarse debajo de \redist\<config>\<arch>\<sdkname>* excepto los archivos asociados a controles XAML. Estos archivos deben colocarse debajo de *\redist\<config>\<arch>\<componentname>\.
Carpeta DesignTime: archivos necesarios solo en tiempo de ejecución o depuración previos y que no deben empaquetarse como parte de la aplicación del usuario. Estos podrían ser documentos XML, bibliotecas, encabezados, binarios en tiempo de diseño del cuadro de herramientas, artefactos de MSBuild, etc. Cualquier SDK destinado al consumo por parte de un proyecto nativo debe tener un archivo SDKName.props. A continuación se muestra un ejemplo de este tipo de archivo.
<?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>Los documentos de referencia XML se colocan junto con el archivo de referencia. Por ejemplo, el documento de referencia XML del ensamblado \References\<config>\<arch>\sample.dll es \References\<config>\<arch>\sample.xml y la versión localizada de ese documento es \References\<config>\<arch>\<locale>\sample.xml.
Carpeta Configuración: tres subcarpetas: Depurar, Minorista y CommonConfiguration. Los autores del SDK pueden colocar sus archivos en CommonConfiguration cuando se debe consumir el mismo conjunto de archivos SDK, independientemente de la configuración objetivo del consumidor de SDK.
Carpeta Arquitectura: se admiten las siguientes arquitecturas: x86, x64, ARM y neutral. Win32 se asigna a x86 y AnyCPU se asigna a neutral.
SDKManifest.xml
El archivo SDKManifest.xml describe cómo Visual Studio debe consumir el SDK. A continuación se muestra un ejemplo:
<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>
En la lista siguiente se proporcionan los elementos del archivo:
DisplayName: valor que aparece en el Administrador de referencias, Explorador de soluciones, Examinador de objetos y otras ubicaciones de la interfaz de usuario de Visual Studio.
ProductFamilyName: nombre general del producto del SDK. Por ejemplo, el SDK de la Biblioteca de Windows para JavaScript (WinJS) se denomina “Microsoft.WinJS.1.0” y “Microsoft.WinJS.2.0”, que pertenece a la misma familia de productos SDK, “Microsoft.WinJS”. Este atributo permite que Visual Studio y MSBuild realicen esa conexión. Si este atributo no existe, el nombre del SDK se usa como nombre de familia del producto.
FrameworkIdentity: especifica una dependencia en una o varias bibliotecas de componentes de Windows. El valor de este atributo se coloca en el manifiesto de la aplicación de consumo. Este atributo solo se aplica a las bibliotecas de componentes de Windows.
TargetFramework: especifica los SDK disponibles en el Administrador de referencias y el cuadro de herramientas. Se trata de una lista delimitada por punto y coma de monikers de la plataforma de destino, por ejemplo “.NET Framework, version=v2.0; .NET Framework, version=v4.5.1”. Si se especifican varias versiones de la misma plataforma de destino, el Administrador de referencias usa la versión especificada más antigua con fines de filtrado. Por ejemplo, si se especifica “.NET Framework, version=v2.0; .NET Framework, version=v4.5.1”, el Administrador de referencias usará “.NET Framework, version=v2.0”. Si se especifica un perfil de marco de destino concreto, solo el Administrador de referencias usará ese perfil con fines de filtrado. Por ejemplo, cuando se especifica “Silverlight, version=v4.0, profile=WindowsPhone”, el Administrador de referencias filtra solo el perfil de Windows Phone; Un proyecto destinado al marco Silverlight 4.0 completo no ve el SDK en el Administrador de referencias.
MinVSVersion: versión mínima de Visual Studio.
MaxPlatformVerson: se debe usar la versión máxima de la plataforma de destino para especificar las versiones de plataforma en las que no funcionará el SDK de extensión. Por ejemplo, los proyectos de Windows 8 solo deben hacer referencia al paquete del entorno de ejecución de Microsoft Visual C++ v11.0. Por lo tanto, MaxPlatformVersion del proyecto de Windows 8 es 8.0. Esto significa que el Administrador de referencias filtra el paquete del entorno de ejecución de Microsoft Visual C++ para un proyecto de Windows 8.1 y MSBuild produce un error cuando un proyecto de Windows 8.1 hace referencia a él. Nota: Este elemento se admite a partir de Visual Studio 2013.
Aplicación: especifica los SDK que están disponibles en el Administrador de referencias concretando los tipos de proyecto de Visual Studio aplicables. Se reconocen nueve valores: WindowsAppContainer, VisualC, VB, CSharp, WindowsXAML, JavaScript, Managed y Native. El autor del SDK puede usar operadores y (“+”) o (“|”), no (“!”) para especificar exactamente el ámbito de los tipos de proyecto que se aplican al SDK.
WindowsAppContainer identifica proyectos para aplicaciones de la Tienda Windows 8.x.
SupportPrefer32Bit: los valores admitidos son “True” y “False”. El valor predeterminado es “True”. Si el valor se establece en “False”, MSBuild devuelve un error para los proyectos de la Tienda Windows 8.x (o una advertencia para los proyectos de escritorio) si el proyecto que hace referencia al SDK tiene habilitado Prefer32Bit. Para obtener más información sobre Prefer32Bit, consulte la página Compilar, Diseñador de proyectos (C#) o la página Compilar, Diseñador de proyectos (Visual Basic).
SupportedArchitectures: lista delimitada por puntos y comas de las arquitecturas que admite el SDK. MSBuild muestra una advertencia si no se admite la arquitectura del SDK de destino en el proyecto de consumo. Si no se especifica este atributo, MSBuild nunca muestra este tipo de advertencia.
SupportsMultipleVersions: si este atributo está establecido en Error o Advertencia, MSBuild indica que el mismo proyecto no puede hacer referencia a varias versiones de la misma familia de SDK. Si este atributo no existe o está establecido en Permitir, MSBuild no muestra este tipo de error o advertencia.
AppX: especifica la ruta de acceso a los paquetes de aplicación para la biblioteca de componentes de Windows en el disco. Este valor se pasa al componente de registro de la biblioteca de componentes de Windows durante la depuración local. La convención de nomenclatura del nombre de archivo es <Empresa>.<Producto>.<Arquitectura>.<Configuración>.<Versión>.appx. La configuración y la arquitectura son opcionales en el nombre del atributo y el valor del atributo si no se aplican a la biblioteca de componentes de Windows. Este valor solo se aplica a las bibliotecas de componentes de Windows.
CopyRedistToSubDirectory: especifica dónde se deben copiar los archivos de la carpeta \redist con respecto a la raíz del paquete de la aplicación (es decir, la ubicación del paquete elegido en el asistente Crear paquete de aplicación) y la raíz del diseño del entorno de ejecución. La ubicación predeterminada es la raíz del paquete de la aplicación y el diseño F5.
DependsOn: lista de identidades de SDK que definen los SDK de los que depende este SDK. Este atributo aparece en el panel de detalles del Administrador de referencias.
MoreInfo: dirección URL de la página web que proporciona ayuda y más información. Este valor se usa en el vínculo Más información del panel derecho del Administrador de referencias.
Tipo de registro: especifica el registro de WinMD en el manifiesto de la aplicación y es necesario para WinMD nativo, que tiene un archivo DLL de implementación equivalente.
Referencia de archivo: se especifica solo para las referencias que contienen controles o son winMD nativos. Para obtener información sobre cómo especificar si una referencia contiene controles, consulte Especificar la ubicación de los elementos del cuadro de herramientas a continuación.
Especificar la ubicación de los elementos del cuadro de herramientas
El elemento ToolBoxItems del esquema SDKManifest.xml especifica los nombres de control, los ensamblados de origen y los nombres de pestañas del cuadro de herramientas de los elementos del cuadro de herramientas en los SDK de plataforma y de extensión. En los ejemplos siguientes se muestran varios escenarios. Esto es aplicable a las referencias de WinMD o DLL.
Tenga en cuenta que en Visual Studio 2019 y versiones anteriores, en lugar de enumerar los nombres de control del cuadro de herramientas en el manifiesto, Visual Studio enumera dinámicamente los tipos de control en los ensamblados del SDK. A partir de Visual Studio 2022, ya no se admite; los elementos del cuadro de herramientas deben aparecer explícitamente en SDKManifest.xml.
Coloque los controles en la categoría predeterminada del cuadro de herramientas.
<File Reference = "sample.winmd"> <ToolboxItems VSCategory = "Toolbox.Default"> <Item Type = "Namespace.ControlName1" /> <Item Type = "Namespace.ControlName2" /> </ToolboxItems> </File>Coloque los controles en un nombre de categoría concreto.
<File Reference = "sample.winmd"> <ToolboxItems VSCategory= "MyCategoryName"> <Item Type = "Namespace.ControlName1" /> <Item Type = "Namespace.ControlName2" /> </ToolboxItems> </File>Coloque los controles en nombres de categoría concretos.
<File Reference = "sample.winmd"> <ToolboxItems VSCategory = "Graph"> <Item Type = "Namespace.ControlName1" /> </ToolboxItems> <ToolboxItems VSCategory = "Data"> <Item Type = "Namespace.ControlName2" /> </ToolboxItems> </File>Coloque los controles en diferentes nombres de categoría en Blend y 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>Enumere los controles específicos de forma diferente en Blend y 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>Enumere controles específicos y colóquelos en la ruta de acceso común de Visual Studio o solo en el grupo Todos los controles.
<File Reference = "sample.winmd"> <ToolboxItems VSCategory = "Toolbox.Common"> <Item Type = "Namespace.ControlName1" /> </ToolboxItems> <ToolboxItems VSCategory = "Toolbox.All"> <Item Type = "Namespace.ControlName2" /> </ToolboxItems> </File>Enumere controles específicos y muestre solo un conjunto específico en ChooseItems sin que estén en el cuadro de herramientas.
<File Reference = "sample.winmd"> <ToolboxItems VSCategory = "Toolbox.ChooseItemsOnly"> <Item Type = "Namespace.ControlName1" /> <Item Type = "Namespace.ControlName2" /> </ToolboxItems> </File>