C#/WinRT

C#/WinRT é um kit de ferramentas empacotado em NuGet que fornece suporte à projeção de Windows Runtime (WinRT) 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.

O C#/WinRT atualmente fornece suporte para consumir APIs do WinRT por meio do uso de Target Framework Monikers (TFMs) em .NET. Definir o TFM com uma versão específica do SDK Windows adiciona referências aos assemblies de projeção e runtime do SDK Windows gerados pelo C#/WinRT.

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

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

Motivação para C#/WinRT

.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 Windows. Para dar suporte às metas de portabilidade e eficiência do .NET 6+, retiramos 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 embutido para WinRT foi 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 .NET runtime. Para obter detalhes, consulte .NET mapeamentos dos tipos do Windows Runtime.

O C#/WinRT também dá suporte a componentes no SDK do Aplicativo Windows, incluindo o WinUI 3. O SDK do Aplicativo Windows eleva 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 em 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 .NET runtime.

Quais são as novidades?

As versões mais recentes do C#/WinRT podem ser encontradas em nossas notas release 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 WinRT e para criar componentes C#/WinRT. Para obter mais detalhes sobre os cenários de uso para C#/WinRT, consulte o guia usage em nosso repositório.

Gerar e distribuir um assembly de interoperabilidade

As APIs do WinRT são definidas em arquivos winmd (metadados 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 .NET código 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 aplicativos .NET serem referenciados, normalmente como um pacote NuGet.

Para obter mais detalhes sobre como gerar e distribuir um assembly de interoperabilidade, consulte Generate uma projeção C# de um componente C++/WinRT, distribua 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 Windows SDK.

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

A partir do C#/WinRT versão 1.4.1, o suporte está incluído para embutir a projeção do SDK do Windows e as fontes de tempo de execução para ambos .NET e .NET Standard 2.0 na saída do seu aplicativo ou biblioteca. Isso é útil nos casos em que o uso de tipos do Windows SDK é independente. O suporte incorporado remove dependências de WinRT.Runtime.dll e Microsoft.Windows.SDK.NET.dll, o que reduz o tamanho da saída 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 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 da área de trabalho está habilitado com a ativação do WinRT sem registro (consulte Enhancing Non-packaged Desktop Apps usando Componentes de Tempo de Execução do Windows), disponível no Windows 10, versão 1903 e posterior. Os componentes nativos do C++ devem definir a propriedade Windows Desktop Compatible como True, seja por meio das propriedades do projeto ou do arquivo .vcxproj, a fim de referenciar e encaminhar os binários Microsoft.VCLibs.Desktop para aplicativos consumidores. Caso contrário, o pacote VCRT Forwarders será necessário pelos aplicativos que consomem se o componente for destinado apenas a aplicativos UWP.

O C#/WinRT também fornece um caminho alternativo de ativação se o Windows falhar ao 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: "Windows metadados não fornecidos ou detectados".

  Você pode especificar Windows Metadados usando a propriedade de projeto <CsWinRTWindowsMetadata>, 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 Windows especificada na propriedade TargetFramework.

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

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

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

  Consulte a documentação sobre Chamada das APIs do Windows Runtime para obter mais detalhes sobre a especificação da propriedade <TargetFramework>.

• 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 Windows Desktop Compatible como True por meio das propriedades do projeto ou por meio do arquivo .vcxproj.

.NET erros de versionamento do SDK

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

Para corrigir esses erros, atualize o SDK do .NET para a versão mais recente. Isso garantirá que as versões de assembly do runtime e 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/recurso antecipadas para o SDK do .NET, pois correções de runtime podem exigir atualizações para nossas versões de assembly.

Problemas conhecidos

Problemas conhecidos e alterações significativas são mencionados 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 C#/WinRT.

Recursos adicionais

• C#/WinRT GitHub repositório