Documentation update. Netcore update.

jspuij · Mar 23, 2020 · d754754 · d754754
1 parent 2d3d487
commit d754754
Show file tree

Hide file tree

Showing 18 changed files with 183 additions and 11 deletions.
diff --git a/.github/workflows/coreosx.yml b/.github/workflows/coreosx.yml
@@ -15,7 +15,7 @@ jobs:
     - name: Setup .NET Core
       uses: actions/setup-dotnet@v1
       with:
-        dotnet-version: 3.1.102
+        dotnet-version: 3.1.200
     - name: Setup nodejs
       uses: actions/setup-node@v1
     - name: Restore packages

diff --git a/.github/workflows/corewindows.yml b/.github/workflows/corewindows.yml
@@ -15,7 +15,7 @@ jobs:
     - name: Setup .NET Core
       uses: actions/setup-dotnet@v1
       with:
-        dotnet-version: 3.1.102
+        dotnet-version: 3.1.200
     - name: Setup nodejs
       uses: actions/setup-node@v1
     - name: Setup nuget

diff --git a/.github/workflows/docfx.yml b/.github/workflows/docfx.yml
@@ -23,7 +23,7 @@ jobs:
     - name: Setup .NET Core
       uses: actions/setup-dotnet@v1
       with:
-        dotnet-version: 3.1.102
+        dotnet-version: 3.1.200
     - name: Chocolatey Action
       uses: crazy-max/[email protected]
       with:

diff --git a/BlazorWebView.sln b/BlazorWebView.sln
@@ -57,25 +57,26 @@ EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "pages", "pages", "{38F7D1E9-A604-4CC1-96B9-73E76E4EAA6D}"
 	ProjectSection(SolutionItems) = preProject
 		docs\pages\index.md = docs\pages\index.md
+		docs\pages\prepare.md = docs\pages\prepare.md
 		docs\pages\toc.yml = docs\pages\toc.yml
 	EndProjectSection
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = ".github", ".github", "{33388780-DC1F-4126-96FA-8DDA89481E21}"
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "workflows", "workflows", "{6C568249-8365-4CA4-B207-914F53457471}"
 	ProjectSection(SolutionItems) = preProject
+		.github\workflows\coreosx.yml = .github\workflows\coreosx.yml
 		.github\workflows\corewindows.yml = .github\workflows\corewindows.yml
 		.github\workflows\docfx.yml = .github\workflows\docfx.yml
-		.github\workflows\coreosx.yml = .github\workflows\coreosx.yml
 	EndProjectSection
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "BlazorWebView.Android", "src\BlazorWebView.Android\BlazorWebView.Android.csproj", "{9CD52AD4-1753-4239-A235-5527CDFCD3BA}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "BlazorWebView.Android", "src\BlazorWebView.Android\BlazorWebView.Android.csproj", "{9CD52AD4-1753-4239-A235-5527CDFCD3BA}"
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "BlazorApp.Android", "sample\BlazorApp.Android\BlazorApp.Android.csproj", "{6870BD0A-8ECA-4989-B5CA-239A7FB4BF24}"
 EndProject
-Project("{9344BDBB-3E7F-41FC-A0DD-8665D75EE146}") = "BlazorWebView.Wpf", "src\BlazorWebView.Wpf\BlazorWebView.Wpf.csproj", "{1C68285B-41B6-4DCC-A120-405DB863E7D4}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "BlazorWebView.Wpf", "src\BlazorWebView.Wpf\BlazorWebView.Wpf.csproj", "{1C68285B-41B6-4DCC-A120-405DB863E7D4}"
 EndProject
-Project("{9344BDBB-3E7F-41FC-A0DD-8665D75EE146}") = "BlazorApp.Wpf", "sample\BlazorApp.Wpf\BlazorApp.Wpf.csproj", "{F35D94BB-F029-4CF5-A49F-48B95CCA56BD}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "BlazorApp.Wpf", "sample\BlazorApp.Wpf\BlazorApp.Wpf.csproj", "{F35D94BB-F029-4CF5-A49F-48B95CCA56BD}"
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution

