These instructions will get you started using Frogui. The steps will get easier, but for now you are a pioneer venturing to places few have been! In that spirit, there are several issues to be aware of that will make you crazy if you don't know how to work with them, which are also discussed below.
Step 1 - Install Visual Studio 2017 (or beyond) on Windows
Frogui has only been tested using Visual Studio 2017 on Windows. If you do not already have Visual Studio 2017 installed, you may download the free Visual Studio Community 2017 edition.
Step 2 - Install .NET Standard 2.0 (or beyond)
If your Visual Studio is up to date, it should already be installed. You can check the Microsoft announcement and this blog for more info.
Step 3 - Clone or download the Frogui GitHub repo
Currently, the repo is used to hold the sample Visual Studio solution. Clone or download the Frogui repo.
Step 4 - Load Samples.sln into Visual Studio
The repo has a Samples folder which contains the Samples.sln solution; open this solution into Visual Studio.
It's very possible yellow warning triangles will appear within the various project dependencies warning that the NuGet could not be found or is out of date. For example, for the Demo project:
▷ check Solution 'Samples' → Demo → Dependencies → NuGut → Lesarde.Frogui.Wasm, and the other dependencies. The next step should help.
Step 5 - Get latest NuGet package
Although the projects are all set to use the Lesarde.Frogui.Wasm Nuget package, there may be a newer package. There may be other dependent packages that need updateding as well. Update all the projects using:
▷ Right-click solution→Manage NuGet Packages for Solution→Updates, and if there is a newer version, update all the dependent projects.
Step 6 - Build the Demo project
From within Visual Studio, build the Demo project. There should be no compiler errors, though you may see a variety of warnings. Internally, two builds are happening:
a standard build, which uses ASP.NET Core
outputs assemblies to ...samples\demo\bin\debug-or-release\netcoreapp2.1 folder
outputs final bits to ...\samples\demo\wwwroot folder
a WebAssembly (wasm) build
outputs everything to ...\samples\demo\debug-or-release\wasm folder
At this step we are only concerned with the standard build, which is how Frogui is debugged. Presently, there is no way to debug the wasm build.
Note: when creating your own projects, there also will be dual builds. Use the standard build for general development and debugging, and the release wasm build for production.
Step 7 - Debug or Run the Demo project
From within Visual Studio, either run the Demo project with or without debugging. At start-up, a browser window should pop-up. You should first see an indication of loading followed by the demo app's home screen:
If you see something like the image above, then everything is working so far.
Problem App never gets past loading
There can be a variety of reasons the app never fully loads, and most are due to a bug. If you would like us to help figure out the problem, seeing the browser's console output is usually very helpful.
Step 8 - Run the wasm Demo project
Currently, it is not possible to debug or run the wasm build from within Visual Studio. In order to run it you will need a web server.
You may have a favorite web server already installed. Some options follow. Configuring web servers is out of the scope of this guide. However, if there is demand we'll add a simpler solution.
Regardless of what you use as a web server, it will be necessary that it is configured to map the .wasm file extension to the application/wasm MIME type.
Python Web Server
A lightweight Python web server script is included, so Python will need to be installed. Locate the server.py and FroguiWeb.bat files, which are copied into build output folders. For example, the debug wasm build's output folder would be:
Note that the application/wasm MIME type has already been mapped. The FroguiWeb.bat runs the script using the py command, which is new to Python 3, and definitely will need to be edited to find your python. If you are using an other python, edit the script to use the python command instead.
Since these file will not change often, you may want to copy them to someplace that can be reached without much typing from within a Windows command prompt. For instance, if copied to a folder that can be found by the Windows PATH environment variable, all you'll have to type is:
Test out the server in a Windows command prompt (here are some how-to tips). If you see something like this, you know it's working:
('python 3 serving at port', 8000)
The script uses port 8000 but can be edited to use other ports. If you are having problems getting the Python web server running, check this Stackoverflow question.
IIS Express Web Server
IIS Express is a handy option that you may already have installed. A new MIME type can be added to a .config file using something like this:
▷ <mimeMap fileExtension=".wasm" mimeType="application/wasm" />
You can read more able IIS Express and MIME types on this blog.
Step 9 - Build the Demo project if not already done
Back in Visual Studio, if you have not already build the Demo project do so now. Note that the output will either be in a debug or release folder depending on your current settings.build the Demo project. If you have no errors then you're ready to go.
Check out issue #4, which will definitely be a regular problem for now.
Step 10 - Start the web server
Either start your own web server or the one provided. If you use FroguiWeb then make sure you are in the proper folder within the command prompt. For instance, if you built Hello as debug, then it would be in a relative folder, such as:
Step 11 - Start the app
Open your browser of choice, and type the following as the URL:
If that doesn't work try:
If all is well, you will see the same scenes depicted in step 7.
Tips and Troubleshooting
Here are some tips to help you out. Please share any ideas you have to improve the experience.
Demo has serious intermittent issues on iOS devices, less so on Android.
The build system does not property detect when XAML files need to be rebuilt. To force a rebuild, delete the associated .g.cs file.
Check GitHub regularly for issues. And please report them as well!
The web server may sometimes lock the components when running. If build is having trouble overwriting binaries, try restarting server.
If something goes wrong within the browser, use the browser DevTool's console window to see output (F12 key).
The current build system actually does two builds: phase-1 for standard build and phase-2 for the wasm build. It's possible that phase-1 succeeds but phase-2 fails. Keep an eye on this and report if noticed.
Occasionally browsers cache files in such a way that you can't actually see the latest builds. If you are suspicious that you are not using fresh bits, clear your browser history.
If you change your project and a Visual Studio Build does nothing, try Rebuild, or Clear + Rebuild.
If you are new to using .NET Core and .NET Standard, they are different. Your "main" Frogui projects should always be .NET Standard. Here's a good article on the subject, x.NET Standard - Demystifying .NET Core and .NET Standard.