C#/WinRT

C#/WinRT é um kit de ferramentas empacotado em NuGet que fornece suporte à projeção do WinRT (Windows Runtime) para a linguagem C#. Um assembly de projeção é um assembly de interoperabilidade, que permite a programação de APIs do WinRT de maneira natural e familiar para a linguagem de destino. A projeção C#/WinRT oculta os detalhes da interoperabilidade entre interfaces C# e WinRT e fornece mapeamentos de muitos tipos WinRT para equivalentes .NET apropriados, como cadeias de caracteres, URIs, tipos de valor comuns e coleções genéricas.

Atualmente, o C#/WinRT fornece suporte para o consumo de APIs do WinRT por meio do uso de TFMs ( Monikers do Target Framework ) no .NET. Definir o TFM com uma versão específica do SDK do Windows adiciona referências às bibliotecas de projeção e tempo de execução do SDK do Windows criadas por C#/WinRT.

O pacote NuGet do C#/WinRT permite que você crie e referencie seus próprios assemblies de interoperabilidade do WinRT para consumidores .NET. A versão mais recente do C#/WinRT também inclui uma versão prévia da criação de tipos WinRT em C#.

Para obter informações adicionais, consulte o repositório GitHub do C#/WinRT.

Motivação para C#/WinRT

O .NET (anteriormente conhecido como .NET Core) é um runtime multiplataforma de software livre que pode ser usado para criar aplicativos de dispositivo, nuvem e IoT.

As versões anteriores do .NET Framework e do .NET Core tinham conhecimento interno do WinRT — uma tecnologia específica do Windows. Para dar suporte às metas de portabilidade e eficiência do .NET 6+, removemos o suporte de projeção do WinRT do compilador e do runtime do .NET e o movemos para o kit de ferramentas C#/WinRT (consulte o suporte interno para WinRT removido do .NET). O objetivo do C#/WinRT é fornecer paridade com o suporte interno do WinRT fornecido por versões anteriores do compilador C# e do runtime do .NET. Para obter detalhes, consulte os mapeamentos do .NET para tipos do Windows Runtime.

O C#/WinRT também dá suporte a componentes no SDK do Aplicativo do Windows, incluindo WinUI. O Windows App SDK separa os controles nativos da interface de usuário da Microsoft e outros componentes nativos do sistema operacional. Isso permite que os desenvolvedores de aplicativos usem os controles e componentes mais recentes no Windows 10, versão 1809 e versões posteriores.

Por fim, C#/WinRT é um kit de ferramentas geral e destina-se a dar suporte a outros cenários em que o suporte interno para WinRT não está disponível no compilador C# ou no runtime do .NET.

Quais são as novidades?

As versões mais recentes do C#/WinRT podem ser encontradas em nossa página de notas de versão no repositório github.

Usage

O pacote NuGet do C#/WinRT pode ser usado para gerar projeções em C# (também chamados de assemblies de interoperabilidade) de componentes do WinRT e na criação de componentes C#/WinRT. Para obter mais detalhes sobre os cenários de uso para C#/WinRT, consulte o guia de uso em nosso repositório.

Gerar e distribuir um assembly de interoperabilidade

As APIs do WinRT são definidas em arquivos WinMD (Metadados do Windows). O pacote NuGet C#/WinRT (Microsoft.Windows.CsWinRT) inclui o compilador C#/WinRT, cswinrt.exe, que você pode usar para processar arquivos WinMD e gerar código .NET C#. O C#/WinRT compila esses arquivos de origem em um assembly de interoperabilidade, semelhante à forma como o C++/WinRT gera cabeçalhos para a projeção de linguagem C++. Em seguida, você pode distribuir o assembly de interoperabilidade C#/WinRT junto com o assembly de implementação para que os aplicativos .NET façam referência, normalmente como um pacote NuGet.

Para obter mais detalhes sobre como gerar e distribuir um assembly de interoperabilidade, consulte Gerar uma projeção em C# de um componente C++/WinRT, distribuir como um NuGet para aplicativos .NET.

Fazer referência a um assembly de interoperabilidade

Normalmente, os assemblies de interoperabilidade C#/WinRT são referenciados por projetos de aplicativo. Mas eles também podem ser referenciados por assemblies de interoperabilidade intermediários. Por exemplo, o assembly de interoperabilidade do WinUI referenciaria o assembly de interoperabilidade do SDK do Windows.

Se você distribuir um componente WinRT de terceiros sem um assembly de interoperabilidade oficial, um projeto de aplicativo poderá seguir o procedimento para gerar um assembly de interoperabilidade para gerar suas próprias fontes de projeção privadas. Não recomendamos essa abordagem, pois ela pode produzir projeções conflitantes do mesmo tipo em um processo. O empacotamento NuGet, seguindo o esquema de Controle de Versão Semântico, foi projetado para evitar isso. Um assembly de interoperabilidade oficial de terceiros é preferencial.

Suporte inserido para tipos WinRT (versão prévia)

A partir do C#/WinRT versão 1.4.1, o suporte é incluído para inserir a projeção e as fontes de runtime do SDK do Windows para .NET e .NET Standard 2.0 na saída de sua biblioteca ou aplicativo. Isso é útil em casos em que o uso de tipos do SDK do Windows é independente. O suporte incorporado remove dependências de WinRT.Runtime.dll e Microsoft.Windows.SDK.NET.dll, o que reduz o tamanho do output da biblioteca ou do aplicativo. Ele também permite que os desenvolvedores de biblioteca forneçam suporte de nível inferior e remova a necessidade de vários direcionamentos.