diff --git a/docs/docfx.json b/docs/docfx.json
@@ -5,8 +5,12 @@
         {
           "src": "../",
           "files": [
-            "src/**.csproj"
-          ]
+            "src/BlazorWebView/BlazorWebView.csproj",
+            "src/BlazorWebView.Android/BlazorWebView.Android.csproj",
+            "src/BlazorWebView.iOS/BlazorWebView.iOS.csproj",
+            "src/BlazorWebView.Mac/BlazorWebView.Mac.csproj",
+            "src/BlazorWebView.Wpf/BlazorWebView.Wpf.csproj"
+          ],
         }
       ],
       "dest": "ref",

diff --git a/docs/images/addnewproject1.png b/docs/images/addnewproject1.png
diff --git a/docs/images/addnewproject2.png b/docs/images/addnewproject2.png
diff --git a/docs/images/addnewproject3.png b/docs/images/addnewproject3.png
diff --git a/docs/images/browsererror.png b/docs/images/browsererror.png
diff --git a/docs/images/builderrors.png b/docs/images/builderrors.png
diff --git a/docs/images/finalstructure.png b/docs/images/finalstructure.png
diff --git a/docs/images/newproject1.png b/docs/images/newproject1.png
diff --git a/docs/images/newproject2.png b/docs/images/newproject2.png
diff --git a/docs/images/newproject3.png b/docs/images/newproject3.png
diff --git a/docs/pages/index.md b/docs/pages/index.md
@@ -41,6 +41,8 @@ to follow the tutorials for every platform. They are available below:
 * [Xamarin Mac](mactutorial.md)
 * [WPF](wpftutorial.md)
 
+[Some guidance](prepare.md) on how to setup a Blazor project to best accomodate targeting multiple platforms is available as well.
+
 ### Install the nugets
 
 In general you need to add one of the nuget packages specific for your platform to your project:

