C#/WinRT

C#/WinRT é um kit de ferramentas incluído no NuGet que fornece suporte para projeção Windows Runtime (WinRT) para a linguagem C#. Um assembly de projeção é um assembly de interoperabilidade, que permite programar APIs WinRT de forma natural e familiar para a linguagem alvo. A projeção C#/WinRT esconde os detalhes da interoperabilidade entre interfaces C# e WinRT, e fornece mapeamentos de muitos tipos WinRT para equivalentes .NET apropriados, como strings, URIs, tipos de valores comuns e coleções genéricas.

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

O pacote NuGet C#/WinRT permite-lhe criar e referenciar as suas próprias assemblies de interoperabilidade WinRT para utilizadores do .NET. A versão mais recente de C#/WinRT inclui também uma pré-visualização da autoria dos tipos WinRT em C#.

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

Motivação para C#/WinRT

.NET (anteriormente conhecido como .NET Core) é um runtime open-source e multiplataforma que pode ser usado para construir aplicações de dispositivos, cloud e IoT.

Versões anteriores do .NET Framework e do .NET Core tinham conhecimento incorporado do WinRT — uma tecnologia específica para Windows. Para apoiar os objetivos de portabilidade e eficiência do .NET 6+, retirámos o suporte a projeção WinRT do compilador e runtime .NET e transferimo-lo para o toolkit C#/WinRT (ver Suporte incorporado para WinRT está removido do .NET). O objetivo do C#/WinRT é proporcionar paridade com o suporte WinRT incorporado fornecido pelas versões anteriores do compilador C# e do runtime .NET. Para detalhes, consulte os mapeamentos .NET dos tipos de tempo de execução do Windows.

C#/WinRT também suporta componentes no Windows App SDK, incluindo o WinUI. O Windows App SDK retira os controlos nativos da interface da Microsoft e outros componentes nativos do sistema operativo. Isto permite aos programadores de aplicações utilizar os controlos e componentes mais recentes no Windows 10, versão 1809 e versões posteriores.

Finalmente, C#/WinRT é um conjunto de ferramentas geral e destina-se a suportar outros cenários onde o suporte incorporado para WinRT não está disponível no compilador C# ou no runtime .NET.

O que há de novo

Os lançamentos mais recentes de C#/WinRT podem ser encontrados na nossa página de notas de lançamento no repositório do Github.

Usage

O pacote NuGet C#/WinRT pode ser usado tanto para gerar projeções de C# (também chamadas assemblies de interoperação) a partir de componentes WinRT como na autoria de componentes C#/WinRT. Para mais detalhes sobre os cenários de utilização de C#/WinRT, consulte o guia de utilização no nosso repositório.

Gerar e distribuir um conjunto de interoperabilidade

As APIs WinRT são definidas em ficheiros de Metadados do Windows (WinMD). O pacote NuGet C#/WinRT (Microsoft.Windows.CsWinRT) inclui o compilador C#/WinRT, cswinrt.exe, que pode usar para processar ficheiros WinMD e gerar código .NET C#. O C#/WinRT compila estes ficheiros fonte numa assembly interop, semelhante à forma como o C++/WinRT gera cabeçalhos para a projeção da linguagem C++. Em seguida, pode distribuir o assembly de interop C#/WinRT juntamente com o assembly de implementação para que possam ser referenciadas por aplicações .NET, normalmente como um pacote NuGet.

Para mais detalhes sobre como gerar e distribuir um assembly de interoperabilidade, consulte Gerar uma projeção C# a partir de um componente C++/WinRT e distribuí-lo como um pacote NuGet para aplicações .NET.

Referência a um conjunto de interoperabilidade

Normalmente, os assemblies de interoperação C#/WinRT são referenciados por projetos de aplicativos. Mas também podem ser referenciados por conjuntos interoperativos intermédios. Por exemplo, o assembly de interoperabilidade do WinUI faria referência ao assembly de interoperabilidade do SDK do Windows.

Se distribuir um componente WinRT de terceiros sem uma assembleia oficial de interoperabilidade, um projeto de aplicação pode seguir o procedimento para gerar uma montagem de interoperabilidade para gerar as suas próprias fontes de projeção privadas. Não recomendamos esta abordagem, pois pode produzir projeções conflitantes do mesmo tipo dentro de um processo. O empacotamento NuGet, seguindo o esquema de Semantic Versioning, é projetado para prevenir isto. Prefere-se uma assembleia oficial de interoperabilidade de terceiros.

Suporte embutido para tipos WinRT (Pré-visualização)

