diff --git a/README.md b/README.md index cb3a7ce..47bc1fe 100644 --- a/README.md +++ b/README.md @@ -10,20 +10,30 @@ WinUI3 Xaml Preview allows you to see a a live preview of your UI while authorin Contributions are welcome! :D -## Features +## Feature - Interactive preview of your XAML code (powered by `XamlReader`) - Integration with VS2022 17.9+ - Reload via opening/saving/switching - Supports your own user control and custom control - Supports controls in dependency (i.e. libraries) +- Supports control template previewing with control+style dropdown +- Supports DLL project (directly, or with a separate Sample App project) -Custom control's template previewing is not supported yet but is planned. Stay tuned. +## Feature/Language Support Table +||C++|C#| +|--|--| +| App | ✔️ | ✔️ | +| App packaged with WAP project | ✔️ | ✔️ | +| Dynamic WinRT Component (via separate Sample App project\*) | ✔️ | ✔️ | +| Static WinRT Component (via separate Sample App project\*) | ✔️ | ✔️ | +|Dynamic WinRT Component (Direct\*) | ✔️ | ❌ (blocked by cswinrt)| +|Static WinRT Component (Direct\*) | ❌ | ❌ | -## Language/Feature Support Table -|| App | WinRT Component (Dynamic) | WinRT Component (Static) | -|--|--|--|--| -|C++|✔️|✔️|❌| -|C#|✔️|❌ (blocked by cswinrt)|❌| +\*See section below on Direct vs Sample App + +### WinRT Component Support - Direct Mode and Sample App Mode + +WinRT Component preview support comes in two mode. One is "Direct" mode, another is "Sample App" mode. Direct mode means you can preview directly in-project. Sample App mode means you preview via a separate "Sample App" project. ## Limitation - Require building the project once before use @@ -31,9 +41,13 @@ Custom control's template previewing is not supported yet but is planned. Stay t - App project require a few lines of setup - WinRT component project require some setup for any nuget/external dependencies -### WinRT Component Limitation +### WinRT Component Direct Mode's Limitation + +The previewer tries its best to resolve your WinRT component's dynamic _project_, or _internal_ dependency and load them before use. This feature is known as Auto DLL Loading. Auto DLL Loading only works for project references whose output is a dynamic library. -The previewer tries its best to resolve your WinRT component's dynamic _project_ dependency and load them before use. This feature is known as Auto DLL Loading. Auto DLL Loading only works for project references whose output is a dynamic library. If your WinRT component has any _external_ dynamic dependencies, e.g. nuget/external dll dependencies (transitive or direct), you'd need to copy them to your dll's output folder so the system can pick them up. +If your WinRT component has any _external_ dynamic dependencies, e.g. nuget/external dll dependencies (transitive or direct), you'd need to copy them to your dll's output folder so the system can pick them up. + +If your library has a complex dependency graph, it is suggested that you switch to Sample App mode. ### Non-Goal @@ -41,9 +55,11 @@ The author does not believe in Designer so this project would stay only as a liv ## Getting Started +### App Project + 1. Install the [VS extension](https://marketplace.visualstudio.com/items?itemName=Roxk.winui3xamlpreview). Require VS2022 17.9+ -2. On _each of your WinUI 3 project_ that uses this feature, install the nuget +2. On your _WinUI 3 App project_ that uses this feature, install the nuget ``` nuget install WinUI3XamlPreview @@ -51,10 +67,6 @@ nuget install WinUI3XamlPreview 3. If you are using C++, add ` @@ -104,18 +114,46 @@ Note that the next steps for app project and WinRT component project are differe Make sure to replace `$YourTargetName` with your build output name. E.g. if your build output is `MyApp.exe`, the correction execution alias to add is `MyApp-WinUI3XP.exe`. -### WinRT Component Project +6. Viola! You have finished the setup for app project + +### WinRT Component Project (Direct Mode) + +1. Install the [VS extension](https://marketplace.visualstudio.com/items?itemName=Roxk.winui3xamlpreview). Require VS2022 17.9+ + +2. On your _WinUI 3 WinRT Component project_ that uses this feature, install the nuget + +``` +nuget install WinUI3XamlPreview +``` + +3. If you are using C++, add `$SampleAppProjectName` property. Make sure you replace `$SampleAppProjectName` with the name of the sample app project. E.g. if your WinRT Component's project name is `Lib`, your sample app (test app)'s project name is `LibTest`, the correct property value is `LibTest`. If you do not want to edit project file directly, you can (1) install the nuget on your _WinUI 3 WinRT Component project_, (2) edit the property by right clicking the component project in Visual Studio -> Properties -> WinUI3XamlPreview tab -> edit Launch Project. Make sure you disable the preview to save compile time. See [Configuration](#Configuration) section for more details + +5. Viola! You have finished the setup for WinRT Component proejct Sample App mode. ## Usage 1. After setup, build your project again. -2. For packaged app, deploy your app once by righting click on the project -> deploy. +2. For packaged app, deploy your app once by righting click on the project -> deploy. If you are using WinRT Component Sample App mode, make sure you build/deploy your sample app project instead of just the component project. 3. Locate the "Toggle WinUI 3 Xaml Preview" in the "Extensions" menu at the top. 4. Open any xaml file and click the toggle to launch preview, click it again to stop. You can also close the preview window to turn off live preview. @@ -124,6 +162,17 @@ The preview renders according to the following triggers: - Switching to a XAML file in the editor - Saving a XAML file +## Configuration + +![WinUI3XamlPreview's property page in Visual Studio](vs-property-page.png) + +You can configure the behavior of WinUI3XamlPreview via a dedicated property page in Visual Studio. If you are comfortable editing project file directly, you can also insert/modify properties listed below. + +|MSBuild Property|type|Behavior| +|--|--| +|`WinUI3XPEnabled`|`Bool`|`true` to enable WinUI3XamlPreview, `false` to disable. Default is true. When it's disabled, no winmd/dll are added to the project. Useful for CI/CD| +|`WinUI3XPLaunchProject`|`String`|Default is null. If specified, instead of using the XAML file's project to locate the preview app, use the specified project instead| + ## Technical Details TODO diff --git a/vs-property-page.png b/vs-property-page.png new file mode 100644 index 0000000..7634c59 Binary files /dev/null and b/vs-property-page.png differ