Using BAT

Table of Contents

• Solution Structure
• Adding your code
• Configurations and Customizing the solution
  • API-only Application
  • appsettings.json
  • Blazor Render Mode
• Next steps

Solution Structure

The solution generated from the Blazor Admin Template has the following structure:

flowchart LR
	Libs("`**Libs**
		Internal libraries, might be migrated to their own NuGet package in the future.`")
    Shared("`**Shared**
        Common code shared by other projects.`")
    Shared.EF("`**Shared.EF**
        Data access using Entity Framework.`")
	Shared.Api("`**Shared.Api**
		Common code for APIs.`")		
    Api("`**Api**
        RESTful API server.`")
    Blazor.App("`**Blazor.App**
        Shared Blazor components.`")
    Blazor("`**Blazor**
        Blazor Server project, also solution's startup project.`")
    Blazor.Client("`**Blazor.Client**
        Blazor WebAssembly (WASM) project.`")

	Libs --refby--> Shared

    Shared --refby--> Shared.EF

	Shared --refby--> Shared.Api
    Shared.EF --refby--> Shared.Api

	Shared.Api --refby--> Api

    Shared --refby--> Blazor.App

    Blazor.App --refby--> Blazor.Client

    Api --refby--> Blazor
    Blazor.App --refby--> Blazor
    Blazor.Client --refby--> Blazor

	Demo.Shared(["`**Demo.Shared**
        Common code shared by other demo projects.`"])
	Demo.Api(["`**Demo.Api**
        Demo RESTful APIs.`"])
	Blazor.Demo.App(["`**Blazor.Demo.App**
        Demo Blazor components.`"])
	
	style Demo.Shared stroke-dasharray: 5 5
	style Demo.Api stroke-dasharray: 5 5
	style Blazor.Demo.App stroke-dasharray: 5 5

	Shared --refby--> Demo.Shared
	Shared.EF --refby--> Demo.Shared
	Demo.Shared --refby--> Demo.Api
	Shared.Api --refby--> Demo.Api
	Demo.Shared --refby --> Blazor.Demo.App
	Blazor.App --refby--> Blazor.Demo.App

	Demo.Api --refby--> Api
	Demo.Api --refby--> Blazor
	Blazor.Demo.App --refby--> Blazor
	Blazor.Demo.App --refby--> Blazor.Client

Loading

Assuming the variable ${BASENAME} is set to MyApp, which is the name of the solution created from the template.

• Base projects:
  • Project Libs (directory ${BASENAME}.Libs): Internal libraries, that might be migrated to their own NuGet package in the future.
  • Project Shared (directory ${BASENAME}.Shared): Common code shared by other projects in the solution.
  • Project Shared.EF (directory ${BASENAME}.Shared.EF): Data access implemented using Entity Framework.
  • Project Shared.Api (directory ${BASENAME}.Shared.Api): Common code for APIs.
  • Project Api (directory ${BASENAME}.Api): RESTful API server.
  • Project Blazor.App (directory ${BASENAME}.Blazor/${BASENAME}.Blazor.App): Shared Blazor components used by both Blazor Server and Blazor WebAssembly (WASM) projects.
  • Project Blazor.Client (directory ${BASENAME}.Blazor/${BASENAME}.Blazor.Client): Blazor WebAssembly (WASM) project.
  • Project Blazor (directory ${BASENAME}.Blazor/${BASENAME}.Blazor): Blazor Server project. This project is set as the solution's startup project.
• Demo projects:
  • Project Demo.Shared (directory ${BASENAME}.Demo.Shared): Common code shared by other demo projects.
  • Project Demo.Api (directory ${BASENAME}.Demo.Api): Demo RESTful APIs.
  • Project Blazor.Demo.App (directory ${BASENAME}.Blazor/${BASENAME}.Blazor.Demo.App): Demo Blazor components.

The Blazor Admin Template follows these conventions:

• The Shared project is a classlib used for code shared across all projects in the solution.
• The Shared.EF project is also a classlib, containing data access code using Entity Framework. It’s intended to be used by all projects that interact with the database (typically backend/API projects).
• The Shared.Api project is a webapi project for code shared across all API projects in the solution.
• The Api project is a webapi that hosts the RESTful API server and contains the API implementation.
• The Blazor.Client project contains the bootstrap code for the Blazor WebAssembly (WASM) frontend.
• The Blazor project contains the bootstrap code for the Blazor Server frontend.
• The Blazor.App project is a razorclasslib where Blazor components implementing business logic reside. These components are shared by both the Blazor Server and Blazor WASM projects.

The Blazor project is configured as the startup project in the solution. Running it will launch the application. The Api project is not set as a startup project by default but can be run independently if needed.

Feel free to adjust the solution structure to match your needs or conventions. The template is designed to be flexible and can be customized as required.

Adding your code

Assuming the variable ${BASENAME} is set to MyApp, which is the name of the solution created from the template.

After generating a solution from the Blazor Admin Template, you can start adding your code to build the application.

For small applications (e.g., PoCs or MVPs), you can add code directly to the base projects: Shared, Shared.xxx, Api, and Blazor.App.

For larger or more complex applications, it's recommended to organize your code into separate projects per module or feature. This approach helps maintain a clean and scalable codebase. Additional projects can follow the same conventions as the base projects. For example:

• Demo.Shared (located in the directory ${BASENAME}.Demo.Shared) - a classlib containing shared code used across demo-related projects.
• Demo.Api (located in the directory ${BASENAME}.Demo.Api) - a webapi project hosting demo-specific REST APIs.
• Blazor.Demo.App (located in the directory ${BASENAME}.Blazor/${BASENAME}.Blazor.Demo.App) - a razorclasslib demo Blazor components that encapsulate business logic.

If you follow this modular structure, remember to reference the new projects from the base projects:

Api references <module>.Api:

The base Api project serves as the entry point for the API server. To enable automatic discovery of controllers in module-specific API projects (e.g., Demo.Api), the base Api project must reference them.

Once your module projects are created, you’ll need to do two things to integrate the module API project: add a reference to it from the base Api project. It can be done with the following command:

$ dotnet add ${BASENAME}.Api/${BASENAME}.Api.csproj reference ${BASENAME}.Demo.Api/${BASENAME}.Demo.Api.csproj

and include its assembly name in the Bootstrap.Assemblies section of the Api project's appsettings.json:

  // Custom bootstrapping settings
  "Bootstrap": {
    // additional assemblies to look for bootstrappers
    "Assemblies": [
      "MyApp.Demo.Api",
	  ...
    ]
  },

Blazor references <module>.Api and Blazor.<module>.App:

Similarly, the base Blazor project must reference both the module API project (e.g., Demo.Api) and the module Blazor component project (e.g., Blazor.Demo.App). This ensures that the base Blazor project can discover and use Blazor components and APIs provided by the module projects.

Once your module projects are created, add references from the base Blazor project to both the module API and Blazor component projects using the following commands:

$ dotnet add ${BASENAME}.Blazor/${BASENAME}.Blazor/${BASENAME}.Blazor.csproj reference ${BASENAME}.Demo.Api/${BASENAME}.Demo.Api.csproj

$ dotnet add ${BASENAME}.Blazor/${BASENAME}.Blazor/${BASENAME}.Blazor.csproj reference ${BASENAME}.Blazor/${BASENAME}.Blazor.Demo.App/${BASENAME}.Blazor.Demo.App.csproj

and include their assembly names in the Bootstrap.Assemblies section of the Blazor project's appsettings.json:

  // Custom bootstrapping settings
  "Bootstrap": {
    // additional assemblies to look for bootstrappers
    "Assemblies": [
      "MyApp.Demo.Api",
      "MyApp.Blazor.Demo.App",
	  ...
    ]
  },

Blazor.Client references Blazor.<module>.App:

The Blazor.<module>.App project contains Blazor components that encapsulate business logic. To ensure these components are discoverable, make sure to complete three following steps to integrate the module Blazor component project (e.g., Blazor.Demo.App) into the Blazor.Client project:

Add a reference from the Blazor.Client project to the module Blazor component project. It can be done with the following command:

$ dotnet add ${BASENAME}.Blazor/${BASENAME}.Blazor.Client/${BASENAME}.Blazor.Client.csproj reference ${BASENAME}.Blazor/${BASENAME}.Blazor.Demo.App/${BASENAME}.Blazor.Demo.App.csproj

Add the module Blazor component project's assembly name to the Bootstrap.Assemblies section in the Blazor.Client project's appsettings.json:

  // Custom bootstrapping settings
  "Bootstrap": {
    // additional assemblies to look for bootstrappers
    "Assemblies": [
      "MyApp.Blazor.Demo.App",
	  ...
    ]
  },

Include the module assembly name in the Blazor.Client project's Routes.razor:

<CascadingAuthenticationState>
    <Router AppAssembly="typeof(_Imports).Assembly"
			AdditionalAssemblies="new[] { typeof(Bat.Blazor.Demo.App._Imports).Assembly, ... }">
        <Found Context="routeData">
		...

Configurations and Customizing the solution

Assuming the variable ${BASENAME} is set to MyApp, which is the name of the solution created from the template.

Before implementing business logic, you may want to configure and customize the generated solution to better suit your needs. There are some key configurations and customizations to consider:

API-only Application

If you only need a RESTful API server, you can remove the Blazor-related projects from the solution. You can do so using the following commands:

$ cd /workspace/${BASENAME}

$ dotnet sln remove ${BASENAME}.Blazor/${BASENAME}.Blazor/${BASENAME}.Blazor.csproj
Project `MyApp.Blazor\MyApp.Blazor\MyApp.Blazor.csproj` removed from the solution.

$ dotnet sln remove ${BASENAME}.Blazor/${BASENAME}.Blazor.Client/${BASENAME}.Blazor.Client.csproj
Project `MyApp.Blazor\MyApp.Blazor.Client\MyApp.Blazor.Client.csproj` removed from the solution.

$ dotnet sln remove ${BASENAME}.Blazor/${BASENAME}.Blazor.App/${BASENAME}.Blazor.App.csproj
Project `MyApp.Blazor\MyApp.Blazor.App\MyApp.Blazor.App.csproj` removed from the solution.

$ dotnet sln remove ${BASENAME}.Blazor/${BASENAME}.Blazor.Demo.App/${BASENAME}.Blazor.Demo.App.csproj
Project `MyApp.Blazor\MyApp.Blazor.Demo.App\MyApp.Blazor.Demo.App.csproj` removed from the solution.

Note: These commands only remove the projects from the solution file. If you want to delete their files entirely, you’ll need to manually delete the corresponding directories.

You may also want to set the Api project as the startup project. In Visual Studio, right-click the Api project in Solution Explorer and select Set as Startup Project.

appsettings.json

There are 3 key appsettings.json files in the solution:

• ${BASENAME}.Api/appsettings.json
• ${BASENAME}.Blazor/${BASENAME}.Blazor/appsettings.json
• ${BASENAME}.Blazor/${BASENAME}.Blazor.Client/wwwroot/appsettings.json

If you're building an API-only application, you can ignore the appsettings.json files in the Blazor projects. In fact, you can remove the entire Blazor project directories, files, and related resources from the solution if they’re not needed.

Likewise, if you are building a Blazor application (integrated with an API backend), you can ignore the appsettings.json file in the API project.

For Blazor applications:

• The appsettings.json in wwwroot of the Blazor Client project serves as a lightweight configuration for the WebAssembly (WASM) mode.
• The appsettings.json in the Blazor (Server) project is the primary configuration file.

Blazor Render Mode

The Blazor projects are configured to use interactive auto-rendering mode by default. To change the render mode, update the code in the <head> and <body> sections of the ${BASENAME}.Blazor/${BASENAME}.Blazor/Components/App.razor file.

In the <head> section:

    <!--
        Docs: https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes
        - Recommend to turn off prerender (prerender: false)
        - new InteractiveServerRenderMode(...) to use interactive SSR.
        - new InteractiveWebAssemblyRenderMode(...) to use interactive CSR.
        - new InteractiveAutoRenderMode(...) to use "auto" mode.
    -->
    <HeadOutlet @rendermode="new InteractiveAutoRenderMode(prerender: false)" />
</head>

And in the <body> section:

<body>
    <!--
        Docs: https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes
        - Recommend to turn off prerender (prerender: false)
        - new InteractiveServerRenderMode(...) to use interactive SSR.
        - new InteractiveWebAssemblyRenderMode(...) to use interactive CSR.
        - new InteractiveAutoRenderMode(...) to use "auto" mode.
    -->
    <Routes @rendermode="new InteractiveAutoRenderMode(prerender: false)" />
    <script src="_framework/blazor.web.js"></script>

For more details, see the official documentation: ASP.NET Core Blazor render modes.

Next steps

• Deep dive into the template features.
• Explore the How-to guides for common tasks and configurations.