leandro-sardinha / dotnet-maui-templates

.NET MAUI Project and Item Templates for VS2022 and CLI.

.NET MAUI Project and Item Templates

This repository is to host the .NET MAUI Project Templates, Item Templates and Code Snippets.

Join me on Developer Thoughts, an exclusive blog for .NET MAUI and Blazor, for articles on working with these templates and much more.

We all know that .NET MAUI is an evolution of Xamarin.Forms.

Release Details:

Channel	.NET MAUI Version	IDE Version	Release Date
Stable	.NET 6 SR11 (6.0.553)	VS2022 17.4.x/17.5.x/17.6.x	Tue, Apr 25, 2023
Stable	.NET 7 SR7 (7.0.92)	VS2022 17.4.x/17.5.x/17.6.x	Tue, Jul 11, 2023
Preview	.NET 8 Preview 7 (8.0.0-preview.7.8842) Requires Android SDK Platform 34	VS2022 17.8.0 Preview 1.0	Tue, Aug 8, 2023

Use the below commands to verify the version installed:

dotnet --version

dotnet workload list

And to install a workload, run the following command:

On Windows, this is to be executed on an elevated prompt:

dotnet workload install maui

On macOS:

sudo dotnet workload install maui

On Linux (Only Android workload is supported for now):

sudo dotnet workload install maui-android

Templates have been updated to support .NET 6/7/8 and is available to install from.

Channel	NuGet	VS Marketplace
Stable

For VS2022 users:

To provide an integrated experience, a VS extension has been developed to host these templates.

Extension is made available in the Visual Studio Marketplace and even more easier, can be installed from within Visual Studio itself (Extensions -> Manage Extensions / Alt + X + M).

This has Project Templates for:

• .NET MAUI App - An All-in-One .NET MAUI App Project Template - For more details, check out this article
• .NET MAUI Class Library
• Shared Class Library (Xamarin.Forms and .NET MAUI)

And has Item Templates for:

