Skip to content

Commit 5e14e82

Browse files
adegeoIEvangelist
andauthored
Update Framework Databinding How-To (#1868)
* Add data object to .NET WPF data binding article * Rewrite Framework databinding how-to * Fix linter settings * Adjust intro and fix linter err * Disable number linter for now * Add VB * Update some wording * Call out .net framework in article * Add .NET version * Forgot to add new article lolz * Fix links * Update dotnet-desktop-guide/net/wpf/data/how-to-create-a-simple-binding.md Co-authored-by: David Pine <[email protected]> * Update dotnet-desktop-guide/net/wpf/data/how-to-create-a-simple-binding.md Co-authored-by: David Pine <[email protected]> * Add changes from other file --------- Co-authored-by: David Pine <[email protected]>
1 parent 8019513 commit 5e14e82

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

48 files changed

+1359
-20
lines changed

.markdownlint-cli2.jsonc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414
"MD026": false,
1515
// Cannot be enabled due to sequential Note blocks
1616
"MD028": false,
17+
"MD030": false,
1718
"MD033": {
1819
"allowed_elements": [
1920
"a",
Lines changed: 73 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,83 @@
11
---
2-
title: "How to: Create a Simple Binding"
3-
description: Create a simple binding for your applications through this how-to example in Windows Presentation Foundation (WPF).
4-
ms.date: "03/30/2017"
2+
title: "How to create a data binding"
3+
description: Create a simple binding for your applications through this how-to example in Windows Presentation Foundation (WPF) and .NET Framework.
4+
ms.date: 07/24/2024
5+
dev_langs:
6+
- "csharp"
7+
- "vb"
58
helpviewer_keywords:
69
- "simple binding [WPF], creating"
710
- "data binding [WPF], creating simple bindings"
811
- "binding data [WPF], creating"
912
ms.assetid: 69b80f72-6259-44cb-8294-5bdcebca1e08
13+
#customer intent: As a devleoper, I want to create a binding so that I can present information in a UI
1014
---
11-
# How to: Create a Simple Binding
12-
13-
This example shows you how to create a simple <xref:System.Windows.Data.Binding>.
14-
15-
## Example
16-
17-
In this example, you have a `Person` object with a string property named `PersonName`. The `Person` object is defined in the namespace called `SDKSample`.
18-
19-
The highlighted line that contains the `<src>` element in the following example instantiates the `Person` object with a `PersonName` property value of `Joe`. This is done in the `Resources` section and assigned an `x:Key`.
20-
21-
[!code-xaml[SimpleBinding](~/samples/snippets/csharp/VS_Snippets_Wpf/SimpleBinding/CSharp/Page1.xaml?highlight=9,37)]
22-
23-
The highlighted line that contains the `<TextBlock>` element then binds the <xref:System.Windows.Controls.TextBlock> control to the `PersonName` property. As a result, the <xref:System.Windows.Controls.TextBlock> appears with the value "Joe".
24-
25-
## See also
15+
16+
# How to create a data binding
17+
18+
This article describes how to create a binding XAML. The example uses a data object that represents an employee at a company. This data object is bound to a XAML window that uses `TextBlock` controls to list the employee's details. You'll create a UI that looks like the following image:
19+
20+
:::image type="content" source="media/how-to-create-a-simple-binding/preview.png" alt-text="A WPF window that shows details about an employee, such as their first name, last name, title, hire date, and salary.":::
21+
22+
To learn more about data binding, see [Data binding overview in WPF](data-binding-overview.md).
23+
24+
## Create a data object
25+
26+
In this example, an employee is used as the data object that the UI is bound to.
27+
28+
1. Add a new class to your project and name it `Employee`.
29+
1. Replace the code with the following snippet:
30+
31+
:::code language="csharp" source="./snippets/how-to-create-a-simple-binding/csharp/Employee.cs":::
32+
:::code language="vb" source="./snippets/how-to-create-a-simple-binding/vb/Employee.vb":::
33+
34+
The employee data object is a simple class that describes an employee:
35+
36+
- The first and last name of the employee.
37+
- The date the employee was hired.
38+
- The employee's company title.
39+
- How much income the employee earns.
40+
41+
## Bind to a data object
42+
43+
The following XAML demonstrates using the `Employee` class as a data object. The root element's `DataContext` property is bound to a static resource declared in the XAML. The individual controls are bound to the properties of the `Employee`.
44+
45+
1. Add a new **Window** to the project and name it `EmployeeView`
46+
1. Replace the XAML with the following snippet:
47+
48+
> [!IMPORTANT]
49+
> The following snippet is taken from a C# project. If you're using Visual Basic, the `x:Class` should be declared without the `ArticleSample` namespace. You can see what the Visual Basic version looks like [here](https://github.com/dotnet/docs-desktop/blob/main/dotnet-desktop-guide/framework/wpf/data/snippets/how-to-create-a-simple-binding/vb/EmployeeView.xaml).
50+
51+
:::code language="xaml" source="./snippets/how-to-create-a-simple-binding/csharp/EmployeeView.xaml" highlight="7-9,33-37,43":::
52+
53+
The namespace of the code won't match your project's namespace, unless you created a project named **ArticleSample**. You can copy and paste the `Window.Resources` and root element (`StackPanel`) into you're **MainWindow** if you created a new project.
54+
55+
To better understand how the previous XAML is using data binding, consider the following points:
56+
57+
- A XAML resource is used to create an instance of the `Employee` class.
58+
59+
Typically the data object is passed to or associated with the Window. This example hardcodes the employee for demonstration purposes.
60+
61+
:::code language="xaml" source="./snippets/how-to-create-a-simple-binding/csharp/EmployeeView.xaml" range="6-10":::
62+
63+
- The root element (`StackPanel`) has its data context set to the hardcoded `Employee` instance.
64+
65+
The child elements inherit their `DataContext` from the parent, unless explicitly set.
66+
67+
:::code language="xaml" source="./snippets/how-to-create-a-simple-binding/csharp/EmployeeView.xaml" range="11":::
68+
69+
- The properties of the `Employee` instance are bound to the `TextBlock` controls.
70+
71+
The `Binding` doesn't specify a `BindingSource`, so the `DataContext` is used as the source.
72+
73+
:::code language="xaml" source="./snippets/how-to-create-a-simple-binding/csharp/EmployeeView.xaml" range="33-37":::
74+
75+
- A `TextBox` control is bound with `TwoWay` mode, allowing the `TextBox` to change the `Employee.Salary` property.
76+
77+
:::code language="xaml" source="./snippets/how-to-create-a-simple-binding/csharp/EmployeeView.xaml" range="43":::
78+
79+
## Related content
2680

2781
- [Data Binding Overview](data-binding-overview.md)
82+
- [How to: Create a Binding in Code](how-to-create-a-binding-in-code.md)
2883
- [How-to Topics](data-binding-how-to-topics.md)
Loading
Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
<Application x:Class="ArticleSample.App"
2+
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
3+
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
4+
xmlns:local="clr-namespace:ArticleSample"
5+
StartupUri="MainWindow.xaml">
6+
<Application.Resources>
7+
8+
</Application.Resources>
9+
</Application>
Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
using System;
2+
using System.Collections.Generic;
3+
using System.Collections.ObjectModel;
4+
using System.Configuration;
5+
using System.Data;
6+
using System.Linq;
7+
using System.Threading.Tasks;
8+
using System.Windows;
9+
10+
namespace ArticleSample
11+
{
12+
/// <summary>
13+
/// Interaction logic for App.xaml
14+
/// </summary>
15+
public partial class App : Application
16+
{
17+
}
18+
}
Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
using System;
2+
using System.ComponentModel;
3+
4+
namespace ArticleSample
5+
{
6+
public class Employee : INotifyPropertyChanged
7+
{
8+
private decimal _salary;
9+
public event PropertyChangedEventHandler PropertyChanged;
10+
11+
public string FirstName { get; set; }
12+
public string LastName { get; set; }
13+
public string Title { get; set; }
14+
public DateTime HireDate { get; set; }
15+
16+
public decimal Salary
17+
{
18+
get => _salary;
19+
set
20+
{
21+
_salary = value;
22+
23+
// Support TwoWay binding
24+
PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(nameof(Salary)));
25+
}
26+
}
27+
}
28+
}
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
<Window x:Class="ArticleSample.EmployeeView"
2+
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
3+
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
4+
xmlns:local="clr-namespace:ArticleSample"
5+
Title="" Height="250" Width="300">
6+
<Window.Resources>
7+
<local:Employee x:Key="EmployeeExample" FirstName="Niki" LastName="Demetriou"
8+
HireDate="2022-02-16" Salary="5012.00"
9+
Title="Content Artist" />
10+
</Window.Resources>
11+
<StackPanel DataContext="{StaticResource EmployeeExample}">
12+
<Label FontSize="32">Employee</Label>
13+
<Border BorderBrush="Gray" BorderThickness="2" />
14+
<Grid Grid.Row="1" Margin="5">
15+
<Grid.RowDefinitions>
16+
<RowDefinition Height="Auto"/>
17+
<RowDefinition Height="Auto"/>
18+
<RowDefinition Height="Auto"/>
19+
<RowDefinition Height="Auto"/>
20+
<RowDefinition Height="Auto"/>
21+
</Grid.RowDefinitions>
22+
<Grid.ColumnDefinitions>
23+
<ColumnDefinition Width="Auto"/>
24+
<ColumnDefinition Width="*"/>
25+
</Grid.ColumnDefinitions>
26+
27+
<TextBlock Text="First Name:" Grid.Row="0" Margin="0,0,10,0" />
28+
<TextBlock Text="Last Name:" Grid.Row="1" />
29+
<TextBlock Text="Title:" Grid.Row="2" />
30+
<TextBlock Text="Hire Date:" Grid.Row="3" />
31+
<TextBlock Text="Salary" Grid.Row="4" />
32+
33+
<TextBlock Text="{Binding FirstName}" Grid.Row="0" Grid.Column="1" />
34+
<TextBlock Text="{Binding LastName}" Grid.Row="1" Grid.Column="1" />
35+
<TextBlock Text="{Binding Title}" Grid.Row="2" Grid.Column="1" />
36+
<TextBlock Text="{Binding HireDate, StringFormat=d}" Grid.Row="3" Grid.Column="1" />
37+
<TextBlock Text="{Binding Salary, StringFormat=C0}" Grid.Row="4" Grid.Column="1" />
38+
</Grid>
39+
<Border BorderBrush="Gray" BorderThickness="2" />
40+
41+
<StackPanel Margin="5,10" Orientation="Horizontal">
42+
<TextBlock Text="Change Salary:" Margin="0,0,10,0" />
43+
<TextBox Text="{Binding Salary, Mode=TwoWay, UpdateSourceTrigger=PropertyChanged, StringFormat=C0}" Width="100" />
44+
</StackPanel>
45+
</StackPanel>
46+
</Window>
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
using System;
2+
using System.Collections.Generic;
3+
using System.Linq;
4+
using System.Text;
5+
using System.Threading.Tasks;
6+
using System.Windows;
7+
using System.Windows.Controls;
8+
using System.Windows.Data;
9+
using System.Windows.Documents;
10+
using System.Windows.Input;
11+
using System.Windows.Media;
12+
using System.Windows.Media.Imaging;
13+
using System.Windows.Shapes;
14+
15+
namespace ArticleSample
16+
{
17+
/// <summary>
18+
/// Interaction logic for EmployeeView.xaml
19+
/// </summary>
20+
public partial class EmployeeView : Window
21+
{
22+
public EmployeeView()
23+
{
24+
InitializeComponent();
25+
}
26+
}
27+
}
Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
<Window x:Class="ArticleSample.MainWindow"
2+
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
3+
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
4+
xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
5+
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
6+
xmlns:local="clr-namespace:ArticleSample"
7+
mc:Ignorable="d"
8+
Title="MainWindow" Height="450" Width="800">
9+
<StackPanel Margin="5">
10+
<Button x:Name="Employee" Content="Employee" Margin="5" Click="Employee_Click" />
11+
</StackPanel>
12+
</Window>
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
using System;
2+
using System.Collections.Generic;
3+
using System.Linq;
4+
using System.Text;
5+
using System.Threading.Tasks;
6+
using System.Windows;
7+
using System.Windows.Controls;
8+
using System.Windows.Data;
9+
using System.Windows.Documents;
10+
using System.Windows.Input;
11+
using System.Windows.Media;
12+
using System.Windows.Media.Imaging;
13+
using System.Windows.Navigation;
14+
using System.Windows.Shapes;
15+
16+
namespace ArticleSample
17+
{
18+
/// <summary>
19+
/// Interaction logic for MainWindow.xaml
20+
/// </summary>
21+
public partial class MainWindow : Window
22+
{
23+
public MainWindow()
24+
{
25+
InitializeComponent();
26+
}
27+
28+
private void Employee_Click(object sender, RoutedEventArgs e)
29+
{
30+
EmployeeView window = new EmployeeView();
31+
window.ShowDialog();
32+
}
33+
}
34+
}
Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
3+
<PropertyGroup>
4+
<OutputType>WinExe</OutputType>
5+
<TargetFramework>netframework4.8.1</TargetFramework>
6+
<UseWpf>true</UseWpf>
7+
<LangVersion>8.0</LangVersion>
8+
<RootNamespace>ArticleSample</RootNamespace>
9+
</PropertyGroup>
10+
11+
</Project>
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
<?xml version="1.0" encoding="utf-8" ?>
2+
<configuration>
3+
<startup>
4+
<supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.8.1" />
5+
</startup>
6+
</configuration>
Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
<Application x:Class="Application"
2+
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
3+
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
4+
xmlns:local="clr-namespace:ArticleSample"
5+
StartupUri="MainWindow.xaml">
6+
<Application.Resources>
7+
8+
</Application.Resources>
9+
</Application>
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Class Application
2+
3+
' Application-level events, such as Startup, Exit, and DispatcherUnhandledException
4+
' can be handled in this file.
5+
6+
End Class

0 commit comments

Comments
 (0)