Skip to content

Latest commit

 

History

History
71 lines (39 loc) · 5.88 KB

structure.md

File metadata and controls

71 lines (39 loc) · 5.88 KB
Raw

Repository Structure

This document describes the CsWinRT repository organization. Documentation and specs are located in the /docs folder. All source code for CsWinRT is located in the /src folder, and files for generating the NuGet package are located in /nuget.

build

Contains source files for Azure DevOps pipeline that handles official builds and testing for C#/WinRT. Uses Maestro to publish builds conveniently for dependent projects; Maestro is a dependency manager developed by dotnet as part of the Arcade Build System.

eng

Contains files that assist with publishing to Maestro.

nuget

Contains source files for producing a C#/WinRT NuGet package, which is regularly built, signed, and published to nuget.org by Microsoft. The C#/WinRT NuGet package contains the cswinrt.exe compiler and the runtime assembly, WinRT.Runtime.dll.

src/Authoring

Contains projects for implementing authoring and hosting support.

src/Benchmarks

Contains benchmarks written using BenchmarkDotNet to track the performance of scenarios in the generated projection. To run the benchmarks using the CsWinRT projection, run benchmark.cmd. To run the same benchmarks using the built-in WinMD support in NET Core 3.1 to compare against as a baseline, run benchmark_winmd.cmd.

src/cswinrt

Contains the sources and cswinrt.vcxproj project file for building the C#/WinRT compiler, cswinrt.exe. The projection's base library is contained in src/cswinrt/strings/WinRT.cs, which is processed by src/Strings.props to generate string literals contained in the compiler.

The compiler uses the WinMD NuGet package for parsing ECMA-335 metadata files. The WinMD github repo includes a winmd.natvis script for debugging metadata parsing. A symlink can be used to install the script:

for /f "tokens=2*" %i in ('reg query "HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folders" /v Personal ^| findstr Personal') do @for /f "tokens=2" %k in ('"%ProgramFiles(x86)%\Microsoft Visual Studio\Installer\vswhere" -latest ^| findstr catalog_productLineVersion') do @echo %j\Visual Studio %k\Visualizers| for /f "delims=" %l in ('more') do @md "%l" 2>nul & mklink "%l\winmd.natvis" "c:\git\winmd\vs\winmd.natvis"

The C#/WinRT project also contains a cswinrt.natvis script for debugging the C# projection writing, which can also be installed with a symlink:

for /f "tokens=2*" %i in ('reg query "HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folders" /v Personal ^| findstr Personal') do @for /f "tokens=2" %k in ('"%ProgramFiles(x86)%\Microsoft Visual Studio\Installer\vswhere" -latest ^| findstr catalog_productLineVersion') do @echo %j\Visual Studio %k\Visualizers| for /f "delims=" %l in ('more') do @md "%l" 2>nul & mklink "%l\cswinrt.natvis" "c:\git\cswinrt\cswinrt\cswinrt.natvis"

See also Deploying .natvis files.

src/Projections

Contains several projects for generating and building projections from the Windows SDK, WinUI, Benchmark (produced by the BenchmarkComponent project), and Test metadata (produced by the TestWinRT and TestComponentCSharp projects).

src/Samples

  • Net5ProjectionSample: Contains an end-to-end sample for component authors, showing how to generate a projection from a C++/WinRT component and consume it using a NuGet package.

  • WinUIDesktopSample: Contains an end-to-end sample app that uses the Windows SDK and WinUI projections generated above.

src/Tests

Contains various testing-related projects:

  • TestComponentCSharp: This is an implementation of a WinRT test component, defined in class.idl and used by the UnitTest project. To complement the general TestComponent above, the TestComponentCSharp tests scenarios specific to the C#/WinRT language projection.

  • UnitTest: Unit tests for validating the Windows SDK, WinUI, and Test projections generated above. All pull requests should ensure that this project executes without errors.

  • HostTest: Unit tests for WinRT.Host.dll, which provides hosting for runtime components written in C#.

src/TestWinRT

C#/WinRT makes use of the standalone TestWinRT repository for general language projection test coverage. This repo is cloned into the root of the C#/WinRT repo, via get_testwinrt.cmd, so that cswinrt.sln can resolve its reference to TestComponent.vcxproj. The resulting TestComponent and BenchmarkComponent files are consumed by the UnitTest and Benchmarks projects above.

src/WinRT.Runtime

Contains the WinRT.Runtime project for building the C#/WinRT runtime assembly, WinRT.Runtime.dll. The runtime assembly provides an abstraction layer over the .NET 5 runtime, and also provides Xaml reference tracking support which is necessary for WinUI 3 applications to manage memory correctly. The runtime assembly implements the following features for all projected C#/WinRT types:

  • WinRT activation and marshaling logic
  • Custom type mappings, primarily for WinUI
  • COM Wrapper management
  • IDynamicInterfaceCastable and ComImport casting support
  • Extension methods common to projected types