diff --git a/.vsts-ci.yml b/.vsts-ci.yml index d9981f4f1..1f925c2d7 100644 --- a/.vsts-ci.yml +++ b/.vsts-ci.yml @@ -1,22 +1,57 @@ +trigger: + branches: + include: + - main + - release/stable/* + - feature/* -jobs: -- template: .vsts-ci-packages.yml - parameters: - jobName: Packages +pr: + branches: + include: + - main + - release/stable/* + - feature/* -- template: .vsts-ci-linux.yml - parameters: - jobName: Linux_Tests - linux_container: unoplatform/wasm-build:3.0 +stages: +- stage: Determine_Changes + displayName: Determine Changes + jobs: + - template: build/ci/stage-determine-changes.yml -- template: .vsts-ci-windows-tests.yml - parameters: - jobName: Windows_Tests - linux_container: unoplatform/wasm-build:3.0 +- stage: Docs_Validations + displayName: Docs Validations + dependsOn: Determine_Changes + # Trigger this stage when docs files are changed + condition: or(eq(dependencies.Determine_Changes.outputs['evaluate_changes.DetermineChanges.docsOnly'], 'true'), eq(dependencies.Determine_Changes.outputs['evaluate_changes.DetermineChanges.mixedChanges'], 'true')) + jobs: + - template: build/ci/stage-docs-validations.yml -- template: .vsts-ci-macos.yml - parameters: - jobName: macOS_Tests - vmImage: macOS-12 +- stage: Packages + displayName: Packages + dependsOn: Determine_Changes + # Don't trigger this stage if only docs files are changed + condition: ne(dependencies.Determine_Changes.outputs['evaluate_changes.DetermineChanges.docsOnly'], 'true') + jobs: + - template: build/ci/stage-build-packages.yml + parameters: + jobName: Packages -- template: .vsts-ci-wsl-tests.yml +- stage: Build_Tests + displayName: Build Tests + dependsOn: Determine_Changes + # Don't trigger this stage if only docs files are changed + condition: ne(dependencies.Determine_Changes.outputs['evaluate_changes.DetermineChanges.docsOnly'], 'true') + jobs: + - template: build/ci/stage-build-linux-tests.yml + parameters: + jobName: Linux_Tests + linux_container: unoplatform/wasm-build:3.0 + - template: build/ci/stage-build-windows-tests.yml + parameters: + jobName: Windows_Tests + linux_container: unoplatform/wasm-build:3.0 + - template: build/ci/stage-build-macos-tests.yml + parameters: + jobName: macOS_Tests + vmImage: macOS-12 + - template: build/ci/stage-build-wsl-tests.yml diff --git a/License.md b/License.md index c5690cb84..2bd4fc3d2 100644 --- a/License.md +++ b/License.md @@ -1,6 +1,7 @@ + Copyright (c) Uno Platform Inc -All rights reserved. +All rights reserved. # Apache 2.0 License @@ -204,4 +205,4 @@ All rights reserved. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and - limitations under the License. \ No newline at end of file + limitations under the License. diff --git a/Readme.md b/Readme.md index e05faca34..fb614f602 100644 --- a/Readme.md +++ b/Readme.md @@ -1,6 +1,6 @@ # Uno.Wasm.Bootstrap -[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/unoplatform/Uno.Wasm.Bootstrap) +[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/unoplatform/Uno.Wasm.Bootstrap) Uno.Wasm.Bootstrap provides a simple way to package C# .NET code, and run it from a compatible browser environment. @@ -13,6 +13,7 @@ This package only provides the bootstrapping features to run a .NET assembly and This package is based on the excellent work from @praeclarum's [OOui Wasm MSBuild task](https://github.com/praeclarum/Ooui). ## Documentation + - [Using the bootstrapper](doc/using-the-bootstrapper.md) - [Debugger support](doc/debugger-support.md) - [Deploy and publish](doc/deploy-and-publish.md) @@ -35,11 +36,11 @@ This package is based on the excellent work from @praeclarum's [OOui Wasm MSBuil - [Profiling](doc/features-profiling.md) - [Node JS](doc/features-node-js.md) - [Nuget package overrides](doc/features-nuget-package-overrides.md) - - [Prefechting](doc/features-prefetch.md) + - [Prefetching](doc/features-prefetch.md) - [PWA Support](doc/features-pwa.md) - [4GB Support](doc/features-4gb.md) - [HttpRequestMessage Extensions](doc/features-httprequestmessage-extensions.md) - - [Assemblies obfuscation](doc/features-obfsucation.md) + - [Assemblies obfuscation](doc/features-obfuscation.md) - Tools - [Uno Version Checker](doc/features-version-checker.md) - [Contributing](doc/contributing.md) diff --git a/build/ci/.markdownlint.json b/build/ci/.markdownlint.json new file mode 100644 index 000000000..372eaa4eb --- /dev/null +++ b/build/ci/.markdownlint.json @@ -0,0 +1,9 @@ +{ + "default": true, + "line-length": false, + "commands-show-output": false, + "no-bare-urls": false, + "no-inline-html": false, + "no-duplicate-heading": false, + "MD051": false +} \ No newline at end of file diff --git a/build/ci/cspell.json b/build/ci/cspell.json new file mode 100644 index 000000000..4358070e9 --- /dev/null +++ b/build/ci/cspell.json @@ -0,0 +1,210 @@ +{ + "version": "0.2", + "language": "en", + "words": [ + "Avalonia", + "ambiently", + "binlog", + "Blazor", + "blockquotes", + "Bootstrapper", + "brotli", + "browsersync", + "bytecode", + "Callout", + "chatops", + "codebases", + "Codespace", + "Codespaces", + "Contoso", + "Cupertino", + "customizability", + "databinding", + "datacontext", + "datagrid", + "devs", + "Dismissable", + "Docfx", + "ellipsize", + "Expando", + "flyouts", + "Framebuffer", + "Gamepad", + "gamepads", + "Geolocation", + "globbing", + "Gyrometer", + "Hanja", + "hectopascals", + "Inlines", + "keychain", + "laggy", + "layouter", + "layouting", + "Listview", + "LLRM", + "mergeable", + "MSAL", + "msbuild", + "MVUX", + "MVVM", + "NETSDK", + "netstandard", + "oidc", + "Omnisharp", + "overscroll", + "Packt", + "parameterless", + "pickable", + "Pluralsight", + "POSIX", + "reentrantly", + "Resizetizer", + "resw", + "roadmap", + "sandboxed", + "Segoe", + "Silverlight", + "Skia", + "skiasharp", + "Storyboarded", + "struct", + "Syncfusion", + "templatable", + "templating", + "timespan", + "Tizen", + "TLDR", + "toolkits", + "triaging", + "UI's", + "unmanaged", + "Uno's", + "unoplatform", + "UWP's", + "VSIX", + "walkthrough", + "WEBASSEMBLY", + "Haptics", + "subfolders", + "interoperating", + "bitcode", + "subresource", + "SIMD" + ], + "ignoreWords": [ + "ADAL", + "addin", + "AEHD", + "appsettings", + "Authenticode", + "automagically", + "Divio's", + "emcc", + "emscripten", + "Findlay", + "Flatpickr", + "Giesel", + "GNSS", + "GPIO", + "Grigorik", + "hdpi", + "Headered", + "Hoefling", + "HRESULT", + "Icaza", + "IDBFS", + "Ilya", + "Infragistics", + "jonathanpeppers's", + "Krueger", + "libgtk", + "Liu's", + "Logpoints", + "macios", + "Matteo", + "McCaffrey", + "mdpi", + "Mergify", + "mlaunch", + "muxc", + "netstd", + "nventive", + "odel", + "Onoh", + "pdate", + "Ronica", + "Serilog", + "Singh", + "slnf", + "Stetho", + "Talkin", + "UADO", + "Udemy", + "UNOB", + "unpackaged", + "winappsdk", + "winui", + "xhdpi", + "xxhdpi", + "xxxhdpi", + "Yowza", + "wslpath", + "httprequestmessage", + "praeclarum's" + ], + "patterns": [ + { + "name": "Markdown uid", + "pattern": "^(?=uid:).*$", + "description": "" + }, + { + "name": "Markdown links", + "pattern": "\\((.*)\\)", + "description": "" + }, + { + "name": "Markdown code blocks", + "pattern": "/^(\\s*`{3,}).*[\\s\\S]*?^\\1/gmx", + "description": "Taken from the cSpell example at https://cspell.org/configuration/patterns/#verbose-regular-expressions" + }, + { + "name": "Inline code blocks", + "pattern": "\\`([^\\`\\r\\n]+?)\\`", + "description": "https://stackoverflow.com/questions/41274241/how-to-capture-inline-markdown-code-but-not-a-markdown-code-fence-with-regex" + }, + { + "name": "Link contents", + "pattern": "\\", + "description": "" + }, + { + "name": "Snippet references", + "pattern": "-- snippet:(.*)", + "description": "" + }, + { + "name": "Snippet references 2", + "pattern": "\\<\\[sample:(.*)", + "description": "another kind of snippet reference" + }, + { + "name": "Multi-line code blocks", + "pattern": "/^\\s*```[\\s\\S]*?^\\s*```/gm" + } + ], + "ignoreRegExpList": [ + "Markdown uid", + "Markdown links", + "Markdown code blocks", + "Inline code blocks", + "Link contents", + "Snippet references", + "Snippet references 2", + "Multi-line code blocks" + ], + "ignorePaths": [ + "../doc/index.md" + ] +} \ No newline at end of file diff --git a/.vsts-ci-linux.yml b/build/ci/stage-build-linux-tests.yml similarity index 98% rename from .vsts-ci-linux.yml rename to build/ci/stage-build-linux-tests.yml index a967e5bcf..4f1813746 100644 --- a/.vsts-ci-linux.yml +++ b/build/ci/stage-build-linux-tests.yml @@ -22,8 +22,8 @@ jobs: - checkout: self clean: true - - template: build/ci/gitversion.yml - - template: build/ci/dotnet-install.yml + - template: gitversion.yml + - template: dotnet-install.yml - task: UseDotNet@2 displayName: 'Use .NET SDK' diff --git a/.vsts-ci-macos.yml b/build/ci/stage-build-macos-tests.yml similarity index 96% rename from .vsts-ci-macos.yml rename to build/ci/stage-build-macos-tests.yml index b3a485cf4..d6badf5bd 100644 --- a/.vsts-ci-macos.yml +++ b/build/ci/stage-build-macos-tests.yml @@ -13,8 +13,8 @@ jobs: SourceLinkEnabled: false steps: - - template: build/ci/gitversion.yml - - template: build/ci/dotnet-install.yml + - template: gitversion.yml + - template: dotnet-install.yml - task: UseDotNet@2 displayName: 'Use .NET SDK' diff --git a/.vsts-ci-packages.yml b/build/ci/stage-build-packages.yml similarity index 97% rename from .vsts-ci-packages.yml rename to build/ci/stage-build-packages.yml index eec629dcc..b8aeb9b09 100644 --- a/.vsts-ci-packages.yml +++ b/build/ci/stage-build-packages.yml @@ -18,8 +18,8 @@ jobs: version: 8.0.100 includePreviewVersions: true - - template: build/ci/gitversion.yml - - template: build/ci/dotnet-install.yml + - template: gitversion.yml + - template: dotnet-install.yml - bash: | npm install -g conventional-changelog-cli@2.2.2 diff --git a/.vsts-ci-windows-tests.yml b/build/ci/stage-build-windows-tests.yml similarity index 99% rename from .vsts-ci-windows-tests.yml rename to build/ci/stage-build-windows-tests.yml index 68984c9f4..a037ef209 100644 --- a/.vsts-ci-windows-tests.yml +++ b/build/ci/stage-build-windows-tests.yml @@ -19,8 +19,8 @@ jobs: - checkout: self clean: true - - template: build/ci/gitversion.yml - - template: build/ci/dotnet-install.yml + - template: gitversion.yml + - template: dotnet-install.yml - task: UseDotNet@2 displayName: 'Use .NET SDK' diff --git a/.vsts-ci-wsl-tests.yml b/build/ci/stage-build-wsl-tests.yml similarity index 100% rename from .vsts-ci-wsl-tests.yml rename to build/ci/stage-build-wsl-tests.yml diff --git a/build/ci/stage-determine-changes.yml b/build/ci/stage-determine-changes.yml new file mode 100644 index 000000000..d25704d64 --- /dev/null +++ b/build/ci/stage-determine-changes.yml @@ -0,0 +1,74 @@ +jobs: +- job: evaluate_changes + displayName: 'Check for Doc Only Changes' + pool: + vmImage: 'ubuntu-latest' + steps: + - powershell: | + # Determine the context of the build (PR or push) and set the target branch accordingly + $isPR = "$(Build.Reason)" -eq "PullRequest" + + # Normalize the target branch name for PR builds or default to 'master' for push builds + $targetBranchName = $isPR ? "$(System.PullRequest.TargetBranch)" -replace 'refs/heads/', '' : "master" + Write-Host "Build context determined: $(if ($isPR) { 'Pull Request targeting ' + $targetBranchName } else { 'Push' })" + + # Fetch the target or default base branch and determine the merge base + git fetch origin $targetBranchName + $mergeBase = git merge-base HEAD "origin/$targetBranchName" + Write-Host "Merge base with '$targetBranchName' identified at $mergeBase" + + Write-Host "Comparing changes from $mergeBase..." + $gitDiffCommand = "git diff $mergeBase --name-only" + $changedFiles = Invoke-Expression $gitDiffCommand + $docsOnly = $false + $nonDocsOnly = $false + $mixedChanges = $false + $docFiles = 0 + $nonDocFiles = 0 + + if ($changedFiles) { + Write-Host "Changed files:" + Write-Host $changedFiles + } else { + Write-Host "No files have changed." + } + + foreach ($file in $changedFiles -split "`n") { + # Identifying changes as documentation: + $isDoc = $file.StartsWith("doc/") -or # Files in the 'doc/' directory + ($file -match "^[^/]+\.md$") -or # Markdown files at the root level (with no subdirectories involved) + ($file -match "^\.github/.*\.md$") -or # Markdown files within the .github folder (including its subdirectories) + ($file -match "^\.(markdownlint|cspell)\.json$") # Specific JSON files: .markdownlint.json and cspell.json + + if ($isDoc) { + $docFiles++ + } else { + $nonDocFiles++ + } + } + + Write-Host "Documentation files changed: $docFiles" + Write-Host "Non-documentation files changed: $nonDocFiles" + + if ($docFiles -gt 0 -and $nonDocFiles -eq 0) { + $docsOnly = $true + Write-Host "All changes are documentation-only." + } elseif ($docFiles -gt 0 -and $nonDocFiles -gt 0) { + $mixedChanges = $true + Write-Host "Mixed changes detected: Both documentation and non-documentation files have been modified." + } elseif ($nonDocFiles -gt 0) { + $nonDocsOnly = $true + Write-Host "Non-documentation changes detected." + } + + # Explicitly write the final values for clarity + Write-Host "Final values:" + Write-Host "docsOnly: $docsOnly" + Write-Host "nonDocsOnly: $nonDocsOnly" + Write-Host "mixedChanges: $mixedChanges" + + # Output the results as pipeline variables + Write-Host "##vso[task.setvariable variable=docsOnly;isOutput=true]$docsOnly" + Write-Host "##vso[task.setvariable variable=nonDocsOnly;isOutput=true]$nonDocsOnly" + Write-Host "##vso[task.setvariable variable=mixedChanges;isOutput=true]$mixedChanges" + name: DetermineChanges diff --git a/build/ci/stage-docs-validations.yml b/build/ci/stage-docs-validations.yml new file mode 100644 index 000000000..ac8be148f --- /dev/null +++ b/build/ci/stage-docs-validations.yml @@ -0,0 +1,42 @@ +jobs: +- job: spell_checking + displayName: 'Spell Checking Validation' + + pool: + vmImage: 'ubuntu-latest' + + steps: + - checkout: self + fetchDepth: 1 + clean: true + + - task: NodeTool@0 + inputs: + versionSpec: '18.x' + + - bash: npm install -g cspell + displayName: Install cSpell + + - bash: cspell --config $(Build.SourcesDirectory)/build/ci/cspell.json "**/*.md" "**/toc.yml" --no-progress + displayName: Run Spell Checking + +- job: markdown_link + displayName: 'Markdown Validation' + + pool: + vmImage: 'ubuntu-latest' + + steps: + - checkout: self + fetchDepth: 1 + clean: true + + - task: NodeTool@0 + inputs: + versionSpec: '18.x' + + - bash: npm install -g markdownlint-cli + displayName: Install markdownlint-cli + + - bash: markdownlint -c $(Build.SourcesDirectory)/build/ci/.markdownlint.json "**/*.md" + displayName: Run Markdown Linter diff --git a/doc/contributing.md b/doc/contributing.md index 87b312e7c..6b3775a2d 100644 --- a/doc/contributing.md +++ b/doc/contributing.md @@ -1,14 +1,16 @@ -## Debugging and contributing to the Uno WebAssembly Bootstrapper +# Debugging and contributing to the Uno WebAssembly Bootstrapper The [src/Uno.Wasm.Bootstrap.sln](src/Uno.Wasm.Bootstrap.sln) solution is a good way to build the bootstrapper itself, as well as sample solutions that validate the different features of the bootstrapper. -### Debugging in Visual Studio for Windows -- Select a sample application, such as the `Uno.Wasm.Sample` project, and press `Ctrl+F5` or run **without debugger**. +## Debugging in Visual Studio for Windows + +- Select a sample application, such as the `Uno.Wasm.Sample` project, and press `Ctrl+F5` or run **without debugger**. - The bootstrapper will be built as part of the process, and will generate a new webassembly site layout. - Once the application has built, it will run in the selected browser in the Visual Studio debug location toolbar Some tips: + - If you make modifications to the `Uno.Wasm.Bootstrap`, you may have to terminate all `msbuild.exe` processes, as they may lock files of that project. - If you make modifications to the `Uno.Wasm.Bootstrap.Cli` project, you may have to terminate the `dotnet.exe` processes that link to your solution's subfolders, as they may lock files of that project. @@ -16,33 +18,42 @@ Once the processes have been terminated, restart your build. Debugging the bootstrapper task can be done by adding a `Debugger.Launch()` statement in the `Run` method of `ShellTask.cs`. -### Testing the bootstrapper through GitPod +## Testing the bootstrapper through GitPod + You can also make contributions through GitPod, and validate that your changes are appropriate. Building and debugging samples is done through the command line. + 1. Build a sample using : - ``` + + ```shell cd src/Uno.Wasm.Sample msbuild /r /bl ``` + 1. Start the web server to serve the sample on port 8000: - ``` + + ```shell cd bin/Debug/net5.0/dist python3 server.py ``` + 1. The GitPod IDE will open a preview window with the content of the site. You may need to open the browser debugger window to see the results of the sample's execution. Click on the button below to try this out! -[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/unoplatform/Uno.Wasm.Bootstrap) +[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/unoplatform/Uno.Wasm.Bootstrap) + +## Overriding the .NET WebAssembly SDK build -### Overriding the .NET WebAssembly SDK build The msbuild property `NetCoreWasmSDKUri` allow the override of the default SDK path. The path can be a local file or remote file. To select a different sdk build: + - For `net5` projects: - - Generate a build from the `https://github.com/unoplatform/Uno.DotnetRuntime.WebAssembly` project - - Copy the `dotnet-runtime-wasm-XX-XX-Release.zip` uri or local zip file path to the `NetCoreWasmSDKUri` property -> Note that override properties require a zip file as the source, not an uncompressed folder. + - Generate a build from the `https://github.com/unoplatform/Uno.DotnetRuntime.WebAssembly` project + - Copy the `dotnet-runtime-wasm-XX-XX-Release.zip` uri or local zip file path to the `NetCoreWasmSDKUri` property +> [!NOTE] +> Override properties require a zip file as the source, not an uncompressed folder. diff --git a/doc/debugger-support.md b/doc/debugger-support.md index c9f7c8a70..097acd7d6 100644 --- a/doc/debugger-support.md +++ b/doc/debugger-support.md @@ -2,13 +2,13 @@ uid: UnoWasmBootstrap.Features.Debugger --- -## .NET for WebAssembly Debugger Support +# .NET for WebAssembly Debugger Support Debugging is supported through the integration of a .NET Core CLI component, which acts as a static files server, as well as a debugger proxy for Chrome (other browsers are not supported). -### Enable the Debugger support +## Enable the Debugger support -In order to debug an **Uno.Wasm.Boostrap** enabled project, the Mono runtime debugger must be enabled: +In order to debug an **Uno.Wasm.Bootstrap** enabled project, the Mono runtime debugger must be enabled: ```xml @@ -33,9 +33,9 @@ Finally, the `DEBUG` constant must be defined ``` -Doing so will enable the deployment of `pdb` files to the browser, and allow for the mono debugger proxy to use them. +Doing so will enable the deployment of `pdb` files to the browser, and allow for the mono debugger proxy to use them. -For the time being, you will also need to make sure that mscorlib is disabled in the Linker configuration file: +For the time being, you will also need to make sure that mscorlib is disabled in the Linker configuration file: ```xml @@ -46,10 +46,12 @@ For the time being, you will also need to make sure that mscorlib is disabled in .NET for WebAssembly now has integrated **preliminary** support for in-browser debugging. Refer to [this document for up-to-date information](https://github.com/mono/mono/tree/master/sdks/wasm#debugging) on how to set up the debugging. -### How to use the Browser debugger -The boostrapper also supports debugging directly in the browser debugging tools. +## How to use the Browser debugger + +The bootstrapper also supports debugging directly in the browser debugging tools. In Visual Studio: + - Make your project the startup project (right-click **set as startup**) - In the debugging toolbar: - Select **IIS Express** as the debugging target @@ -60,14 +62,15 @@ In Visual Studio: - Follow the instructions on the web page - You may need to refresh the original tab if you want to debug the entry point (Main) of your application. -### Debugger troubleshooting +## Debugger troubleshooting + The debugger is still under development, and here are a few things to look for: + - Breakpoints set sometimes disappear when the debugged page is reloaded -- If none of your assemblies appear in the debugger window, it's generally caused -by the debugger caching previously loaded files. Make sure to hit Ctrl+Shit+R to force -reload the debugged page. +- If none of your assemblies appear in the debugger window, it's generally caused +by the debugger caching previously loaded files. Make sure to hit Ctrl+Shit+R to force reload the debugged page. -### AOT Debugging and mono tracing (.NET 5 only) +## AOT Debugging and mono tracing (.NET 5 only) When running with PG-AOT, exceptions generally do not provide stack traces, as WebAssembly as of the MVP does not yet support stack walking. @@ -78,16 +81,18 @@ First, you'll need to add the following class to your app: ```csharp static class MonoInternals { - [DllImport("__Native")] - internal static extern void mono_trace_enable(int enable); - [DllImport("__Native")] - internal static extern int mono_trace_set_options(string options); + [DllImport("__Native")] + internal static extern void mono_trace_enable(int enable); + [DllImport("__Native")] + internal static extern int mono_trace_set_options(string options); } ``` + > [!NOTE] > In order for `__Native` to be available, you'll need to specify `` item. See [Static linking additional P/Invoke libraries](features-module-linking.md#static-linking-additional-pinvoke-libraries) for details. Then in the `Main` of your application, add the following: + ```csharp MonoInternals.mono_trace_enable(1); MonoInternals.mono_trace_set_options("E:all"); diff --git a/doc/deploy-and-publish.md b/doc/deploy-and-publish.md index 18b74fffe..1bbd278f3 100644 --- a/doc/deploy-and-publish.md +++ b/doc/deploy-and-publish.md @@ -2,7 +2,8 @@ uid: UnoWasmBootstrap.Features.Publish --- -## Publishing the build results +# Publishing the build results + The easiest way to publish the build results is to use the Visual Studio publish menu on your project. This will allow to use all the features provided by the standard experience, as described in the [Deploy to Azure App Service](https://docs.microsoft.com/en-us/visualstudio/deployment/quickstart-deploy-to-azure?view=vs-2017). The publication of the application must be done in .NET Framework hosting (and not .NET Core), as the app uses the `web.config` file for the server configuration, and to enable the use of pre-compression. @@ -14,27 +15,32 @@ For deeper integration in the publishing pipeline, the `WasmShellOutputPackagePa ASP.NET Core hosting is supported through the `Uno.Wasm.Bootstrap.Server` package. In order to host an Uno Platform App, you'll need to the following: + - Create an `ASP.NET Core Web API` project (call it `MyApp.Server`). You may need to disable swagger for the `index.html` to be served properly. - Add a NuGet reference to `Uno.Wasm.Bootstrap.Server` - In your `Program.cs` startup, add the following to setup your `WebApplication` instance: -``` -using Uno.Wasm.Bootstrap.Server; -... -app.UseUnoFrameworkFiles(); -app.MapFallbackToFile("index.html"); -``` + + ```csharp + using Uno.Wasm.Bootstrap.Server; + ... + app.UseUnoFrameworkFiles(); + app.MapFallbackToFile("index.html"); + ``` + - Add a project reference to the `Wasm` project - Build and deploy `MyApp.Server` ## Serve the Wasm app through Windows Linux Subsystem + Using Windows 10/11, serving the app through a small Web Server is done through WSL. Here's how to install it: + - Search for Ubuntu in the Microsoft Store: https://apps.microsoft.com/store/search/ubuntu - Install Ubuntu 18.04 or later, and follow the instructions during the first run - - If you have another distribution installed make sure that the 18.04 is the default using `wslconfig /s "Ubuntu-20.04"`. You can list your active distributions with `wslconfig /l` - - Note that WSL 2 is considerably slower than WSL 1 for the boostrapper scenario. You will need to set your distribution to version 1 using `wsl --set-version "Ubuntu-20.04" 1`. + - If you have another distribution installed make sure that the 18.04 is the default using `wslconfig /s "Ubuntu-20.04"`. You can list your active distributions with `wslconfig /l` + - Note that WSL 2 is considerably slower than WSL 1 for the bootstrapper scenario. You will need to set your distribution to version 1 using `wsl --set-version "Ubuntu-20.04" 1`. - Once you've built your project, you should see a path to the project dll - In the Ubuntu shell, type ``cd `wslpath "[the_path_to_your_bin_folder]\dist"` `` - Type `python3 server.py` - - If this command does not exist, run the following `sudo apt-get install python3` + - If this command does not exist, run the following `sudo apt-get install python3` diff --git a/doc/features-4gb.md b/doc/features-4gb.md index fb737e392..d83638c7d 100644 --- a/doc/features-4gb.md +++ b/doc/features-4gb.md @@ -2,13 +2,14 @@ uid: UnoWasmBootstrap.Features.4gb --- -### 4GB memory support +# 4GB memory support The support for 4GB memory space is available by adding the following configuration: + ```xml - + ``` -The configuration can also be detected at runtime using the `UNO_BOOTSTRAP_EMSCRIPTEN_MAXIMUM_MEMORY` environment variable, which will be set to `4GB` once set. +The configuration can also be detected at runtime using the `UNO_BOOTSTRAP_EMSCRIPTEN_MAXIMUM_MEMORY` environment variable, which will be set to `4GB` once set. diff --git a/doc/features-additional-files.md b/doc/features-additional-files.md index dea5d7ac9..2f393143d 100644 --- a/doc/features-additional-files.md +++ b/doc/features-additional-files.md @@ -2,33 +2,38 @@ uid: UnoWasmBootstrap.Features.AdditionalFiles --- -### Index.html content override +# Index.html content override + The msbuild property `WasmShellIndexHtmlPath` can be used to specify the path of a project-specific `index.html` file. -This file should contain the following markers, for the runtime to initialize properly: +This file should contain the following markers, for the runtime to initialize properly: + - `$(ADDITIONAL_CSS)` - `$(ADDITIONAL_HEAD)` Use this file as an example: + - [Templates/index.html](https://github.com/unoplatform/Uno.Wasm.Bootstrap/blob/main/src/Uno.Wasm.Bootstrap/Templates/index.html) for bootstrapper 8.x. - [Templates/index.html](https://github.com/unoplatform/Uno.Wasm.Bootstrap/blob/release/stable/7.0/src/Uno.Wasm.Bootstrap/Templates/index.html) for bootstrapper 7.x. - [Templates/index.html](https://github.com/unoplatform/Uno.Wasm.Bootstrap/blob/release/stable/3.3/src/Uno.Wasm.Bootstrap/Templates/index.html) for bootstrapper 3.x. - [Templates/index.html](https://github.com/unoplatform/Uno.Wasm.Bootstrap/blob/release/stable/2.1/src/Uno.Wasm.Bootstrap/Templates/index.html) for bootstrapper 2.x. -### Support for additional JS files +## Support for additional JS files Providing additional JS files is done through the inclusion of `EmbeddedResource` msbuild item files, in a project folder named `WasmScripts`. Files are processed as embedded resources to allow for libraries to provide javascript files. -### Support for additional CSS files +## Support for additional CSS files + Additional CSS files are supported through the inclusion of `EmbeddedResource` msbuild item files, in a project folder named `WasmCSS`. -### Support for additional Content files +## Support for additional Content files + Additional Content files are supported through the inclusion of `Content` files. The folder structure is preserved in the output `dist` folder. There is 3 deployment modes for content files: -* `Package`: files using `UnoDeploy="Package"` mode will be deployed in the `dist\package_` folder and the folder structure will be preserved. This is the default mode for most files (see exclusions below). -* `Root`: files using `UnoDeploy="Root"` mode will be deployed directly in the `dist\` folder and the folder structure will be preserved. -* `None`: files using the `UnoDeploy="None"` mode will be ignored and won't be deployed. +- `Package`: files using `UnoDeploy="Package"` mode will be deployed in the `dist\package_` folder and the folder structure will be preserved. This is the default mode for most files (see exclusions below). +- `Root`: files using `UnoDeploy="Root"` mode will be deployed directly in the `dist\` folder and the folder structure will be preserved. +- `None`: files using the `UnoDeploy="None"` mode will be ignored and won't be deployed. Exclusions: @@ -55,4 +60,3 @@ Asset files: `dist/package_XXXX/uno-assets.txt` contains the package relative pa A few files extensions are excluded (`UnoDeploy="None")`by default such as `*.a`, `*.bc`. `.html` files are those named `web.config` will default to `UnoDeploy="Root"`. - diff --git a/doc/features-deep-linking.md b/doc/features-deep-linking.md index ae32d6bbd..0dcb05e31 100644 --- a/doc/features-deep-linking.md +++ b/doc/features-deep-linking.md @@ -4,14 +4,14 @@ uid: UnoWasmBootstrap.Features.DeepLinking # Support for deep-linking (routes) -Deep-linking enables the path part of the URI to indicate a location that should be navigated to. +Deep-linking enables the path part of the URI to indicate a location that should be navigated to. > [!TIP] > This feature is colloquially referred to as _routing_ in the web development world. ## Use in Uno Platform applications -Apps using deep-linking typically parse the URI as part of a robust navigation system. No longer is access to resources on discrete pages complicated by repetitive UI steps. Instead, these areas can be navigated directly from a link in an email, a bookmark, or another website. When planning the capabilities of your application, it is essential to decide whether common scenarios necessitate deep-linking. +Apps using deep-linking typically parse the URI as part of a robust navigation system. No longer is access to resources on discrete pages complicated by repetitive UI steps. Instead, these areas can be navigated directly from a link in an email, a bookmark, or another website. When planning the capabilities of your application, it is essential to decide whether common scenarios necessitate deep-linking. If so, consider a navigation [system](xref:Overview.Navigation) that allows mapping route names to specific sectors of UI elements. @@ -60,4 +60,4 @@ When deep-linking is disabled, [anchor-based navigation](https://developer.mozil - [Azure Static WebApps](xref:Uno.Tutorials.AzureStaticWepApps) - [Navigation](xref:Overview.Navigation) -- [RouteMap](xref:Reference.Navigation.RouteMap) \ No newline at end of file +- [RouteMap](xref:Reference.Navigation.RouteMap) diff --git a/doc/features-dependency-management.md b/doc/features-dependency-management.md index a66141996..dcde5c0f2 100644 --- a/doc/features-dependency-management.md +++ b/doc/features-dependency-management.md @@ -2,8 +2,9 @@ uid: UnoWasmBootstrap.Features.DependencyManagement --- -### Dependency management -The Uno Bootstrapper uses RequireJS for dependency management, allowing for dependencies to be resolved in a stable manner. +# Dependency management + +The Uno Bootstrapper uses RequireJS for dependency management, allowing for dependencies to be resolved in a stable manner. For instance, a script defined this way, placed in the `WasmScripts` folder: @@ -17,7 +18,7 @@ define(() => { will be executed appropriately. -Dependencies can also be declared this way: +Dependencies can also be declared this way: ```javascript define([], function() { return MyModule; }); @@ -26,18 +27,24 @@ define([], function() { return MyModule; }); If you're taking a dependency on an [AMD](https://en.wikipedia.org/wiki/Asynchronous_module_definition) enabled library, you'll need to publish the library as it would outside of the normal require flow. As an example, to be able to use [html2canvas](https://html2canvas.hertzen.com/): + - Add the `html2canvas.js` file as an `EmbeddedResource` in the `WasmScripts` folder - Then create an additional file called `myapp.js`, also as an `EmbeddedResource` - ``` + + ```javascript require([`${config.uno_app_base}/html2canvas`], c => window.html2canvas = c); ``` + - You'll then be able to access `window.html2canvas` from C# using `eval()`. -### Using multiple dependencies -In some cases, the simple inclusion of dependencies may allow for defining a dependency graph. +## Using multiple dependencies + +In some cases, the simple inclusion of dependencies may allow for defining a dependency graph. To do so, here's an example of dependency graph: + - Add a `MyLib.js` file in the `WasmScripts` folder: + ```javascript require( [`${config.uno_app_base}/Assets/js/test1`, `${config.uno_app_base}/Assets/js/test2`], @@ -46,13 +53,17 @@ To do so, here's an example of dependency graph: } ); ``` + Make sure to set the `Build action` of the file to `EmbeddedResource`. - Then create an `Assets/js` folder in your application, then add a file named `test1.js`: + ```javascript console.log('test1.js loaded'); define({name: "test1"}); ``` + - Finally, in an `Assets/js`, add a file named `test2.js`: + ```javascript console.log('test2.js loaded'); define({ name: "test2" }); @@ -62,6 +73,4 @@ When running the application, the `MyLib.js` file will be loaded first, then wil ### Dependency management for Emscripten -Emscripten modules initialization is performed in an asynchronous way and the Bootstrapper -will ensure that a dependency that exposes a module will have finished its initialization -for starting the `Main` method of the C# code. +Emscripten modules initialization is performed in an asynchronous way and the Bootstrapper will ensure that a dependency that exposes a module will have finished its initialization for starting the `Main` method of the C# code. diff --git a/doc/features-embedded.mode.md b/doc/features-embedded.mode.md index e3062f7fc..6f4890143 100644 --- a/doc/features-embedded.mode.md +++ b/doc/features-embedded.mode.md @@ -2,7 +2,7 @@ uid: UnoWasmBootstrap.Features.EmbeddedMode --- -### Browser Embedded mode +# Browser Embedded mode By default, the project is launched with a HTML page (`index.html`). This mode is used for SPAs (Single Page Applications), but does not allow embedding into an existing webpage or application. @@ -10,7 +10,7 @@ It is possible to use the Browser Embedded mode to allow the launching using Jav 1. Add this line in your project file: - ``` xml + ```xml BrowserEmbedded ``` @@ -19,21 +19,19 @@ It is possible to use the Browser Embedded mode to allow the launching using Jav 2. In the HTML where you want to host the application, add the following: Using HTML: - ``` html + ```html