• Content Page
• Content Page (C#)
• Content Page (Razor)
• Content Page with BlazorWebView
• Content Page with BlazorWebView (C#)
• Content Page with ViewModel
• Content Page (C#) with ViewModel
  • For both the Page with ViewModel templates, ensure only the real page name alone is provided as input like Settings as the Page and ViewModel will be suffixed to it like SettingsPage and SettingsViewModel. And Page will be generated in the Views folder and ViewModel will be generated in the ViewModels folder.
  • The ViewModels are generated with the base class titled BaseViewModel (implementation left to the user).
  • Recommended to add CommunityToolkit.Mvvm, an officially supported NuGet package, to make it easy to work with MVVM design pattern.
  • This MVVM - Made Easy Part 1 and Part 2 articles can help you to get started with this brand-new NuGet package.
• Content View
• Content View (C#)
• Content View (Razor)
• Resource Dictionary
• Resource Dictionary (XAML only)
• Shell Page
• Shell Page (C#)
• Custom View and Handler (Regular)
  • Handler definitions generated in the Platforms folder
• Custom View and Handler (Cond.)
  • Handler definitions generated in the same folder in conditional compilation format
• Custom View and Renderer (Regular)
  • Renderer definitions generated in the Platforms folder
• Custom View and Renderer (Cond.)
  • Renderer definitions generated in the same folder in conditional compilation format
• Comet Page (C#)
• Partial Class (C#)
  • Made available in the section titled Code
     
• For Cond. type template to work properly, ensure Conditional Compilation is enabled (mentioned in detail here)

Now VS2022 extension is loaded with 25+ C# and XAML Code Snippets.

XAML Snippets for new Layouts, Gestures, Color, Style.

C# Snippets for Properties such as Attached, Bindable, ViewModel and Comet (MVU design pattern).

Types such as record and record struct.

Snippets for Method definition, Event Handler definition (async version also).

.NET CLI Template

For making use of these templates cross-platform, have provided it as .NET CLI template package distributed via NuGet.

Install the template package from NuGet with the below command.

dotnet new install VijayAnand.MauiTemplates

If you've already installed this package, then this can be updated to the latest version with the below command.

dotnet new update --check-only

dotnet new update

This comes with with the following templates:

Name	Template Name	Type
All-in-One .NET MAUI App	mauiapp	Project
.NET MAUI Class Library	mauiclasslib	Project
Shared Class Library	sharedclasslib	Project
ContentPage (XAML)	maui-page	Item
ContentPage (C#)	maui-page-cs	Item
ContentPage (Razor)	maui-page-razor	Item
ContentView (XAML)	maui-view	Item
ContentView (C#)	maui-view-cs	Item
ContentView (Razor)	maui-view-razor	Item
ResourceDictionary	maui-resdict	Item
ShellPage (XAML)	maui-shell	Item
ShellPage (C#)	maui-shell-cs	Item
ShellPage (Razor)	maui-shell-razor	Item
ContentPage with ViewModel	maui-mvvm	Item
ContentPage with ViewModel (C#)	maui-mvvm-cs	Item
ContentPage with BlazorWebView (XAML)	maui-bwv	Item
ContentPage with BlazorWebView (C#)	maui-bwv-cs	Item
Partial Class (C#)	class-cs	Item

Parameters:

Starting with v2.0.0 of the template package, to effectively support .NET MAUI on both .NET 6 and .NET 7, CLI project template defines a new parameter named framework:

And from v3.0.0 of the template package, CLI project template framework parameter adds .NET 8 as another option.

And from v4.0.0 of the template package, CLI project template defines a new parameter named language:

• Language: (Short notation: -lang):

  This can take C# / F# as its options (with C# being the default value, if not specified).

  Examples:

  dotnet new mauiapp -lang F#

  For creating a .NET MAUI App on .NET 8 Preview

  dotnet new mauiapp -f net8.0 -lang F#

• Framework: (Short notation: -f)

  This can take net6.0 / net7.0 / net8.0 as its options (with net7.0 being the default value, if not specified).

  Examples:

  dotnet new mauiapp -f net6.0

  Below command can be simplified to dotnet new mauiapp as default value of framework parameter is net7.0

  dotnet new mauiapp -f net7.0

  For creating a .NET MAUI App on .NET 8 Preview

  dotnet new mauiapp -f net8.0

In .NET CLI, all of these Item Templates takes two parameters:

• Name: (Short notation: -n)

  The name of the project/page/view to create. For pages/views, don't need to suffix it with .xaml, it will get added.

  If the name parameter is not specified, by default, the .NET CLI template engine will take the current folder name as the filename (current behaviour of the templating engine).

• Namespace: (Short notation: -na)

  The namespace for the generated files.

  While working with .NET 7 SDK or later, the namespace parameter in short notation needs to be passed as -p:na (i.e., it needs to be prefixed with -p:).

• Now with more options while creating the app or class library project, ability to include NuGet packages on the fly for CommunityToolkit.Maui, CommunityToolkit.Maui.Markup, CommunityToolkit.Mvvm or all.

Note: Parameter values are case-insensitive.

Both .NET MAUI App and Class Library templates take the below optional Boolean parameters to include the officially supported CommunityToolkit NuGet packages:

Specifying the parameter name, either in short or full notation, implies that it is defined.

• -it | --include-toolkit - Default is false
• -im | --include-markup - Default is false
• -imt | --include-mvvm-toolkit - Default is false
• -cc | --conditional-compilation - Default is false

Conditional Compilation

And now conditional compilation can be configured so that platform source files can be defined anywhere in the project provided they follow a naming convention as mentioned below. This will allow maintaining related source files in the same place, especially MAUI Handlers.

• *.Standard.cs - Files targeting the BCL
• *.Android.cs - Files specific to Android
• *.iOS.cs - Files shared with both iOS and MacCatalyst
• *.MacCatalyst.cs - Files specific to MacCatalyst
• *.Tizen.cs - Files specific to Tizen
• *.Windows.cs - Files specific to Windows

For existing projects, add the below block of code in the project file (.csproj). This will modify the behavior of build process so due care must be taken if doing so.

<ItemGroup Condition="'$(TargetFramework)' != 'net6.0'">
    <Compile Remove="**\*.Standard.cs" />
    <None Include="**\*.Standard.cs" Exclude="$(DefaultItemExcludes);$(DefaultExcludesInProjectFolder)" />
</ItemGroup>

<ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) != 'ios' AND $([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) != 'maccatalyst'">
    <Compile Remove="**\*.iOS.cs" />
    <None Include="**\*.iOS.cs" Exclude="$(DefaultItemExcludes);$(DefaultExcludesInProjectFolder)" />
    <Compile Remove="**\iOS\**\*.cs" />
    <None Include="**\iOS\**\*.cs" Exclude="$(DefaultItemExcludes);$(DefaultExcludesInProjectFolder)" />
</ItemGroup>

<ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) != 'android'">
    <Compile Remove="**\*.Android.cs" />
    <None Include="**\*.Android.cs" Exclude="$(DefaultItemExcludes);$(DefaultExcludesInProjectFolder)" />
    <Compile Remove="**\Android\**\*.cs" />
    <None Include="**\Android\**\*.cs" Exclude="$(DefaultItemExcludes);$(DefaultExcludesInProjectFolder)" />
</ItemGroup>

<ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) != 'maccatalyst'">
    <Compile Remove="**\*.MacCatalyst.cs" />
    <None Include="**\*.MacCatalyst.cs" Exclude="$(DefaultItemExcludes);$(DefaultExcludesInProjectFolder)" />
    <Compile Remove="**\MacCatalyst\**\*.cs" />
    <None Include="**\MacCatalyst\**\*.cs" Exclude="$(DefaultItemExcludes);$(DefaultExcludesInProjectFolder)" />
</ItemGroup>

<ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) != 'tizen'">
    <Compile Remove="**\*.Tizen.cs" />
    <None Include="**\*.Tizen.cs" Exclude="$(DefaultItemExcludes);$(DefaultExcludesInProjectFolder)" />
    <Compile Remove="**\Tizen\**\*.cs" />
    <None Include="**\Tizen\**\*.cs" Exclude="$(DefaultItemExcludes);$(DefaultExcludesInProjectFolder)" />
</ItemGroup>

<ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) != 'windows'">
    <Compile Remove="**\*.Windows.cs" />
    <None Include="**\*.Windows.cs" Exclude="$(DefaultItemExcludes);$(DefaultExcludesInProjectFolder)" />
    <Compile Remove="**\Windows\**\*.cs" />
    <None Include="**\Windows\**\*.cs" Exclude="$(DefaultItemExcludes);$(DefaultExcludesInProjectFolder)" />
</ItemGroup>

All-in-One .NET MAUI App Project Template:

This takes two additional parameters to define the application design pattern and target platform respectively:

• -dp | --design-pattern

Can take any one of the following values, with default value set to Plain:

Parameter Value	Description
Plain	App configured to work with a single, initial screen.
Hierarchical	App configured to work in a Hierarchical pattern using NavigationPage.
Tab	App configured to work in a Tabbed fashion using TabbedPage.
Shell	App configured to work with Routes using Shell page.
Hybrid	App configured to work in a Hybrid fashion using BlazorWebView.
Markup	App configured to work with C# Markup syntax.
Razor	App configured to work with Razor syntax.
Comet	App configured to work with MVU pattern using Comet.
Reactor	App configured to work with MVU pattern using Reactor.

• -tp | --target-platform

Can take a combination of the following values, with default value set to All:

Parameter Value	Description
All	Targets all possible .NET MAUI supported platforms.
Base	Base framework (.NET 6/7/8) based on the framework opted.
Android	Targets Android platform.
iOS	Targets iOS platform.
macOS	Targets macOS platform via Mac Catalyst.
Windows	Targets Windows platform.
Tizen	Targets Tizen platform.
Mobile	Targets Android and iOS platforms.
Desktop	Targets Windows and macOS platforms.
Apple	Targets iOS and macOS platforms.

Additional parameters supported:

MVVM is a delightful and development-friendly design pattern to work with. To support this, a new parameter has been introduced:

• -mvvm | --use-mvvm - Default is false
• -icb | --include-compiled-bindings - Default is false

Note: Opting for this MVVM option will not have any impact on the App created with Web-based Razor syntax or MVU based Comet/Reactor.

While creating a Blazor Hybrid App, an option to abstract the Razor components as a separate Razor class library.

• -rcl | --razor-class-library - Default is false

The target for the Windows platform can be either Package (MSIX) or Unpackaged. By default, it is set as Package, this can be overridden while creating the project by including the below parameter:

• -wu | --windows-unpackaged - Default is false

While targeting .NET 7 or later, an option to add and configure CommunityToolkit.Maui.MediaElement, Microsoft.Maui.Controls.Foldable, Microsoft.Maui.Controls.Maps, or all NuGet packages.

• -ime | --include-media-element - Default is false
• -if | --include-foldable - Default is false
• -inm | --include-maps - Default is false

Note: If the project target .NET 6, selecting the MediaElement/Foldable/Maps option will NOT have any impact.

Examples (passing one or more values):

dotnet new mauiapp --design-pattern Hybrid --target-platform Mobile

dotnet new mauiapp -dp Shell -tp Android iOS Windows

.NET MAUI Class Library Template:

Similar to All-in-One .NET MAUI App, the Class Library project template also takes target-platform as a parameter that takes a combination from the same set of values (with All being the default value).

• Can be created targeting .NET Razor SDK
  • Parameter name: --use-razor-sdk | -usr
• Can be created targeting .NET MAUI Core
  • Parameter name: --use-maui-core | -umc
• Can be created targeting .NET MAUI Essentials
  • Parameter name: --use-maui-essentials | -ume

Shared Class Library Template:

This takes the below optional Boolean parameters to include the officially supported NuGet packages:

Specifying the parameter name, either in short or full notation, implies that it is defined.

Single parameter to include all the supported NuGet packages:

• -asp | --all-supported-packages - Default is false

Specific to Xamarin.Forms:

• -ife | --include-forms-essentials - Default is false
• -ift | --include-forms-toolkit - Default is false
• -ifm | --include-forms-markup - Default is false

Specific to .NET MAUI:

• -imt | --include-maui-toolkit - Default is false
• -imm | --include-maui-markup - Default is false

Common to both:

• -inmt | --include-mvvm-toolkit - Default is false

For more details: run this command in the terminal (use -h to save some keystrokes):

dotnet new mauiapp --help

dotnet new mauiclasslib --help

dotnet new sharedclasslib --help

Partial Class Item Template:

This item template (short name: class-cs) allows to create a C# class from CLI with support for multiple options.

Parameter Name	Type	Default Value	Remarks
access-modifier	choice	public	Specifies the accessibility of the class type.
base	text	object	Specifies the base type for the class.
abstract	bool	false	Option to create the type as abstract.
partial	bool	true	Option to create the type as partial.
sealed	bool	false	Option to create the type as sealed.
static	bool	false	Option to create the type as static.

Access Modifier parameter (--access-modifier | -am):

Supported values are:

• public (default value, if not provided)
• internal
• protected
• private

Usage:

After installation, use the below command(s) to create new artifacts using the template (both provide the same output):

With parameter names abbreviated:

.NET MAUI App:

dotnet new mauiapp -n MyApp -dp Shell

dotnet new mauiapp -n MyApp -dp Hybrid

dotnet new mauiapp -n MyApp -dp Markup

dotnet new mauiapp -n MyApp -dp Razor

dotnet new mauiapp -n MyApp -dp Comet

dotnet new mauiapp -n MyApp -dp Reactor

Option to use MVVM:

dotnet new mauiapp -n MyApp -mvvm

dotnet new mauiapp -n MyApp -dp Markup -mvvm

Option to use MVVM (Compiled Bindings):

dotnet new mauiapp -n MyApp -mvvm -icb

Option to create Razor class library while creating Blazor Hybrid App:

dotnet new mauiapp -n MyApp -dp Hybrid -rcl

Option to include NuGet packages:

dotnet new mauiapp -n MyApp -dp Shell -it -im -imt -ime -inm -if

Option to configure conditional compilation:

dotnet new mauiapp -n MyApp -dp Shell -cc

.NET MAUI Class Library:

dotnet new mauiclasslib -n MyApp.Core

Option to include NuGet packages:

dotnet new mauiclasslib -n MyApp.Core -it -im -imt

Option to configure conditional compilation:

dotnet new mauiclasslib -n MyApp.Core -cc

Shared Class Library:

dotnet new sharedclasslib -n MyApp.UI

Option to include all supported NuGet packages:

dotnet new sharedclasslib -n MyApp.UI -asp

Pages:

dotnet new maui-page -n HomePage -na MyApp.Views

dotnet new maui-page-cs -n HomePage -na MyApp.Views

dotnet new maui-page-razor -n HomePage

Page with ViewModel:

Don't suffix anything to the name, it'll be included automatically.

dotnet new maui-mvvm -n Login

dotnet new maui-mvvm-cs -n Login

ContentPage with BlazorWebView:

dotnet new maui-bwv -n HomePage -na MyApp.Views

dotnet new maui-bwv-cs -n HomePage -na MyApp.Views

Views:

dotnet new maui-view -n OrderView -na MyApp.Views

dotnet new maui-view-cs -n OrderView -na MyApp.Views

dotnet new maui-view-razor -n OrderView

Shell:

dotnet new maui-shell -n AppShell -na MyApp

dotnet new maui-shell-cs -n AppShell -na MyApp

dotnet new maui-shell-razor -n AppShell

Resource Dictionary:

dotnet new maui-resdict -n LightTheme -na MyApp.Themes

Partial Class:

dotnet new class-cs -n BaseViewModel

dotnet new class-cs -n OrderDataStore -b IDataStore -p false -am internal

With parameter names expanded:

.NET MAUI App:

dotnet new mauiapp --name MyApp --design-pattern Shell

dotnet new mauiapp --name MyApp --design-pattern Hybrid

dotnet new mauiapp --name MyApp --design-pattern Markup

dotnet new mauiapp --name MyApp --design-pattern Razor

dotnet new mauiapp --name MyApp --design-pattern Comet

dotnet new mauiapp --name MyApp --design-pattern Reactor

Option to use MVVM:

dotnet new mauiapp --name MyApp --use-mvvm

dotnet new mauiapp --name MyApp --design-pattern Markup --use-mvvm

Option to use MVVM (Compiled Bindings):

dotnet new mauiapp --name MyApp --use-mvvm --include-compiled-bindings

Option to create Razor class library while creating Blazor Hybrid App:

dotnet new mauiapp --name MyApp --design-pattern Hybrid --razor-class-library

Option to include NuGet packages:

dotnet new mauiapp --name MyApp --design-pattern Shell --include-toolkit --include-markup --include-mvvm-toolkit --include-media-element --include-maps --include-foldable

dotnet new mauiapp -n MyApp --design-pattern Shell --conditional-compilation

.NET MAUI Class Library:

dotnet new mauiclasslib --name MyApp.Core

dotnet new mauiclasslib --name MyApp.Core --include-toolkit --include-markup --include-mvvm-toolkit

dotnet new mauiclasslib --name MyApp.Core --conditional-compilation

Shared Class Library:

dotnet new sharedclasslib --name MyApp.UI

dotnet new sharedclasslib --name MyApp.UI --all-supported-packages

Pages:

dotnet new maui-page --name HomePage --namespace MyApp.Views

dotnet new maui-page-cs --name HomePage --namespace MyApp.Views

dotnet new maui-page-razor --name HomePage

Page with ViewModel:

Don't suffix anything to the name, it'll be included automatically.

dotnet new maui-mvvm --name Login

dotnet new maui-mvvm-cs --name Login

ContentPage with BlazorWebView:

dotnet new maui-bwv --name HomePage --namespace MyApp.Views

dotnet new maui-bwv-cs --name HomePage --namespace MyApp.Views

Views:

dotnet new maui-view --name OrderView --namespace MyApp.Views

dotnet new maui-view-cs --name OrderView --namespace MyApp.Views

dotnet new maui-view-razor --name OrderView

Shell:

dotnet new maui-shell --name AppShell --namespace MyApp

dotnet new maui-shell-cs --name AppShell --namespace MyApp

dotnet new maui-shell-razor --name AppShell

Resource Dictionary:

dotnet new maui-resdict --name LightTheme --namespace MyApp.Themes

Partial Class:

dotnet new class-cs --name BaseViewModel

dotnet new class-cs --name OrderDataStore --base IDataStore --partial false --access-modifier internal