Skip to content

Commit c6edcd2

Browse files
CopilotjfversluisCopilotkartheekp-ms
authored
Add comprehensive README to Microsoft.Maui.Controls NuGet package (dotnet#32835)
* Initial plan * Add comprehensive README for Microsoft.Maui.Controls NuGet package Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com> * Update src/Controls/src/NuGet/README.md * Change title to use product name .NET MAUI instead of .NET MAUI Controls Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com> * Address PR feedback: Update Background property, add XAML enhancements, update Discord/social links Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com> * Update src/Controls/src/NuGet/README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update src/Controls/src/NuGet/README.md Co-authored-by: Kartheek Penagamuri <kapenaga@microsoft.com> * Add Mac Catalyst run command and replace code examples with doc links Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com> * Add code snippets alongside doc links and remove ListView reference Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com> * Remove build status badge from README Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com> * Update src/Controls/src/NuGet/README.md --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com> Co-authored-by: Gerald Versluis <gerald.versluis@microsoft.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Kartheek Penagamuri <kapenaga@microsoft.com>
1 parent a7ecebe commit c6edcd2

File tree

2 files changed

+292
-0
lines changed

2 files changed

+292
-0
lines changed

‎src/Controls/src/NuGet/Controls.NuGet.csproj‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020
<IsPackable>true</IsPackable>
2121
<PackageId>Microsoft.Maui.Controls</PackageId>
2222
<Description>.NET Multi-platform App UI (.NET MAUI) is a cross-platform framework for creating native mobile and desktop apps with C# and XAML. Using .NET MAUI, you can develop apps that can run on Android, iOS, macOS, Tizen, and Windows from a single shared codebase.</Description>
23+
<PackageReadmeFile>README.md</PackageReadmeFile>
2324
</PropertyGroup>
2425

2526
<ItemGroup>
@@ -29,6 +30,10 @@
2930
<ProjectReference Include="..\..\..\SingleProject\Resizetizer\src\Resizetizer.csproj" />
3031
</ItemGroup>
3132

33+
<ItemGroup>
34+
<None Include="README.md" Pack="true" PackagePath="\" />
35+
</ItemGroup>
36+
3237
<Import Project="$(MauiSrcDirectory)Workload\Shared\LibraryPacks.targets" />
3338

3439
</Project>

‎src/Controls/src/NuGet/README.md‎

Lines changed: 287 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,287 @@
1+
# .NET Multi-platform App UI (.NET MAUI)
2+
3+
![NuGet](https://img.shields.io/nuget/v/Microsoft.Maui.Controls?style=flat-square&label=NuGet)
4+
![License](https://img.shields.io/github/license/dotnet/maui?style=flat-square&label=License)
5+
6+
[.NET Multi-platform App UI (.NET MAUI)](https://dotnet.microsoft.com/apps/maui) is a cross-platform framework for creating native mobile and desktop apps with C# and XAML. Using .NET MAUI, you can develop apps that run on Android, iOS, iPadOS, macOS, and Windows from a single shared codebase.
7+
8+
## ✨ What is .NET MAUI?
9+
10+
The **Microsoft.Maui.Controls** package provides the UI controls and XAML infrastructure for building beautiful, native cross-platform applications. It includes:
11+
12+
- **40+ UI controls** - Buttons, labels, entries, pickers, lists, grids, and more
13+
- **XAML support** - Design your UI with declarative markup
14+
- **Layout system** - Flexible layouts including Grid, StackLayout, FlexLayout, and AbsoluteLayout
15+
- **Navigation** - Shell navigation, NavigationPage, TabbedPage, FlyoutPage
16+
- **Data binding** - Two-way data binding with MVVM support
17+
- **Styling and theming** - Application-wide styles, dynamic resources, and light/dark theme support
18+
- **Platform integration** - Access platform-specific features seamlessly
19+
- **Hot Reload** - See UI changes instantly during development
20+
21+
## 🚀 Supported Platforms
22+
23+
.NET MAUI applications run on the following platforms:
24+
25+
| Platform | Minimum Version |
26+
|----------|----------------|
27+
| Android | API 21 (Android 5.0) |
28+
| iOS | iOS 13.0+ |
29+
| iPadOS | iPadOS 13.0+ |
30+
| macOS | macOS 12.0+ (via Mac Catalyst) |
31+
| Windows | Windows 11, Windows 10 (Version 1809+) using Windows UI Library (WinUI) |
32+
33+
## 📦 Getting Started
34+
35+
### Prerequisites
36+
37+
- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) (or .NET 9 for previous versions)
38+
- Platform-specific tools:
39+
- **Android**: Android SDK (installed via Visual Studio or Android Studio)
40+
- **iOS/macOS**: Xcode (Mac required)
41+
- **Windows**: Windows App SDK
42+
43+
### Installation
44+
45+
Install the .NET MAUI workload:
46+
47+
```bash
48+
dotnet workload install maui
49+
```
50+
51+
### Create a New Project
52+
53+
Create a new .NET MAUI app using the CLI:
54+
55+
```bash
56+
dotnet new maui -n MyMauiApp
57+
cd MyMauiApp
58+
```
59+
60+
Or create with sample content including Community Toolkit and Syncfusion Toolkit:
61+
62+
```bash
63+
dotnet new maui -n MyMauiApp -sc
64+
```
65+
66+
### Run Your App
67+
68+
Run on Android:
69+
```bash
70+
dotnet build -t:Run -f net10.0-android
71+
```
72+
73+
Run on iOS (Mac only):
74+
```bash
75+
dotnet build -t:Run -f net10.0-ios
76+
```
77+
78+
Run on Mac Catalyst (Mac only):
79+
```bash
80+
dotnet build -t:Run -f net10.0-maccatalyst
81+
```
82+
83+
Run on Windows:
84+
```bash
85+
dotnet build -t:Run -f net10.0-windows10.0.19041.0
86+
```
87+
88+
## 💡 Quick Start Example
89+
90+
Here's a simple .NET MAUI page to get you started:
91+
92+
```xml
93+
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
94+
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml">
95+
<VerticalStackLayout Padding="30" Spacing="25">
96+
<Label Text="Hello, .NET MAUI!"
97+
FontSize="32"
98+
HorizontalOptions="Center" />
99+
<Button Text="Click Me"
100+
Clicked="OnButtonClicked" />
101+
<Label x:Name="CounterLabel"
102+
Text="Button not clicked yet"
103+
HorizontalOptions="Center" />
104+
</VerticalStackLayout>
105+
</ContentPage>
106+
```
107+
108+
**Learn more:**
109+
- [Build your first app](https://learn.microsoft.com/dotnet/maui/get-started/first-app) - Complete tutorial with UI examples
110+
- [XAML basics](https://learn.microsoft.com/dotnet/maui/xaml/fundamentals/get-started) - Learn XAML fundamentals
111+
- [Create a multi-page app](https://learn.microsoft.com/dotnet/maui/tutorials/notes-app/) - Build a note-taking app
112+
113+
## 🎯 Key Features
114+
115+
### MVVM and Data Binding
116+
117+
.NET MAUI fully supports the Model-View-ViewModel (MVVM) pattern with powerful data binding:
118+
119+
```xml
120+
<Label Text="{Binding UserName}" />
121+
<Entry Text="{Binding Email, Mode=TwoWay}" />
122+
```
123+
124+
**Learn more:**
125+
- [Data binding fundamentals](https://learn.microsoft.com/dotnet/maui/xaml/fundamentals/data-binding-basics) - Complete guide with examples
126+
- [MVVM pattern](https://learn.microsoft.com/dotnet/maui/xaml/fundamentals/mvvm) - Implementing MVVM
127+
- [.NET MAUI Community Toolkit](https://learn.microsoft.com/dotnet/communitytoolkit/maui/) - MVVM helpers
128+
- [MVVM Toolkit](https://learn.microsoft.com/dotnet/communitytoolkit/mvvm/) - Source generators and commands
129+
130+
### XAML Enhancements
131+
132+
.NET MAUI includes powerful XAML features for cleaner, more efficient code:
133+
134+
```xml
135+
<!-- Simplified property syntax -->
136+
<Button Text="Click Me" Clicked="OnClicked" />
137+
138+
<!-- Markup extensions -->
139+
<Label Text="{Binding Title}"
140+
TextColor="{StaticResource PrimaryColor}" />
141+
```
142+
143+
**Learn more:**
144+
- [XAML compilation and source generation](https://learn.microsoft.com/dotnet/maui/xaml/xamlc) - Better performance
145+
- [XAML markup extensions](https://learn.microsoft.com/dotnet/maui/xaml/markup-extensions/consume) - Extend capabilities
146+
- [XAML hot reload](https://learn.microsoft.com/dotnet/maui/xaml/hot-reload) - Instant updates during development
147+
148+
### Shell Navigation
149+
150+
Shell provides a structured, performant navigation experience:
151+
152+
```xml
153+
<Shell>
154+
<TabBar>
155+
<ShellContent Title="Home"
156+
Icon="home.png"
157+
ContentTemplate="{DataTemplate local:HomePage}" />
158+
<ShellContent Title="Settings"
159+
Icon="settings.png"
160+
ContentTemplate="{DataTemplate local:SettingsPage}" />
161+
</TabBar>
162+
</Shell>
163+
```
164+
165+
**Learn more:**
166+
- [Shell overview](https://learn.microsoft.com/dotnet/maui/fundamentals/shell/) - Getting started with Shell
167+
- [Shell navigation](https://learn.microsoft.com/dotnet/maui/fundamentals/shell/navigation) - Navigation patterns
168+
- [Shell tabs](https://learn.microsoft.com/dotnet/maui/fundamentals/shell/tabs) - Create tabbed interfaces
169+
170+
### Collections and Lists
171+
172+
Display lists and collections with CollectionView:
173+
174+
```xml
175+
<CollectionView ItemsSource="{Binding Items}">
176+
<CollectionView.ItemTemplate>
177+
<DataTemplate>
178+
<Grid Padding="10">
179+
<Label Text="{Binding Name}"
180+
FontSize="18" />
181+
</Grid>
182+
</DataTemplate>
183+
</CollectionView.ItemTemplate>
184+
</CollectionView>
185+
```
186+
187+
**Learn more:**
188+
- [CollectionView](https://learn.microsoft.com/dotnet/maui/user-interface/controls/collectionview/) - High-performance lists
189+
- [CarouselView](https://learn.microsoft.com/dotnet/maui/user-interface/controls/carouselview/) - Scrollable carousel
190+
191+
### Responsive Layouts
192+
193+
Build adaptive UIs that work across different screen sizes:
194+
195+
```xml
196+
<Grid RowDefinitions="Auto,*"
197+
ColumnDefinitions="*,*">
198+
<Label Grid.ColumnSpan="2"
199+
Text="Header" />
200+
<BoxView Grid.Row="1"
201+
Grid.Column="0"
202+
Color="Blue" />
203+
<BoxView Grid.Row="1"
204+
Grid.Column="1"
205+
Color="Green" />
206+
</Grid>
207+
```
208+
209+
**Learn more:**
210+
- [Layouts](https://learn.microsoft.com/dotnet/maui/user-interface/layouts/) - Overview of all layout types
211+
- [Grid layout](https://learn.microsoft.com/dotnet/maui/user-interface/layouts/grid) - Flexible grid system
212+
- [FlexLayout](https://learn.microsoft.com/dotnet/maui/user-interface/layouts/flexlayout) - CSS flexbox-style layout
213+
- [Adaptive layouts](https://learn.microsoft.com/dotnet/maui/user-interface/layouts/choose-layout) - Multi-screen design
214+
215+
## 📚 Documentation and Resources
216+
217+
### Official Documentation
218+
- [.NET MAUI Documentation](https://learn.microsoft.com/dotnet/maui/) - Complete guide to building apps
219+
- [API Reference](https://learn.microsoft.com/dotnet/api/?view=net-maui-10.0) - Detailed API documentation
220+
- [Controls Documentation](https://learn.microsoft.com/dotnet/maui/user-interface/controls/) - All available controls
221+
- [What's New in .NET 10](https://learn.microsoft.com/dotnet/maui/whats-new/dotnet-10) - Latest features and improvements
222+
223+
### Learning Resources
224+
- [.NET MAUI Samples](https://github.com/dotnet/maui-samples) - Official sample applications
225+
- [.NET MAUI Workshop](https://github.com/dotnet-presentations/dotnet-maui-workshop) - Hands-on learning workshop
226+
- [Microsoft Learn](https://learn.microsoft.com/training/paths/build-apps-with-dotnet-maui/) - Free training modules
227+
- [.NET MAUI Blog](https://devblogs.microsoft.com/dotnet/category/net-maui/) - Latest news and updates
228+
229+
### Community Resources
230+
- [.NET MAUI Community Toolkit](https://learn.microsoft.com/dotnet/communitytoolkit/maui/) - Additional controls, behaviors, and converters
231+
- [Awesome .NET MAUI](https://github.com/jsuarezruiz/awesome-dotnet-maui) - Curated list of resources
232+
- [Stack Overflow](https://stackoverflow.com/questions/tagged/.net-maui) - Community Q&A
233+
234+
## 💬 Feedback and Support
235+
236+
We welcome your feedback and contributions!
237+
238+
### Getting Help
239+
- **Documentation**: Check the [official documentation](https://learn.microsoft.com/dotnet/maui/)
240+
- **Q&A**: Ask questions on [Stack Overflow](https://stackoverflow.com/questions/tagged/.net-maui) with the `.net-maui` tag
241+
- **Discussions**: Join [GitHub Discussions](https://github.com/dotnet/maui/discussions) for community conversations
242+
243+
### Reporting Issues
244+
- **Bug Reports**: File bugs at [GitHub Issues](https://github.com/dotnet/maui/issues)
245+
- **Feature Requests**: Suggest new features in [GitHub Issues](https://github.com/dotnet/maui/issues)
246+
- **Security Issues**: Report security vulnerabilities via [Microsoft Security Response Center](https://msrc.microsoft.com/)
247+
248+
### Community
249+
- **Discord**: Join the [.NET Discord server](https://aka.ms/dotnet-discord) or the [MAUIverse Discord](https://mauiverse.net/discord) (community-driven, not Microsoft official)
250+
- **X (formerly Twitter)**: Follow [@dotnet](https://twitter.com/dotnet)
251+
- **YouTube**: Watch tutorials on [.NET YouTube channel](https://www.youtube.com/dotnet)
252+
253+
## 🤝 Contributing
254+
255+
We encourage contributions from the community! .NET MAUI is an open-source project.
256+
257+
- **Contributing Guide**: Read our [Contributing Guidelines](https://github.com/dotnet/maui/blob/main/.github/CONTRIBUTING.md)
258+
- **Development Guide**: See the [Development Guide](https://github.com/dotnet/maui/blob/main/.github/DEVELOPMENT.md) for building locally
259+
- **Code of Conduct**: Review our [Code of Conduct](https://github.com/dotnet/maui/blob/main/.github/CODE_OF_CONDUCT.md)
260+
- **Good First Issues**: Find [good first issues](https://github.com/dotnet/maui/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) to start contributing
261+
262+
## 🔧 Related Packages
263+
264+
.NET MAUI consists of several packages that work together:
265+
266+
| Package | Description |
267+
|---------|-------------|
268+
| [Microsoft.Maui.Controls](https://www.nuget.org/packages/Microsoft.Maui.Controls) | Core UI controls and XAML (this package) |
269+
| [Microsoft.Maui.Core](https://www.nuget.org/packages/Microsoft.Maui.Core) | Platform abstractions and handlers |
270+
| [Microsoft.Maui.Essentials](https://www.nuget.org/packages/Microsoft.Maui.Essentials) | Cross-platform APIs (merged into Core) |
271+
| [Microsoft.Maui.Graphics](https://www.nuget.org/packages/Microsoft.Maui.Graphics) | Cross-platform graphics library |
272+
| [CommunityToolkit.Maui](https://www.nuget.org/packages/CommunityToolkit.Maui) | Community-built controls and helpers |
273+
274+
## 📄 License
275+
276+
.NET MAUI is licensed under the [MIT License](https://github.com/dotnet/maui/blob/main/LICENSE.TXT).
277+
278+
## 🎉 Acknowledgements
279+
280+
.NET MAUI is the evolution of Xamarin.Forms, building on years of mobile and cross-platform development experience. We thank the community for their continued support and contributions.
281+
282+
---
283+
284+
**[Get Started with .NET MAUI](https://dotnet.microsoft.com/apps/maui)** |
285+
**[Documentation](https://learn.microsoft.com/dotnet/maui/)** |
286+
**[Samples](https://github.com/dotnet/maui-samples)** |
287+
**[GitHub](https://github.com/dotnet/maui)**

0 commit comments

Comments
 (0)