Para obter mais detalhes, consulte a documentação inserida em C#/WinRT em nosso repositório.

Ativação do tipo WinRT

O C#/WinRT dá suporte à ativação de tipos WinRT hospedados pelo sistema operacional, bem como a componentes de terceiros, como o Win2D. O suporte para ativação de componentes de terceiros em um aplicativo desktop está habilitado com a ativação WinRT sem necessidade de registro (consulte Aprimoramento de aplicativos de área de trabalho não empacotados usando componentes do Windows Runtime), disponível no Windows 10, versão 1903 e posterior. Os componentes C++ nativos devem definir a propriedade Compatível com a Área de Trabalho do Windows como True por meio das propriedades do projeto ou do .vcxproj arquivo, a fim de referenciar e encaminhar os binários Microsoft.VCLibs.Desktop para aplicativos de consumo. Caso contrário, o pacote de encaminhadores VCRT será exigido pelos aplicativos consumidores se o componente for destinado apenas a aplicativos UWP.

C#/WinRT também fornece um caminho alternativo de ativação caso o Windows falhe em ativar o tipo, conforme descrito acima. Nesse caso, C#/WinRT tenta localizar uma DLL de implementação nativa com base no nome de tipo totalmente qualificado, removendo progressivamente os elementos. Por exemplo, a lógica de fallback tentaria ativar o tipo Contoso.Controls.Widget dos seguintes módulos, em sequência:

1. Contoso.Controls.Widget.dll
2. Contoso.Controls.dll
3. Contoso.dll

O C#/WinRT usa a ordem de pesquisa alternativa loadLibrary para localizar uma DLL de implementação. Um aplicativo que depende desse comportamento de fallback deve empacotar a DLL de implementação junto com o módulo do aplicativo.

Erros comuns e solução de problemas

• Erro: "Metadados do Windows não fornecidos ou detectados".

  Você pode especificar metadados do Windows usando a propriedade do <CsWinRTWindowsMetadata> projeto, por exemplo:

  <CsWinRTWindowsMetadata>10.0.19041.0</CsWinRTWindowsMetadata>
  

  No C#/WinRT versão 1.2.1 e posterior, essa propriedade usa como padrão TargetPlatformVersion, que é derivado da versão do SDK do Windows especificada na TargetFramework propriedade.

• Erro CS0246: O nome do tipo ou namespace 'Windows' não pôde ser encontrado (você está esquecendo uma diretiva de uso ou uma referência de assembly?)

  Para resolver esse erro, edite sua <TargetFramework> propriedade para direcionar uma versão específica do Windows, por exemplo:

  <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
  

  Consulte os documentos sobre como chamar APIs do Windows Runtime para obter mais detalhes sobre como especificar a <TargetFramework> propriedade.

• System.InvalidCastException ao fazer conversão para uma interface que possui o atributo ComImport

  Ao converter um objeto em uma interface que tenha o ComImport atributo, você precisará usar o .As<> operador em vez de usar uma expressão de conversão explícita. Por exemplo:

  someObject.As<SomeComImportInterface>
  

  Para obter mais detalhes, consulte o guia de interoperabilidade COM.

• System.Runtime.InteropServices.COMException: Classe não registrada (0x80040154 (REGDB_E_CLASSNOTREG))

  • Se você vir essa exceção ao consumir uma projeção C#/WinRT de um componente C++/WinRT, verifique se o componente definiu a propriedade Compatível com Área de Trabalho do Windows como True por meio das propriedades do projeto ou por meio do .vcxproj arquivo.

Erros de controle de versão do SDK do .NET

Você pode encontrar os seguintes erros ou avisos em um projeto criado com uma versão anterior do SDK do .NET do que qualquer uma de suas dependências.

Erro ou mensagem de aviso	Reason
Aviso MSB3277: encontrado conflitos entre diferentes versões do WinRT.Runtime ou Microsoft.Windows.SDK.NET que não puderam ser resolvidos.	Esse aviso de build ocorre ao referenciar uma biblioteca que expõe tipos de SDK do Windows em sua superfície de API.
Erro CS1705: Assembly 'AssemblyName1' usa 'TypeName' que tem uma versão mais alta do que o assembly referenciado 'AssemblyName2'	Esse erro do compilador de build ocorre ao referenciar e consumir tipos expostos do SDK do Windows em uma biblioteca.
System.IO.FileLoadException	Esse erro de runtime pode ocorrer ao chamar determinadas APIs em uma biblioteca que não expõe tipos de SDK do Windows.

Para corrigir esses erros, atualize o SDK do .NET para a versão mais recente. Isso garantirá que o runtime e as versões de assembly do SDK do Windows usadas pelo aplicativo sejam compatíveis com todas as dependências. Esses erros podem ocorrer com atualizações de serviço/recursos antecipadas para o SDK do .NET, pois as correções de runtime podem exigir atualizações em nossas versões de assembly.

Problemas conhecidos

Problemas conhecidos e alterações significativas são observados no repositório GitHub do C#/WinRT.

Se você encontrar problemas funcionais com o pacote NuGet C#/WinRT, o compilador cswinrt.exe ou as fontes de projeção geradas, envie problemas para nós por meio da página de problemas do C#/WinRT.

Recursos adicionais

• Repositório GitHub do C#/WinRT