Criar um Software Development Kit
Um SDK (Software Development Kit) é uma coleção de APIs que você pode referenciar como um único item no Visual Studio. A caixa de diálogo Gerenciador de Referências lista todos os SDKs relevantes para o projeto. Quando você adiciona um SDK a um projeto, as APIs estão disponíveis no Visual Studio.
Há dois tipos de SDKs:
SDKs de plataforma são componentes obrigatórios para o desenvolvimento de aplicativos para uma plataforma. Por exemplo, o SDK do Windows 8.1 é necessário para desenvolver aplicativos da Windows 8.x Store.
SDKs de extensão são componentes opcionais que estendem uma plataforma, mas não são obrigatórios para o desenvolvimento de aplicativos para essa plataforma.
As seções a seguir descrevem a infraestrutura geral dos SDKs e como criar um SDK de plataforma e um SDK de extensão.
SDKs de plataforma
Os SDKs de plataforma são necessários para desenvolver aplicativos para uma plataforma. Por exemplo, o SDK do Windows 8.1 é necessário para desenvolver aplicativos para o Windows 8.1.
Instalação
Todos os SDKs de plataforma serão instalados em HKLM\Software\Microsoft\Microsoft SDKs\[TPI]\v[TPV]\@InstallationFolder = [raiz do SDK]. Assim, o SDK do Windows 8.1 é instalado em HKLM\Software\Microsoft\Microsoft SDKs\Windows\v8.1.
Layout
Os SDKs de plataforma têm o seguinte layout:
\[InstallationFolder root]
SDKManifest.xml
\References
\[config]
\[arch]
\DesignTime
\[config]
\[arch]
| Nó | Descrição |
|---|---|
| Pasta Referências | Contém binários que contêm APIs que podem ser codificadas. Eles podem incluir arquivos ou assemblies de WinMD (Metadados do Windows). |
| Pasta DesignTime | Contém arquivos que são necessários apenas no momento da pré-execução/depuração. Isso pode incluir documentos XML, bibliotecas, cabeçalhos, binários de tempo de design da caixa de ferramentas, artefatos do MSBuild e assim por diante Os documentos XML seriam, idealmente, colocados na pasta \DesignTime, mas os documentos XML para referências continuarão a ser colocados ao lado do arquivo de referência no Visual Studio. Por exemplo, o documento XML para uma referência \References\[config]\[arch]\sample.dll será \References\[config]\[arch]\sample.xml, e a versão localizada desse documento será \References\[config]\[arch]\[locale]\sample.xml. |
| Pasta Configuração | Pode haver somente três pastas: Debug, Retail e CommonConfiguration. Os autores do SDK podem colocar seus arquivos em CommonConfiguration se o mesmo conjunto de arquivos SDK deve ser consumido, independentemente da configuração que o consumidor do SDK terá como meta. |
| Pasta Arquitetura | Qualquer pasta Arquitetura com suporte pode existir. O Visual Studio oferece suporte às seguintes arquiteturas: x86, x64, ARM e neutro. Observação: Win32 mapeia para x86 e AnyCPU mapeia para neutro. O MSBuild procura apenas em \CommonConfiguration\neutral para SDKs de plataforma. |
| SDKManifest.xml | Esse arquivo descreve como o Visual Studio deve consumir o SDK. Confira o manifesto do 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: o valor que o pesquisador de objetos exibe na lista de controle. PlatformIdentity: a existência desse atributo informa ao Visual Studio e ao MSBuild que o SDK é um SDK de plataforma e que as referências adicionadas dele não devem ser copiadas localmente. TargetFramework: esse atributo é usado pelo Visual Studio para garantir que apenas projetos destinados às mesmas estruturas especificadas no valor desse atributo possam consumir o SDK. MinVSVersion: esse atributo é usado pelo Visual Studio para consumir apenas os SDKs que se aplicam a ele. Reference: esse atributo deve ser especificado apenas para as referências que contêm controles. Para obter informações sobre como especificar se uma referência contém controles, confira abaixo. |
SDKs de extensão
As seções a seguir descrevem o que você precisa fazer para implantar um SDK de extensão.
Instalação
SDKs de extensão podem ser instalados para um usuário específico ou para todos os usuários sem especificar uma chave do Registro. Para instalar um SDK para todos os usuários, use o seguinte caminho:
%Program Files%\Microsoft SDKs<target platform>\v<platform version number>\ExtensionSDKs
Para uma instalação específica do usuário, use o seguinte caminho:
%USERPROFILE%\AppData\Local\Microsoft SDKs<target platform>\v<platform version number>\ExtensionSDKs
Se você quiser usar uma localização diferente, você deve executar uma das duas opções:
Especifique-a em uma chave do Registro:
HKLM\Software\Microsoft\Microsoft SDKs<target platform>\v<platform version number>\ExtensionSDKs<SDKName><SDKVersion>\
e adicione uma subchave (Padrão) que tenha um valor de
<path to SDK><SDKName><SDKVersion>.Adicione a propriedade MSBuild
SDKReferenceDirectoryRootao seu arquivo de projeto. O valor dessa propriedade é uma lista delimitada por ponto e vírgula de diretórios nos quais residem os SDKs de extensão que você deseja referenciar.
Layout de instalação
Os SDKs de extensão têm o seguinte layout de instalação:
\<ExtensionSDKs root>
\<SDKName>
\<SDKVersion>
SDKManifest.xml
\References
\<config>
\<arch>
\Redist
\<config>
\<arch>
\DesignTime
\<config>
\<arch>
\<SDKName>\<SDKVersion>: o nome e a versão do SDK de extensão são derivados dos nomes de pasta correspondentes no caminho para a raiz do SDK. O MSBuild usa essa identidade para localizar o SDK no disco e o Visual Studio exibe essa identidade na janela Propriedades e na caixa de diálogo Gerenciador de Referências.
Pasta References: os binários que contêm as APIs. Eles podem ser arquivos ou assemblies de WinMD (Metadados do Windows).
Pasta Redist: os arquivos que são necessários para runtime/depuração e devem ser empacotados como parte do aplicativo do usuário. Todos os binários devem ser colocados abaixo de \redist\<config>\<arch>, e os nomes binários devem ter o seguinte formato para garantir a exclusividade: ]<empresa>.<produto>.<finalidade>.<extensão>. Por exemplo, *Microsoft.Cpp.Build.dll. Todos os arquivos com nomes que podem colidir com nomes de arquivos de outros SDKs (por exemplo, arquivos javascript, css, pri, xaml, png e jpg) devem ser colocados abaixo de \redist\<config>\<arch>\<sdkname>*, exceto para os arquivos associados a controles XAML. Esses arquivos devem ser colocados abaixo de *\redist\<config>\<arch>\<componentname>\.
Pasta DesignTime: os arquivos que são necessários apenas no tempo de pré-execução/depuração e não devem ser empacotados como parte do aplicativo do usuário. Eles podem ser documentos XML, bibliotecas, cabeçalhos, binários de tempo de design da caixa de ferramentas, artefatos do MSBuild e assim por diante. Qualquer SDK destinado ao consumo por um projeto nativo deve ter um arquivo SDKName.props. Confira a seguir uma amostra desse tipo de arquivo.
<?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>Os documentos de referência XML são colocados ao lado do arquivo de referência. Por exemplo, o documento de referência XML para o assembly \References\<config>\<arch>\sample.dll é \References\<config>\<arch>\sample.xml e a versão localizada desse documento é \References\<config>\<arch>\<locale>\sample.xml.
Pasta Configuration: três subpastas: Debug, Retail e CommonConfiguration. Os autores do SDK podem colocar seus arquivos em CommonConfiguration quando o mesmo conjunto de arquivos SDK deve ser consumido, independentemente da configuração direcionada pelo consumidor do SDK.
Pasta Architecture: as seguintes arquiteturas têm suporte: x86, x64, ARM, neutro. Win32 mapeia para x86 e AnyCPU mapeia para neutro.
SDKManifest.xml
O arquivo SDKManifest.xml descreve como o Visual Studio deve consumir o SDK. A seguir, é mostrado um exemplo:
<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>
A lista a seguir fornece os elementos do arquivo:
DisplayName: o valor que aparece no Gerenciador de Referências, no Gerenciador de Soluções, no Pesquisador de Objetos e em outras localizações na interface do usuário do Visual Studio.
ProductFamilyName: o nome geral do produto SDK. Por exemplo, o SDK da WinJS (Biblioteca do Windows para JavaScript) é chamado "Microsoft.WinJS.1.0" e "Microsoft.WinJS.2.0", que pertencem à mesma família de produtos SDK, "Microsoft.WinJS". Esse atributo permite que o Visual Studio e o MSBuild façam essa conexão. Se esse atributo não existir, o nome do SDK será usado como o nome da família de produtos.
FrameworkIdentity: especifica uma dependência em uma ou mais bibliotecas de componentes do Windows. O valor desse atributo é colocado no manifesto do aplicativo de consumo. Esse atributo é aplicável somente a bibliotecas de componentes do Windows.
TargetFramework: especifica os SDKs que estão disponíveis no Gerenciador de Referências e na caixa de ferramentas. Essa é uma lista delimitada por ponto e vírgula dos Monikers da Estrutura de Destino, por exemplo, ".NET Framework, version=v2.0; .NET Framework, version=v4.5.1". Se várias versões da mesma estrutura de destino forem especificadas, o Gerenciador de Referências usará a versão mais baixa especificada para fins de filtragem. Por exemplo, se ".NET Framework, version=v2.0; .NET Framework, version=v4.5.1" for especificado, o Gerenciador de Referências usará ".NET Framework, version=v2.0". Se um perfil de estrutura de destino específico for especificado, somente esse perfil será usado pelo Gerenciador de Referências para fins de filtragem. Por exemplo, quando "Silverlight, version=v4.0, profile=WindowsPhone" é especificado, o Gerenciador de Referência filtra somente o perfil do telefone Windows; um projeto direcionado à estrutura Silverlight 4.0 completa não vê o SDK no Gerenciador de Referências.
MinVSVersion: a versão mínima do Visual Studio.
MaxPlatformVerson: a versão máxima da plataforma de destino deve ser usada para especificar as versões de plataforma nas quais o SDK de extensão não funcionará. Por exemplo, o pacote de runtime v11.0 do Microsoft Visual C++ deve ser referenciado somente por projetos do Windows 8. Assim, o MaxPlatformVersion do projeto do Windows 8 é 8.0. Isso significa que o Gerenciador de Referências filtra o pacote de runtime do Microsoft Visual C++ para um projeto do Windows 8.1 e o MSBuild lança um erro quando um projeto do Windows 8.1 faz referência a ele. Observação: esse elemento tem suporte desde o Visual Studio 2013.
AppliesTo: especifica os SDKs que estão disponíveis no Gerenciador de Referências especificando os tipos de projeto aplicáveis do Visual Studio. Nove valores são reconhecidos: WindowsAppContainer, VisualC, VB, CSharp, WindowsXAML, JavaScript, Managed e Native. O autor do SDK pode usar os operadores e ("+"), ou ("|"), não ("!") para especificar exatamente o escopo dos tipos de projeto que se aplicam ao SDK.
WindowsAppContainer identifica projetos para aplicativos da Windows 8.x Store.
SupportPrefer32Bit: os valores com suporte são "True" e "False". O padrão é "True". Se o valor for definido como "False", o MSBuild retornará um erro para projetos da Windows 8.x Store (ou um aviso para projetos da área de trabalho) se o projeto que faz referência ao SDK tiver Prefer32Bit habilitado. Para obter mais informações sobre Prefer32Bit, confira Página de build, Designer de Projeto (C#) ou Página de compilação, Designer de Projeto (Visual Basic).
SupportedArchitectures: uma lista delimitada por ponto e vírgula de arquiteturas às quais o SDK oferece suporte. O MSBuild exibirá um aviso se a arquitetura do SDK de destino no projeto de consumo não tiver suporte. Se esse atributo não for especificado, o MSBuild nunca exibirá esse tipo de aviso.
SupportsMultipleVersions: se esse atributo estiver definido como Erro ou Aviso, o MSBuild indicará que o mesmo projeto não pode fazer referência a várias versões da mesma família de SDK. Se esse atributo não existir ou estiver definido como Permitir, o MSBuild não exibirá esse tipo de erro ou aviso.
AppX: especifica o caminho para os pacotes do aplicativo para a biblioteca de componentes do Windows no disco. Esse valor é passado para o componente de registro da biblioteca de componentes do Windows durante a depuração local. A convenção de nomenclatura para o nome de arquivo é <Empresa>.<Produto>.<Arquitetura>.<Configuração>.<Versão>.appx. Configuração e Arquitetura são opcionais no nome do atributo e no valor do atributo se não se aplicarem à biblioteca de componentes do Windows. Esse valor é aplicável somente às bibliotecas de componentes do Windows.
CopyRedistToSubDirectory: especifica onde os arquivos na pasta \redist devem ser copiados em relação à raiz do pacote do aplicativo (ou seja, a localização do pacote escolhida no assistente Criar pacote de aplicativo) e à raiz do layout de runtime. A localização padrão é a raiz do pacote do aplicativo e o layout F5.
DependsOn: uma lista de identidades do SDK que definem os SDKs dos quais esse SDK depende. Esse atributo aparece no painel Detalhes do Gerenciador de Referências.
MoreInfo: a URL para a página da Web que fornece ajuda on-line e mais informações. Esse valor é usado no link Mais informações no painel direito do Gerenciador de Referências.
Tipo de registro: especifica o registro do WinMD no manifesto do aplicativo e é necessário para o WinMD nativo, que tem uma DLL de implementação de contrapartida.
Referência de arquivo: especificado apenas para as referências que contêm controles ou são WinMDs nativos. Para obter informações sobre como especificar se uma referência contém controles, confira Especificar a localização dos itens da caixa de ferramentas abaixo.
Especificar a localização dos itens da caixa de ferramentas
O elemento ToolBoxItems do esquema SDKManifest.xml especifica os nomes de controle, assemblies de origem e nomes de guia de caixa de ferramentas de itens de caixa de ferramentas em SDKs de plataforma e extensão. Os exemplos a seguir mostram vários cenários. Isto é aplicável a referências de WinMD ou DLL.
No Visual Studio 2019 e versões anteriores, em vez de listar nomes de controle de caixa de ferramentas no manifesto, o Visual Studio enumerou dinamicamente os tipos de controle nos assemblies do SDK. A partir do Visual Studio 2022, não há mais suporte; os itens da caixa de ferramentas devem ser explicitamente listados em SDKManifest.xml.
Coloque os controles na categoria padrão da caixa de ferramentas.
<File Reference = "sample.winmd"> <ToolboxItems VSCategory = "Toolbox.Default"> <Item Type = "Namespace.ControlName1" /> <Item Type = "Namespace.ControlName2" /> </ToolboxItems> </File>Coloque os controles sob um nome de categoria específico.
<File Reference = "sample.winmd"> <ToolboxItems VSCategory= "MyCategoryName"> <Item Type = "Namespace.ControlName1" /> <Item Type = "Namespace.ControlName2" /> </ToolboxItems> </File>Coloque controles sob nomes de categoria específicos.
<File Reference = "sample.winmd"> <ToolboxItems VSCategory = "Graph"> <Item Type = "Namespace.ControlName1" /> </ToolboxItems> <ToolboxItems VSCategory = "Data"> <Item Type = "Namespace.ControlName2" /> </ToolboxItems> </File>Coloque controles sob nomes de categoria diferentes no Blend e no 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 controles específicos de forma diferente no Blend e no 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 e coloque-os no caminho comum do Visual Studio ou somente no grupo Todos os 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 e mostre somente um conjunto específico em ChooseItems sem que eles estejam na caixa de ferramentas.
<File Reference = "sample.winmd"> <ToolboxItems VSCategory = "Toolbox.ChooseItemsOnly"> <Item Type = "Namespace.ControlName1" /> <Item Type = "Namespace.ControlName2" /> </ToolboxItems> </File>