### Quick Start Example
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/examples/Demo/Shared/wwwroot/docs/CodeSetup.md
A minimal example demonstrating the usage of FluentCard, H2, and FluentButton components.
```xml
Hello World!
Click Me
```
--------------------------------
### Using Helper Methods for Test Setup
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/docs/unit-tests.md
Prefer helper methods for setting up common objects or states instead of constructors or setup attributes. This keeps test setup code visible and avoids shared state issues between tests.
```csharp
// Bad
// public StringCalculatorTests()
// {
// stringCalculator = new StringCalculator();
// }
[Fact]
public void Add_TwoNumbers_ReturnsSumOfNumbers()
{
var stringCalculator = CreateDefaultStringCalculator();
var actual = stringCalculator.Add("0,1");
Assert.Equal(1, actual);
}
private StringCalculator CreateDefaultStringCalculator()
{
return new StringCalculator();
}
```
--------------------------------
### Install NVM and Latest NPM
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/src/Assets/Generator/ReadMe.md
If npm commands fail, install Node Version Manager (NVM) and then install the latest LTS version of Node.js and npm.
```cmd
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
```
```cmd
nvm install --lts
```
--------------------------------
### Install DataGrid OData Adapter Package
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/src/Extensions/DataGrid.ODataAdapter/README.md
Install the necessary NuGet package to enable the OData adapter for FluentDataGrid.
```bash
dotnet add package Microsoft.FluentUI.AspNetCore.Components.DataGrid.ODataAdapter
```
--------------------------------
### Install EF Core DataGrid Adapter Package
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/src/Extensions/DataGrid.EntityFrameworkAdapter/README.md
Install the necessary NuGet package for the EF Core adapter using the .NET CLI.
```bash
dotnet add package Microsoft.FluentUI.AspNetCore.Components.DataGrid.EntityFrameworkAdapter
```
--------------------------------
### Build the Project
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/docs/contributing.md
Build the fluentui-blazor project from the cloned repository directory. This command requires .NET to be installed.
```bash
dotnet build
```
--------------------------------
### Install Fluent UI Blazor Templates
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/examples/Demo/Shared/wwwroot/docs/Templates.md
Run this command to install the Fluent UI Blazor template package. This enables the creation of new projects with Fluent UI components pre-configured.
```cshtml
dotnet new install Microsoft.FluentUI.AspNetCore.Templates
```
--------------------------------
### Install Ubuntu WSL2
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/src/Assets/Generator/ReadMe.md
Recommended for Windows users to set up a Linux environment for icon generation. This command installs Ubuntu 22.04.
```cmd
wsl --install -d Ubuntu-22.04
```
--------------------------------
### Install Coverlet and ReportGenerator Tools
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/docs/unit-tests.md
Install the Coverlet console tool and the ReportGenerator global tool using the .NET CLI. These are required for generating code coverage reports locally.
```bash
dotnet tool install --global coverlet.console --version 3.2.0
dotnet tool install --global dotnet-reportgenerator-globaltool --version 5.1.20
```
```bash
dotnet tool list --global
```
--------------------------------
### Install Dependencies in SVG Icons Package
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/src/Assets/Generator/ReadMe.md
Navigate to the /packages/svg-icons directory and install development dependencies using npm. This may need to be repeated in the root folder.
```cmd
npm install --only=dev
```
--------------------------------
### Clone Fluent UI Blazor Repository
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/docs/contributing.md
Use this command to clone the repository using HTTPS. Ensure Git is installed.
```shell
git clone https://github.com/microsoft/fluentui-blazor.git
```
--------------------------------
### Create New Fluent UI Blazor Project
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/examples/Demo/Shared/wwwroot/docs/CodeSetup.md
After installing the templates, use this command to create a new Blazor project with Fluent UI pre-configured. Replace 'MyApplication' with your desired project name.
```shell
dotnet new fluentblazor --name MyApplication
```
--------------------------------
### Add Fluent UI Icons Nuget Package
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/src/Assets/FluentUI.Icons/README.md
Install the official Nuget package for Fluent UI Icons using the .NET CLI.
```shell
dotnet add package Microsoft.FluentUI.AspNetCore.Components.Icons
```
--------------------------------
### Install Fluent UI Emoji Package
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/src/Assets/FluentUI.Emojis/README.md
Install the official NuGet package for Fluent UI Emojis into your Blazor project.
```shell
dotnet add package Microsoft.FluentUI.AspNetCore.Components.Emoji
```
--------------------------------
### Add Fluent UI Blazor NuGet Package
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/examples/Demo/Shared/wwwroot/docs/CodeSetup.md
Install the main Fluent UI Blazor component package using the .NET CLI. This command adds the core library to your project.
```shell
dotnet add package Microsoft.FluentUI.AspNetCore.Components
```
--------------------------------
### Verified HTML for Blazor Component Rendering
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/docs/unit-tests.md
An example of a '.verified.html' file used with bUnit's Verify method to compare against a generated '.received.html' file. This helps ensure component rendering consistency.
```html
Button 1Button 2
```
--------------------------------
### Add Optional Fluent UI Blazor Packages
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/examples/Demo/Shared/wwwroot/docs/CodeSetup.md
Install additional packages for Fluent UI Blazor to extend functionality with icons or emoji. These are optional and depend on your project's needs.
```shell
dotnet add package Microsoft.FluentUI.AspNetCore.Components.Icons
```
```shell
dotnet add package Microsoft.FluentUI.AspNetCore.Components.Emoji
```
--------------------------------
### Configure RTL Design Token
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/examples/Demo/Shared/wwwroot/docs/CodeSetup.md
Example of configuring the Direction design token for Right-To-Left languages in a Blazor layout.
```csharp
@* MainRtlLayout.razor *@
@using Microsoft.FluentUI.AspNetCore.Components.DesignTokens
@inject Direction DirectionDesignToken
@inherits LayoutComponentBase
...
@Body
...
@code {
LocalizationDirection Direction { get; set; }
protected override async Task OnAfterRenderAsync(bool f)
{
await base.OnAfterRenderAsync(f);
if(!f)
return;
await DirectionDesignToken.WithDefault("rtl");
Direction = LocalizationDirection.RightToLeft;
StateHasChanged();
}
}
```
--------------------------------
### Add Fluent UI Icons NuGet Package
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/examples/Demo/Shared/wwwroot/docs/ProjectSetup.md
Install the official NuGet package for Fluent UI System Icons to use them in your project. This command adds the package to your project file.
```shell
dotnet add package Microsoft.Fast.Components.FluentUI.Icons
```
--------------------------------
### Add Fluent UI Emojis NuGet Package
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/examples/Demo/Shared/wwwroot/docs/ProjectSetup.md
Install the official NuGet package for Fluent UI Emojis to use them in your project. This command adds the package to your project file.
```shell
dotnet add package Microsoft.Fast.Components.FluentUI.Emojis
```
--------------------------------
### Arrange-Act-Assert Pattern in Unit Tests
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/docs/unit-tests.md
Use the Arrange-Act-Assert pattern to structure your tests. This clearly separates test setup, execution, and verification steps.
```csharp
[Fact]
public void Add_EmptyString_ReturnsZero()
{
// Arrange
var stringCalculator = new StringCalculator();
// Act
var actual = stringCalculator.Add("");
// Assert
Assert.Equal(0, actual);
}
```
--------------------------------
### Access Raw Assets in C#
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/src/Templates/templates/maui-blazor-solution/MauiApp.1/Resources/Raw/AboutAssets.txt
Access deployed raw assets using `FileSystem.OpenAppPackageFileAsync` to get a stream to the file. This is useful for reading configuration files, text files, or other raw data included with your application.
```csharp
async Task LoadMauiAsset()
{
using var stream = await FileSystem.OpenAppPackageFileAsync("AboutAssets.txt");
using var reader = new StreamReader(stream);
var contents = reader.ReadToEnd();
}
```
--------------------------------
### Display Generator Help
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/src/Assets/Generator/ReadMe.md
Run the application with the `--help` parameter to see all available parameters and their descriptions. This is useful for understanding the generator's capabilities and options.
```cmd
> FluentAssetsGenerator.exe --help
FluentAssetsGenerator --folder:
--Assets | -a The root directory containing all SVG icons,
downloaded from https://github.com/microsoft/fluentui-system-icons.
If not specified, the current working directory will be used.
--Library | -l The type of library to generate: icon or emoji.
If not specified, "icon" will be used.
--Namespace | -ns The namespace used for generated classes.
If not specified, "Microsoft.FluentUI.AspNetCore.Components" will be used.
--Names | -n The list of icon names to generate, separated by coma.
Example of icons: accessibility_32_filled,add_circle_20_filled
Example of emojis: accordion_flat,ambulance_high_contrast
By default: all icons
--Sizes | -s The list of icon sizes to generate, separated by coma.
Example: 12,24. By default: all sizes
(Not available for emoji library)
--Target | -t The target directory where C# classes will be created.
If not specified, the current working directory will be used.
--Help | -h Display this documentation.
```
--------------------------------
### Configure launchSettings.json for Icon Generation
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/src/Assets/Generator/ReadMe.md
Alternatively, configure the command-line arguments within the Properties/launchSettings.json file to run the FluentAssetsGenerator for icons.
```json
{
"profiles": {
"Microsoft.FluentUI.AspNetCore.Components.AssetsGenerator": {
"commandName": "Project",
"commandLineArgs": "--Assets=C:/Temp/Icons --Target=./Samples --Library=Icon"
}
}
}
```
--------------------------------
### Configure launchSettings.json for Emoji Generation
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/src/Assets/Generator/ReadMe.md
Configure the command-line arguments within the Properties/launchSettings.json file to run the FluentAssetsGenerator for emojis.
```json
{
"profiles": {
"Microsoft.FLuentUI.AspNetCore.Components.AssetsGenerator": {
"commandName": "Project",
"commandLineArgs": "--Assets=C:/Temp/Icons --Target=./Samples --Library=Emoji"
}
}
}
```
--------------------------------
### Clean and Build for Blazor
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/src/Assets/Generator/ReadMe.md
Run the clean command to remove previous work, followed by the build command specifically for Blazor projects.
```cmd
npm run clean
npm run buildforblazor
```
--------------------------------
### Update FluentDataGrid Align Enumeration
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/examples/Demo/Shared/wwwroot/docs/UpgradeGuide.md
The `Align` enumeration values have changed from `Left` and `Right` to `Start` and `End` for better consistency, especially in RTL applications.
```razor
...
```
--------------------------------
### Include Raw Assets in .csproj
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/src/Templates/templates/maui-blazor-solution/MauiApp.1/Resources/Raw/AboutAssets.txt
Use the `MauiAsset` build action to include raw assets from the Resources\Raw directory and its subdirectories. The `LogicalName` preserves the original directory structure and filename.
```xml
```
--------------------------------
### Remove .csproj Configuration for Icons and Emoji
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/examples/Demo/Shared/wwwroot/docs/UpgradeGuide.md
Remove the entire PropertyGroup related to FluentIcon and FluentEmoji assets from your .csproj file. Refer to the Project Setup documentation for version 3.
```xml
true10,12,16,20,24,28,32,48Filled,RegulartrueActivities,Animals_Nature,Flags,Food_Drink,Objects,People_Body,Smileys_Emotion,Symbols,Travel_PlacesColor,Flat,HighContrast
```
--------------------------------
### Configure Fluent UI Components in Program.cs
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/examples/Demo/Shared/wwwroot/docs/WhatsNew-Archive.md
Add these two lines to your Program.cs file to configure Fluent UI components. This enables the system to check for available icons and emojis.
```csharp
LibraryConfiguration config = new(ConfigurationGenerator.GetIconConfiguration(), ConfigurationGenerator.GetEmojiConfiguration());
builder.Services.AddFluentUIComponents(config);
```
--------------------------------
### Update _Imports.razor for Icons and Emoji Packages
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/examples/Demo/Shared/wwwroot/docs/WhatsNew-Before412.md
Add these @using statements to your _Imports.razor file to correctly reference the Icons and Emoji packages starting from v4.11.0. The Emoji statement is conditional.
```razor
@using Icons = Microsoft.FluentUI.AspNetCore.Components.Icons;
@* add line below only if you are using the Emoji package *@
@using Emoji = Microsoft.FluentUI.AspNetCore.Components.Emoji
```
--------------------------------
### Copy Generated Icons using rsync
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/src/Assets/Generator/ReadMe.md
Navigate to the generated icons folder and use rsync to copy new or updated files to a local fluentui-blazor clone. Adjust the WSL2 path as needed.
```cmd
rsync -r -v . /mnt/c/Temp/Icons
```
--------------------------------
### Run FluentAssetsGenerator for Icons (CLI)
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/src/Assets/Generator/ReadMe.md
Execute the FluentAssetsGenerator application from the command line, specifying the path to the SVG assets, the target output directory, and the library type as 'Icon'.
```cmd
FluentAssetsGenerator.exe --Assets=C:\Temp\Icons --Target=./Samples --Library=Icon
```
--------------------------------
### Set Button Background Color with CSS
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/tests/Core/Button/FluentButtonTests.FluentButton_BackgroundColor.verified.razor.html
Use CSS to define the background color and gradient for a button's control part. This example also shows how to apply hover effects.
```css
#MyButton::part(control) { background: padding-box linear-gradient(#ff0000, #ff0000), border-box #ff0000; }
#MyButton::part(control):hover { opacity: 0.8; }
```
--------------------------------
### Create Fluent Blazor Web App
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/examples/Demo/Shared/wwwroot/docs/Templates.md
Use this command to create a new Fluent Blazor Web App project. Replace '{your project name}' with your desired project directory name.
```cshtml
dotnet new fluentblazor -o {your project name}
```
--------------------------------
### Register Fluent UI Services
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/examples/Demo/Shared/wwwroot/docs/CodeSetup.md
Add this line to your Program.cs to register the necessary Fluent UI components services.
```csharp
builder.Services.AddFluentUIComponents();
```
--------------------------------
### Clone FluentUI System Icons Repository
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/src/Assets/Generator/ReadMe.md
Clone the official FluentUI system icons repository to your Linux environment. No fork is needed as changes are integrated directly.
```cmd
git clone https://github.com/microsoft/fluentui-system-icons.git
```
--------------------------------
### Run FluentAssetsGenerator for Emojis (CLI)
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/src/Assets/Generator/ReadMe.md
Execute the FluentAssetsGenerator application from the command line, specifying the path to the SVG assets, the target output directory, and the library type as 'Emoji'.
```cmd
FluentAssetsGenerator.exe --Assets=C:\Temp\Emojis --Target=./Samples --Library=Emoji
```
--------------------------------
### Clone Fluent UI Blazor Repository via SSH
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/docs/contributing.md
Use this command to clone the repository using SSH. Ensure SSH keys are configured.
```shell
git clone git@github.com:microsoft/fluentui-blazor.git
```
--------------------------------
### Create Fluent Blazor WebAssembly Standalone App
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/examples/Demo/Shared/wwwroot/docs/Templates.md
Use this command to create a new Fluent Blazor WebAssembly Standalone App project. Replace '{your project name}' with your desired project directory name.
```cshtml
dotnet new fluentblazorwasm -o {your project name}
```
--------------------------------
### Include Reboot CSS
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/README.md
Add this link to the head section of your main layout file (e.g., App.razor, index.html, _Layout.cshtml) to apply the Reboot baseline styles. Remove the leading '/' if your site is hosted in a different base path.
```html
```
--------------------------------
### Update Program.cs for Fluent UI Components
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/examples/Demo/Shared/wwwroot/docs/UpgradeGuide.md
Modify the AddFluentUIComponents call in Program.cs. Remove options.IconConfiguration and options.EmojiConfiguration. Set options.HostingModel to a value from the BlazorHostingModel enumeration that matches your project type.
```csharp
builder.Services.AddFluentUIComponents(options =>
{
options.HostingModel = {see remark below};
});
```
--------------------------------
### Register Fluent UI Services
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/README.md
Add this line to your Program.cs to register the necessary Fluent UI Blazor services. For Blazor Server, ensure a default HttpClient is registered first.
```csharp
builder.Services.AddFluentUIComponents();
```
```csharp
builder.Services.AddHttpClient();
```
--------------------------------
### Configure Icon and Emoji Asset Publishing in .csproj
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/examples/Demo/Shared/wwwroot/docs/WhatsNew-Archive.md
Use this PropertyGroup in your .csproj file to control the publishing of Fluent UI icon and emoji assets. Set 'PublishFluentIconAssets' and 'PublishFluentEmojiAssets' to 'true' to enable publishing. You can further refine which assets are published by specifying sizes, variants, groups, and styles.
```xml
true10,12,16,20,24,28,32,48Filled,RegulartrueActivities,Animals_Nature,Flags,Food_Drink,Objects,People_Body,Smileys_Emotion,Symbols,Travel_PlacesColor,Flat,HighContrast
```
--------------------------------
### Include Fluent UI Reboot Stylesheet
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/examples/Demo/Shared/wwwroot/docs/CodeSetup.md
Add this line to the `` section of your `App.razor`, `index.html`, or `_Layout.cshtml` file to include the Fluent UI Reboot stylesheet. This provides a consistent baseline for styling.
```html
```
--------------------------------
### Add Reboot CSS for IIS (.NET 9)
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/examples/Demo/Shared/wwwroot/docs/CodeSetup.md
Include this link in your App.razor, index.html, or _Layout.cshtml for .NET 9 when hosting on IIS with a different base path.
```razor
```
--------------------------------
### Run Unit Tests with Code Coverage
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/docs/unit-tests.md
Execute unit tests and collect code coverage data using the 'dotnet test' command with specific properties. This command generates a 'coverage.cobertura.xml' file in each unit test project folder.
```bash
dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=cobertura
```
--------------------------------
### WebView Workaround for Script Loading
Source: https://github.com/microsoft/fluentui-blazor/blob/dev/examples/Demo/Shared/wwwroot/docs/CodeSetup.md
Use this workaround in WebView environments to ensure web-components scripts are loaded correctly. Include the initializersLoader script before blazor.webview.js.
```html
```