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 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 C#/WinRT permite que você crie e faça referência a seus próprios assemblies de interoperabilidade WinRT para consumidores do .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 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 do 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 de tipos do Windows Runtime.

O C#/WinRT também dá suporte a componentes no Windows App SDK, incluindo o WinUI 3. O Windows App SDK extrai os controles nativos da interface do 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 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 .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 fornecer o assembly de interoperabilidade C#/WinRT junto com o outro assembly de implementação para aplicativos .NET a 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 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 fontes de projeção e 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 embutido remove as dependências de WinRT.Runtime.dll e Microsoft.Windows.SDK.NET.dll, reduzindo 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 de WinRT sem registro (consulte Aprimorando Aplicativos de Desktop Não Empacotados usando Componentes do Windows Runtime), disponível no Windows 10, versão 1903 e posterior. Os componentes nativos do C++ devem definir a propriedade Windows Desktop Compatible como True por meio das propriedades do projeto ou do arquivo .vcxproj, para referenciar e encaminhar os binários Microsoft.VCLibs.Desktop para aplicativos consumidores. 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 <CsWinRTWindowsMetadata> project, 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 a documentação sobre as APIs do Windows Runtime Calling para obter mais detalhes sobre como especificar a 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 project ou por meio do arquivo .vcxproj.

Erros de versão do SDK do .NET

Você pode encontrar os seguintes erros ou avisos em um projeto construído com uma versão anterior do SDK .NET em relação a qualquer uma de suas dependências.

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/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 mudanças disruptivas são observados no repositório do GitHub 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