diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fabb3724d..a11ff0f86 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # C#/WinRT Contributor's Guide -Below is our guidance for how to report issues, propose new features, and submit contributions via Pull Requests (PRs). +Below is our guidance for how to report issues, propose new features, and submit contributions via Pull Requests (PRs). Please refer to [building and running C#/WinRT](./README.md#Building-and-running-cwinrt) to get started on building the repo. ## Before you start, file an issue diff --git a/README.md b/README.md index 7e7b3b85c..33c59ddd3 100644 --- a/README.md +++ b/README.md @@ -34,10 +34,14 @@ Application developers on .NET5+ can reference C#/WinRT interop assemblies by ad However, C#/WinRT is a general effort and is intended to support other scenarios and versions of the .NET runtime, compatible down to .NET Standard 2.0. -## Installing and running C#/WinRT +## Usage and Developer Guidance Download the C#/WinRT NuGet package here: https://www.nuget.org/packages/Microsoft.Windows.CsWinRT/ +Please read the [usage](docs/usage.md) and [repository structure](docs/structure.md) docs for a detailed breakdown. For recommendations on migrating from System.Runtime.InteropServices, see the [COM Interop](docs/interop.md) guide. For additional documentation and walkthroughs, visit . + +## Building and running C#/WinRT + C#/WinRT currently requires the following packages, or newer, to build: - [Visual Studio 16.8](https://visualstudio.microsoft.com/downloads/) @@ -56,11 +60,7 @@ The `build.cmd` script takes care of all related configuration steps and is the ## What's New -[CsWinRT v1.0](https://github.com/microsoft/CsWinRT/releases/tag/1.0.1.201020.1) is our latest public release, and is compatible with the .NET 5 RTM SDK. We may have preview releases to address specific bug fixes before v1.1. Details on breaking changes and known issues can be found on the [release notes page](https://github.com/microsoft/CsWinRT/releases). - -## Developer Guidance - -Please read the [usage](docs/usage.md) and [repository structure](docs/structure.md) docs for a detailed breakdown. For recommendations on migrating from System.Runtime.InteropServices, see the [COM Interop](docs/interop.md) guide. For additional documentation visit . +C#/WinRT version 1.1.2 features a preview of C#/WinRT [authoring support](https://github.com/microsoft/CsWinRT/blob/master/docs/authoring.md). C#/WinRT [version 1.1.1](https://github.com/microsoft/CsWinRT/releases/tag/1.1.1.210120.1) is aligned with the [.NET 5 February update](https://devblogs.microsoft.com/dotnet/net-february-2021/). See the [releases page](https://github.com/microsoft/CsWinRT/releases) for the most recent C#/WinRT NuGet releases and specific updates to the .NET 5 SDK. Details on breaking changes and known issues can be found on the releases page. ## Related Projects diff --git a/docs/usage.md b/docs/usage.md index 76db3ce2d..bdbc648b6 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1,12 +1,17 @@ # Usage -## Component Project +The [C#/WinRT NuGet package](https://www.nuget.org/packages/Microsoft.Windows.CsWinRT/) provides tooling for the following scenarios: -A component project adds a NuGet reference to C#/WinRT to invoke cswinrt.exe at build time, generate projection sources, and compile these into an interop assembly. For an example of this, see the [Projection Sample](https://github.com/microsoft/CsWinRT/tree/master/src/Samples/Net5ProjectionSample). Command line options can be displayed by running **cswinrt -?**. The interop assembly is then typically distributed as a NuGet package itself. +- [Generate and distribute a projection interop assembly](#generate-and-distribute-a-projection-interop-assembly) +- [Author and consume a C#/WinRT component](#author-and-consume-a-cwinrt-component) -### Example +For more information on using the NuGet package, refer to the [NuGet documentation](../nuget/readme.md). -To invoke cswinrt to generate projection sources for types in the **Contoso** namespace, you need to add the following property to your C# library project file. In this project you would also need to reference the CsWinRT NuGet package and the project-specific `winmd` files you want to project, whether through a NuGet package, project reference or direct reference. By default, the **Windows** and **Microsoft** namespaces are not projected. +## Generate and distribute a projection interop assembly + +A projection project adds a NuGet reference to C#/WinRT to invoke cswinrt.exe at build time, generate projection sources, and compile these into a projection interop assembly. For an example of this, see the [Projection Sample](https://github.com/microsoft/CsWinRT/tree/master/src/Samples/Net5ProjectionSample) and associated [walkthrough](https://docs.microsoft.com/windows/uwp/csharp-winrt/net-projection-from-cppwinrt-component). Command line options can be displayed by running `cswinrt -?`. The interop assembly is then typically distributed as a NuGet package itself for application projects to use. + +To invoke cswinrt to generate projection sources for types in the **Contoso** namespace, you need to add the following property to your C# library project file. In this project you would also need to reference the C#/WinRT NuGet package and the project-specific `.winmd` files you want to project, whether through a NuGet package, project reference or direct reference. By default, the **Windows** and **Microsoft** namespaces are not projected. ``` @@ -14,8 +19,12 @@ To invoke cswinrt to generate projection sources for types in the **Contoso** na ``` -To further customize C#/WinRT behavior, refer to the [CsWinRT NuGet documentation](../nuget/readme.md). +To further customize C#/WinRT behavior, refer to the [C#/WinRT NuGet documentation](../nuget/readme.md). + +### Application Project + +An interop assembly is typically distributed as a NuGet package for application projects to reference. This package will require a dependency on C#/WinRT to include `WinRT.Runtime.dll` for .NET 5 targets. If the interop assembly is not distributed as a NuGet package, an application project adds references to both the component interop assembly produced above and to C#/WinRT to include the `WinRT.Runtime.dll` assembly. If a third party WinRT component is distributed without an official interop assembly, an application project may add a reference to C#/WinRT to generate its own private component interop assembly. There are versioning concerns related to this scenario, so the preferred solution is for the third party to publish an interop assembly directly. -## Application Project +## Author and consume a C#/WinRT component -An application project adds NuGet references to both the component interop assembly produced above and to CsWinRT to include the `winrt.runtime.dll` assembly. If the interop assembly is distributed as a NuGet package itself, this package will require a dependency on C#/WinRT for .NET5 targets. If a third party WinRT component is distributed without an official interop assembly, an application project may add a reference to C#/WinRT to generate its own private component interop assembly. There are versioning concerns related to this scenario, so the preferred solution is for the third party to publish an interop assembly directly. +C#/WinRT provides authoring and hosting support for .NET 5 component authors. For more details, refer to this [walkthrough](https://docs.microsoft.com/en-us/windows/uwp/csharp-winrt/create-windows-runtime-component-cswinrt) and these [authoring docs](https://github.com/microsoft/CsWinRT/blob/master/docs/authoring.md).