XS Blazor UI Components - Maintenance Guide

1. Synopsis

  • This document describes the process for maintaining the XS.Lib.Blazor.UIComponents library.

  • Refer to the Developers Guide for usage.

2. Requirements

2.1. .NET 7.x

2.2. Visual Studio 2022

2.3. Node.js

  1. Download and install the latest node.js for Windows.

  2. Open a cmd window to install jQuery:

    npm i --save-dev @types/jquery    (1)
npm i --save-dev @types/bootstrap (2)
npm install -g typescript
npm install @types/blazor
    1 Install jQuery.
    2 Bootstrap may not be needed.

3. Custom UI Component Library Project Setup

3.1. TypeScript (node.js)

3.1.1. Reference Docs

  1. Doc one

  2. Doc two

3.1.2. Install

  1. Install Node.js.

  2. Install the Microsoft.TypeScript.MSBuild package from NuGet:

    Install-Package Microsoft.TypeScript.MSBuild

  3. Create a tsconfig.json file which specifies the target version of JavaScript that the transpiler will compile to:

    Expand for tsconfig.json source 
    {
  "compilerOptions": {
    "target": "ES2018",
    "module": "ES2020",
    "sourceMap": true,
    "pretty": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["wwwroot/js/*.ts"],
  "compileOnSave": true,
  "$schema": "https://json.schemastore.org/tsconfig",
  "display": "Recommended"
}

  4. Update the .csproj file with a TypeScriptCompile tag that will point to our .ts files:

    Expand for .csproj source 
    	<ItemGroup>
		<None Include="compilerconfig.json" />
		<None Include="tsconfig.json" />
		<None Include="XS-icon-512x512.png">
			<Pack>True</Pack>
			<PackagePath></PackagePath>
		</None>
		<PackageReference Include="BuildWebCompiler" Version="1.12.405" />
		<PackageReference Include="ClosedXML" Version="0.105.0" />
		<PackageReference Include="Microsoft.AspNetCore.Components.Web" Version="9.0.5" />
		<PackageReference Include="Microsoft.TypeScript.MSBuild" Version="5.8.3">
			<PrivateAssets>all</PrivateAssets>
			<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
		</PackageReference>
		<PackageReference Include="System.Linq.Dynamic.Core" Version="1.6.5" />
		<PackageReference Include="YamlDotNet" Version="16.3.0" />
		<!--Points to our TypeScript files which will be compiled to Javascript-->
		<TypeScriptCompile Include="wwwroot/js/*.ts" />                       (1)
		<Compile Remove="docs\**" />
		<Compile Remove="Services\**" />
		<Content Remove="docs\**" />
		<Content Remove="Services\**" />
		<EmbeddedResource Remove="docs\**" />
		<EmbeddedResource Remove="Services\**" />
		<None Remove="docs\**" />
		<None Remove="Services\**" />
		<TypeScriptCompile Remove="docs\**" />
		<TypeScriptCompile Remove="Services\**" />
	</ItemGroup>
    1 Points to our TypeScript files which will be compiled to Javascript.
    This is probably not needed since the tsconfig.json has an include key.

3.2. SCSS (Web Compiler)

  • Install the Web Compiler extension

  1. Click on Extensions  Manage Extensions  Browse

  2. Search for Web Compiler 2022

  3. Click on the Install button

  4. Now close Visual Studio and wait for the installer to appear. Follow the steps to install the extension.

    It can take a few seconds for the installer to appear. Wait for the installer to finish before re-opening Visual Studio.

  • Follow this link which contains instructions on how to set up Sass compilation for Blazor .

3.3. NuGet Setup

  • Source documentation can be found here

3.3.1. Private NuGet Server Setup

3.3.2. Exclude Files from the NuGet Package

  • For files that should not be included in the package (e.g., the following files), change the Build Action from Content to None.

    1. compilerconfig.json

    2. tsconfig.json

3.3.3. Create NuGet Package

General instructions can be found here.

Set Package Properties

  • Right mouse click on the Com.XS.Lib.UI.Blazor project and select Properties.

  • Select Package in the left menu. Alter package settings as needed using the following as a guide:

    Setting Value

    Package ID

    XS.Lib.Blazor.UIComponents

    Package Title

    XS Blazor UI Component Library

    Package Version

    1.0.6

    Authors

    Codey Martinez

    Company

    Xackley! Studio, LLC

    Product

    XS Blazor UI Component Library

    Description

    A UI Component Library for Microsoft’s Blazor free and open-source web framework.
Build Package

  • Confirm that you are building a Release build.

  • Right mouse click on the Com.XS.Lib.UI.Blazor project and select Pack which will build the NuGet Package.

Push Package to a NuGet Repo
Currently hosting on MyGet.

  1. Right mouse click on the Com.XS.Lib.UI.Blazor project and select Open in Terminal.

  2. This will leave you in …​\Com.XS.Lib.UI.Blazor\Com.XS.Lib.UI.Blazor.

  3. Now go to bin\Release:

    cd .\bin\Release\

  4. This will leave you in …​\Com.XS.Lib.UI.Blazor\Com.XS.Lib.UI.Blazor\bin\Release.

  5. There should be packages named XS.Lib.Blazor.UIComponents.x.x.x.nupkg here.

  6. Push the package to the appropriate repo:

    • MyGet

      Command to Run
      dotnet nuget push XS.Lib.Blazor.UIComponents.1.0.1.nupkg --api-key 1cf63307-027a-4f3a-962e-30ab3ca8a29e --source https://www.myget.org/F/xs/api/v2/package (1)
      Sample Output
      Pushing XS.Lib.Blazor.UIComponents.0.0.1-rc.1.nupkg to 'https://www.myget.org/F/xs/api/v2/package'... (2)
  PUT https://www.myget.org/F/xs/api/v2/package/
  Created https://www.myget.org/F/xs/api/v2/package/ 1244ms
Your package was pushed. (3)
      1 Modify this command using the current package name e.g., XS.Lib.Blazor.UIComponents.1.0.17.nupkg and the actual API Access Token.
      2 Output
      3 Confirmation

    • GitHub

      Not fully researched yet. This is incomplete! 
      dotnet nuget push "bin/Release/XS.Lib.Blazor.UIComponents.0.0.1-rc.1.nupkg"  --api-key YOUR_GITHUB_PAT --source "github"

    • NuGet

      TBA

    • Private Xackley! Studio, LLC Nuget Server

      dotnet nuget push XS.Lib.Blazor.UIComponents.0.0.1-rc.1.nupkg --api-key 0074340892234 --source https://nuget.xackleystudio.com/nuget
View a NuGet Package Repo
Delete a NuGet Package from Repo

  • To delete a package from a remote package repo

    It may take a few minutes for a package to be deleted due to caching.

    • MyGet

      dotnet nuget delete XS.Lib.Blazor.UIComponents 0.0.1 --api-key 1cf63307-027a-4f3a-962e-30ab3ca8a29e --source https://www.myget.org/F/xs/api/v2/package

4. References

4.1. CSS Reference Material

4.1.1. CSS Functions

  • A Guide to CSS Functions.

4.1.2. Additional CSS

4.1.3. SCSS

  • A getting started Guide.

  • More guidance from the official Sass site.

4.2. Bootstrap

4.2.1. Bootstrap Themes can be found here

  • The following sites can be used for inspiration when creating custom themes:

  • Boot Swatch

  • ThemeStr

4.2.2. Bootstrap Theme editors

4.2.3. Favicon Generator

  • While there are no favicons in this UI Library, they can be generated for the Blazor project that consumes this library.

  • Go to Favicon IO Generator.

5. To Do

5.1. Graphs

  • Research using Conic Gradients for Doughnut Charts.

  • Understand the JavaScript.

  • Wrap the JavaScript as a Blazor component.