A partir do C#/WinRT versão 1.4.1, está incluído suporte para incorporar projeções e fontes de tempo de execução do SDK do Windows tanto para .NET como para .NET Standard 2.0 na saída da sua biblioteca ou aplicação. Isto é útil em casos em que a utilização dos tipos de SDK do Windows é autónoma. O suporte embutido remove dependências de WinRT.Runtime.dll e Microsoft.Windows.SDK.NET.dll, o que reduz o tamanho da saída da biblioteca ou da aplicação. Também permite aos programadores de bibliotecas fornecer suporte downlevel e elimina a necessidade de multi-direcionamento.

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

Ativação do tipo WinRT

O C#/WinRT suporta a ativação de tipos WinRT alojados pelo sistema operativo, bem como componentes de terceiros como o Win2D. O suporte para ativação de componentes de terceiros numa aplicação de ambiente de trabalho está ativado com a ativação WinRT sem registo (ver Melhoria de Aplicações de Ambiente de Trabalho Não Embaladas usando Componentes de Tempo de Execução do Windows), disponível no Windows 10, versão 1903 e posteriores. Os componentes nativos C++ devem definir a propriedade Compatível com o Windows Desktop para True , seja através das propriedades do projeto ou do .vcxproj ficheiro, para referenciar e encaminhar os binários Microsoft.VCLibs.Desktop para aplicações que consomem. Caso contrário, o pacote VCRT Forwarders será necessário para aplicações que utilizam o componente se este se destinar exclusivamente a aplicações UWP.

C#/WinRT também fornece um caminho de ativação se o Windows não conseguir ativar o tipo descrito acima. Neste caso, o C#/WinRT tenta localizar uma DLL nativa de implementação baseada no nome do tipo totalmente qualificado, removendo progressivamente elementos. Por exemplo, a lógica de substituição 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

A ordem alternativa de pesquisa LoadLibrary é utilizada pelo C#/WinRT para localizar uma DLL de implementação. Uma aplicação que dependa deste comportamento alternativo deve incluir a DLL de implementação juntamente com o módulo da aplicação.

Erros comuns e solução de problemas

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

  Pode especificar metadados do Windows usando a <CsWinRTWindowsMetadata> propriedade do projeto, por exemplo:

  <CsWinRTWindowsMetadata>10.0.19041.0</CsWinRTWindowsMetadata>
  

  No C#/WinRT versão 1.2.1 e posteriores, esta propriedade é predefinida para TargetPlatformVersion, que é derivada 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 (falta uma diretiva de using ou uma referência de assembly?)

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

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

  Consulte a documentação sobre Chamar APIs de Execução do Windows para mais detalhes sobre a especificação da <TargetFramework> propriedade.

• System.InvalidCastException ao realizar um casting para uma interface que tem o atributo ComImport

  Ao converter um objeto para uma interface que possui o atributo ComImport, deverá usar o operador .As<> em vez de uma expressão de cast explícita. Por exemplo:

  someObject.As<SomeComImportInterface>
  

  Para mais detalhes, consulte o guia de interoperabilidade COM.

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

  • Se vir esta exceção ao consumir uma projeção C#/WinRT de um componente C++/WinRT, certifique-se de que o componente definiu a propriedade Compatível com o Windows Desktop para Verdadeiro , seja através das propriedades do projeto ou através do .vcxproj ficheiro.

Erros de versionamento do SDK .NET

Pode encontrar os seguintes erros ou avisos num projeto construído com uma versão .NET SDK anterior a qualquer uma das suas dependências.

Mensagem de erro ou aviso	Reason
Aviso MSB3277: Encontrei conflitos entre diferentes versões do WinRT.Runtime ou Microsoft.Windows.SDK.NET que não puderam ser resolvidos.	Este aviso de compilação ocorre ao referenciar uma biblioteca que expõe tipos de SDK do Windows na sua superfície API.
Erro CS1705: Assembly 'AssemblyName1' usa 'TypeName' que tem uma versão superior à assembly referenciada 'AssemblyName2'	Este erro do compilador de compilação ocorre ao referenciar e consumir tipos de SDK Windows expostos numa biblioteca.
System.IO.FileLoadException	Este erro de execução pode ocorrer ao chamar certas APIs numa biblioteca que não expõe tipos de SDK do Windows.

Para corrigir estes erros, atualize o seu SDK .NET para a versão mais recente. Fazer isso garantirá que as versões de assembly em tempo de execução e do SDK do Windows usadas pela sua aplicação são compatíveis com todas as dependências. Estes erros podem ocorrer com atualizações iniciais de manutenção/funcionalidades do SDK .NET, porque correções em tempo de execução podem exigir atualizações nas nossas versões de assembly.

Problemas conhecidos

Problemas conhecidos e alterações irregulares estão registados no repositório GitHub de C#/WinRT.

Se encontrar algum problema funcional com o pacote NuGet C#/WinRT, o compilador cswinrt.exe ou as fontes de projeção geradas, envie-nos os problemas através da página de problemas C#/WinRT.

Recursos adicionais

• Repositório GitHub C#/WinRT