diff --git a/docs/pages/prepare.md b/docs/pages/prepare.md
@@ -0,0 +1,153 @@
+# Prepare a Blazor project
+
+We start the preparations by generating a new Blazor Webassembly project from Visual Studio.
+Make sure you have the WebAssembly templates installed by following the [instructions in the
+documentation](https://docs.microsoft.com/en-us/aspnet/core/blazor/get-started?view=aspnetcore-3.1&tabs=visual-studio).
+
+>We will use a WebAssembly project for these preparations, but the steps for Server Side
+Blazor are roughly the same.
+
+Create a new project using the settings below:
+
+# [Create Page 1](#tab/createpage-1)
+
+![New project, page 1](../images/newproject1.png)
+
+# [Create Page 3](#tab/createpage-2)
+
+![New project, page 2](../images/newproject2.png)
+
+# [Create Page 3](#tab/createpage-3)
+
+![New project, page 3](../images/newproject3.png)
+
+***
+
+## Add a shared RCL project
+
+To prepare a Blazor project for use with a BlazorWebView it is best to move all dynamic
+Blazor content to a Razor Class Library, and keep only the static content inside the
+WebAssembly project. We do this by adding a new project to the solution first:
+
+# [Add Project 1](#tab/addpage-1)
+
+![Add New project, page 1](../images/addnewproject1.png)
+
+# [Add Project 2](#tab/addpage-2)
+
+![Add New project, page 2](../images/addnewproject2.png)
+
+# [Add Project 3](#tab/addpage-3)
+
+![Add New project, page 3](../images/addnewproject3.png)
+
+***
+
+
+We can delete all content that has been generated as an example in the RCL project,
+as we will move over the content from the WebAssembly project shortly. Don't delete
+the wwwroot folder itself, we will use that later on.
+
+Finally add a reference from the WebAssembly project to the shared project:
+
+  * Right click `Dependencies` node in the solution explorer of the WebAssembly project.
+  * Select `Add reference...`
+  * In the dialog that is opened, click `Projects` and `Solution`.
+  * Select your shared RCL project.
+
+## Moving over the neccesary files and folders.
+
+Now move over the following items from the WebAssembly project to the shared project,
+leaving only the favicon.ico and index.html files in the wwwroot behind:
+
+* Pages
+* Shared
+* _Imports.razor
+* App.razor
+* wwwroot/css
+* wwwroot/sample-data
+
+You'll arrive at the following structure:
+
+![Final structure](../images/finalstructure.png)
+
+## Clean up the build errors.
+
+Now build your solution. You'll get a list of build errors that need to be adressed:
+
+![build errors](../images/builderrors.png)
+
+We will fix these one by one:
+
+* First we change the namespaces in _Imports.Razor to match the shared library instead of
+  the WebAssembly project:
+
+```cshtml-razor
+@using System.Net.Http
+@using Microsoft.AspNetCore.Components.Forms
+@using Microsoft.AspNetCore.Components.Routing
+@using Microsoft.AspNetCore.Components.Web
+@using Microsoft.JSInterop
+<!-- change these last two lines to match the namespaces of your shared library !-->
+@using BlazorWebView.Tutorial
+@using BlazorWebView.Tutorial.Shared
+```
+* Next add a nuget reference to `Microsoft.AspNetCore.Blazor.HttpClient` to the shared project
+  as well (It is already in the webassembly project).
+* Finally we add a using statement to the Program.cs folder in the webassembly project to
+  resolve the App class at a new location:
+```csharp
+using System;
+using System.Collections.Generic;
+using System.Threading.Tasks;
+using System.Text;
+using Microsoft.AspNetCore.Components.WebAssembly.Hosting;
+using Microsoft.Extensions.DependencyInjection;
+// Add this line and have it match the location of the App class.
+using BlazorWebView.Shared;
+
+namespace BlazorWebView.Tutorial
+{
+    public class Program
+    {
+        public static async Task Main(string[] args)
+        {
+            var builder = WebAssemblyHostBuilder.CreateDefault(args);
+            builder.RootComponents.Add<App>("app");
+
+            builder.Services.AddBaseAddressHttpClient();
+
+            await builder.Build().RunAsync();
+        }
+    }
+}
+```
+
+The project should now build without any errors. Let's move on and try to run it:
+
+## Solving some runtime problems
+
+Click Debug or press F5 to build and run the project. A browser page will open that looks like this:
+
+![browser error](../images/browsererror.png)
+
+This is because the files we have moved from the webassembly wwwroot folder to the shared project
+wwwroot folder are not copied to the output directory. This is why blazor webassembly cannot find
+them. The easiest way to solve this, is by editing the shared .csproj file directly. You can do
+this by right-clicking the file in the solution explorer and choosing "Edit project file" from
+the context menu.
+Next add the following content inside the `<project>` tag to change the copy behaviour for all
+content inside the wwwroot folder:
+
+```xml
+  <ItemGroup>
+    <Content Update="wwwroot\**\*">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </Content>
+  </ItemGroup>
+```
+
+Press F5 again. The project should now build, run and the sample should be in working order.
+Congratulations! You've completed the preparations and are ready to move on to one of the
+tutorials. The source code so far is in this branch:
+
diff --git a/docs/pages/toc.yml b/docs/pages/toc.yml
@@ -1,4 +1,16 @@
 - name: Introduction
   items:
     - name: Summary
-      href: index.md
+      href: index.md
+- name: Tutorial
+  items:
+    - name: Preparations
+      href: prepare.md
+    - name: Android
+      href: androidtutorial.md
+    - name: iOS
+      href: iostutorial.md
+    - name: Mac
+      href: mactutorial.md
+    - name: WPF
+      href: wpftutorial.md
diff --git a/src/BlazorWebView/BlazorWebView.xml b/src/BlazorWebView/BlazorWebView.xml