Skip to content

Latest commit

 

History

History
501 lines (286 loc) · 29.9 KB

walkthrough-my-first-wpf-desktop-application.md

File metadata and controls

501 lines (286 loc) · 29.9 KB
Raw
title titleSuffix description ms.date ms.topic dev_langs helpviewer_keywords ms.assetid ms.custom
Create your first WPF app in Visual Studio 2019 - .NET Framework
Develop a Windows Presentation Foundation (WPF) desktop application that includes elements common to most WPF applications.
09/06/2019
tutorial
csharp
vb
getting started [WPF], WPF
WPF [WPF], getting started
b96bed40-8946-4285-8fe4-88045ab854ed
mvc,vs-dotnet

Tutorial: Create your first WPF application in Visual Studio 2019

This article shows you how to develop a Windows Presentation Foundation (WPF) desktop application that includes the elements that are common to most WPF applications: Extensible Application Markup Language (XAML) markup, code-behind, application definitions, controls, layout, data binding, and styles. To develop the application, you'll use Visual Studio.

Important

This article was written for .NET Framework. To get started with .NET 7, see Tutorial: Create a new WPF app (WPF .NET).

In this tutorial, you learn how to:

[!div class="checklist"]

  • Create a WPF project.
  • Use XAML to design the appearance of the application's user interface (UI).
  • Write code to build the application's behavior.
  • Create an application definition to manage the application.
  • Add controls and create the layout to compose the application UI.
  • Create styles for a consistent appearance throughout the application's UI.
  • Bind the UI to data, both to populate the UI from data and to keep the data and UI synchronized.

By the end of the tutorial, you'll have built a standalone Windows application that allows users to view expense reports for selected people. The application is composed of several WPF pages that are hosted in a browser-style window.

Tip

The sample code that is used in this tutorial is available for both Visual Basic and C# at Tutorial WPF App Sample Code.

You can toggle the code language of the sample code between C# and Visual Basic by using the language selector on top of this page.

Prerequisites

Create the application project

The first step is to create the application infrastructure, which includes an application definition, two pages, and an image.

  1. Create a new WPF Application project in Visual Basic or Visual C# named ExpenseIt:

    1. Open Visual Studio and select Create a new project under the Get started menu.

      The Create a new project dialog opens.

    2. In the Language dropdown, select either C# or Visual Basic.

    3. Select the WPF App (.NET Framework) template and then select Next.

      Create a new project dialog

      The Configure your new project dialog opens.

    4. Enter the project name ExpenseIt and then select Create.

      Configure a new project dialog

      Visual Studio creates the project and opens the designer for the default application window named MainWindow.xaml.

  2. Open Application.xaml (Visual Basic) or App.xaml (C#).

    This XAML file defines a WPF application and any application resources. You also use this file to specify the UI, in this case MainWindow.xaml, that automatically shows when the application starts.

    Your XAML should look like the following in Visual Basic:

    [!code-xamlExpenseIt#1_A]

    And like the following in C#:

    [!code-xamlExpenseIt#1]

  3. Open MainWindow.xaml.

    This XAML file is the main window of your application and displays content created in pages. The xref:System.Windows.Window class defines the properties of a window, such as its title, size, or icon, and handles events, such as closing or hiding.

  4. Change the xref:System.Windows.Window element to a xref:System.Windows.Navigation.NavigationWindow, as shown in the following XAML:

    <NavigationWindow x:Class="ExpenseIt.MainWindow"
     xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
     xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
     ...
</NavigationWindow>

    This app navigates to different content depending on the user input. This is why the main xref:System.Windows.Window needs to be changed to a xref:System.Windows.Navigation.NavigationWindow. xref:System.Windows.Navigation.NavigationWindow inherits all the properties of xref:System.Windows.Window. The xref:System.Windows.Navigation.NavigationWindow element in the XAML file creates an instance of the xref:System.Windows.Navigation.NavigationWindow class. For more information, see Navigation overview.

  5. Remove the xref:System.Windows.Controls.Grid elements from between the xref:System.Windows.Navigation.NavigationWindow tags.

  6. Change the following properties in the XAML code for the xref:System.Windows.Navigation.NavigationWindow element:

    • Set the xref:System.Windows.Window.Title%2A property to "ExpenseIt".

    • Set the xref:System.Windows.FrameworkElement.Height%2A property to 350 pixels.

    • Set the xref:System.Windows.FrameworkElement.Width%2A property to 500 pixels.

    Your XAML should look like the following for Visual Basic:

    [!code-xamlExpenseIt#2_A]

    And like the following for C#:

    [!code-xamlExpenseIt#2]

  7. Open MainWindow.xaml.vb or MainWindow.xaml.cs.

    This file is a code-behind file that contains code to handle the events declared in MainWindow.xaml. This file contains a partial class for the window defined in XAML.

  8. If you're using C#, change the MainWindow class to derive from xref:System.Windows.Navigation.NavigationWindow. (In Visual Basic, this happens automatically when you change the window in XAML.) Your C# code should now look like this:

    [!code-csharpExpenseIt#3]

Add files to the application

In this section, you'll add two pages and an image to the application.

  1. Add a new page to the project, and name it ExpenseItHome.xaml:

    1. In Solution Explorer, right-click on the ExpenseIt project node and choose Add > Page.

    2. In the Add New Item dialog, the Page (WPF) template is already selected. Enter the name ExpenseItHome, and then select Add.

    This page is the first page that's displayed when the application is launched. It will show a list of people to select from, to show an expense report for.

  2. Open ExpenseItHome.xaml.

  3. Set the xref:System.Windows.Controls.Page.Title%2A to "ExpenseIt - Home".

  4. Set the DesignHeight to 350 pixels and the DesignWidth to 500 pixels.

    The XAML now appears as follows for Visual Basic:

    [!code-xamlExpenseIt#6_A]

    And like the following for C#:

    [!code-xamlExpenseIt#6]

  5. Open MainWindow.xaml.

  6. Add a xref:System.Windows.Navigation.NavigationWindow.Source%2A property to the xref:System.Windows.Navigation.NavigationWindow element and set it to "ExpenseItHome.xaml".

    This sets ExpenseItHome.xaml to be the first page opened when the application starts.

    Example XAML in Visual Basic:

    [!code-xamlExpenseIt#7_A]

    And in C#:

    [!code-xamlExpenseIt#7]

    [!TIP] You can also set the Source property in the Miscellaneous category of the Properties window.

    Source property in Properties window

  7. Add another new WPF page to the project, and name it ExpenseReportPage.xaml::

    1. In Solution Explorer, right-click on the ExpenseIt project node and choose Add > Page.

    2. In the Add New Item dialog, select the Page (WPF) template. Enter the name ExpenseReportPage, and then select Add.

    This page will show the expense report for the person that is selected on the ExpenseItHome page.

  8. Open ExpenseReportPage.xaml.

  9. Set the xref:System.Windows.Controls.Page.Title%2A to "ExpenseIt - View Expense".

  10. Set the DesignHeight to 350 pixels and the DesignWidth to 500 pixels.

    ExpenseReportPage.xaml now looks like the following in Visual Basic:

    [!code-xamlExpenseIt#4_A]

    And like the following in C#:

    [!code-xamlExpenseIt#4]

  11. Open ExpenseItHome.xaml.vb and ExpenseReportPage.xaml.vb, or ExpenseItHome.xaml.cs and ExpenseReportPage.xaml.cs.

    When you create a new Page file, Visual Studio automatically creates its code-behind file. These code-behind files handle the logic for responding to user input.

    Your code should look like the following for ExpenseItHome:

    [!code-csharpExpenseIt#2_5]

    [!code-vbExpenseIt#2_5]

    And like the following for ExpenseReportPage:

    [!code-csharpExpenseIt#5]

    [!code-vbExpenseIt#5]

  12. Add an image named watermark.png to the project. You can create your own image, copy the file from the sample code, or get it from the microsoft/WPF-Samples GitHub repository.

    1. Right-click on the project node and select Add > Existing Item, or press Shift+Alt+A.

    2. In the Add Existing Item dialog, set the file filter to either All Files or Image Files, browse to the image file you want to use, and then select Add.

    3. Select the image file in Solution Explorer, then in the Properties window, set Build Action to Resource.

Build and run the application

  1. To build and run the application, press F5 or select Start Debugging from the Debug menu.

    The following illustration shows the application with the xref:System.Windows.Navigation.NavigationWindow buttons:

    Application after you build and run it.

  2. Close the application to return to Visual Studio.

Create the layout

Layout provides an ordered way to place UI elements, and also manages the size and position of those elements when a UI is resized. You typically create a layout with one of the following layout controls:

  • xref:System.Windows.Controls.Canvas - Defines an area within which you can explicitly position child elements by using coordinates that are relative to the Canvas area.
  • xref:System.Windows.Controls.DockPanel - Defines an area where you can arrange child elements either horizontally or vertically, relative to each other.
  • xref:System.Windows.Controls.Grid - Defines a flexible grid area that consists of columns and rows.
  • xref:System.Windows.Controls.StackPanel - Arranges child elements into a single line that can be oriented horizontally or vertically.
  • xref:System.Windows.Controls.VirtualizingStackPanel - Arranges and virtualizes content on a single line that is oriented either horizontally or vertically.
  • xref:System.Windows.Controls.WrapPanel - Positions child elements in sequential position from left to right, breaking content to the next line at the edge of the containing box. Subsequent ordering happens sequentially from top to bottom or from right to left, depending on the value of the Orientation property.

Each of these layout controls supports a particular type of layout for its child elements. ExpenseIt pages can be resized, and each page has elements that are arranged horizontally and vertically alongside other elements. In this example, the xref:System.Windows.Controls.Grid is used as layout element for the application.

Tip

For more information about xref:System.Windows.Controls.Panel elements, see Panels overview. For more information about layout, see Layout.

In this section, you create a single-column table with three rows and a 10-pixel margin by adding column and row definitions to the xref:System.Windows.Controls.Grid in ExpenseItHome.xaml.

  1. In ExpenseItHome.xaml, set the xref:System.Windows.FrameworkElement.Margin%2A property on the xref:System.Windows.Controls.Grid element to "10,0,10,10", which corresponds to left, top, right and bottom margins:

    <Grid Margin="10,0,10,10">

    [!TIP] You can also set the Margin values in the Properties window, under the Layout category:

    Margin values in Properties window

  2. Add the following XAML between the xref:System.Windows.Controls.Grid tags to create the row and column definitions:

    [!code-xamlExpenseIt#8]

    The xref:System.Windows.Controls.RowDefinition.Height%2A of two rows is set to xref:System.Windows.GridLength.Auto%2A, which means that the rows are sized based on the content in the rows. The default xref:System.Windows.Controls.RowDefinition.Height%2A is xref:System.Windows.GridUnitType.Star sizing, which means that the row height is a weighted proportion of the available space. For example if two rows each have a xref:System.Windows.Controls.RowDefinition.Height%2A of "*", they each have a height that is half of the available space.

    Your xref:System.Windows.Controls.Grid should now contain the following XAML:

    [!code-xamlExpenseIt#9]

Add controls

In this section, you'll update the home page UI to show a list of people, where you select one person to display their expense report. Controls are UI objects that allow users to interact with your application. For more information, see Controls.

To create this UI, you'll add the following elements to ExpenseItHome.xaml:

  • A xref:System.Windows.Controls.ListBox (for the list of people).
  • A xref:System.Windows.Controls.Label (for the list header).
  • A xref:System.Windows.Controls.Button (to click to view the expense report for the person that is selected in the list).

Each control is placed in a row of the xref:System.Windows.Controls.Grid by setting the xref:System.Windows.Controls.Grid.Row%2A?displayProperty=nameWithType attached property. For more information about attached properties, see Attached Properties Overview.

  1. In ExpenseItHome.xaml, add the following XAML somewhere between the xref:System.Windows.Controls.Grid tags:

    [!code-xamlExpenseIt#10]

    [!TIP] You can also create the controls by dragging them from the Toolbox window onto the design window, and then setting their properties in the Properties window.

  2. Build and run the application.

    The following illustration shows the controls you created:

ExpenseIt sample screenshot displaying a list of names

Add an image and a title

In this section, you'll update the home page UI with an image and a page title.

  1. In ExpenseItHome.xaml, add another column to the xref:System.Windows.Controls.Grid.ColumnDefinitions%2A with a fixed xref:System.Windows.Controls.ColumnDefinition.Width%2A of 230 pixels:

    [!code-xamlExpenseIt#11]

  2. Add another row to the xref:System.Windows.Controls.Grid.RowDefinitions%2A, for a total of four rows:

    [!code-xamlExpenseIt#11b]

  3. Move the controls to the second column by setting the xref:System.Windows.Controls.Grid.Column%2A?displayProperty=nameWithType property to 1 in each of the three controls (Border, ListBox, and Button).

  4. Move each control down a row by incrementing its xref:System.Windows.Controls.Grid.Row%2A?displayProperty=nameWithType value by 1 for each of the three controls (Border, ListBox, and Button) and for the Border element.

    The XAML for the three controls now looks like the following:

    [!code-xamlExpenseIt#12]

  5. Set the Background property to the watermark.png image file, by adding the following XAML anywhere between the <Grid> and </Grid> tags:

    [!code-xamlExpenseIt#14]

  6. Before the xref:System.Windows.Controls.Border element, add a xref:System.Windows.Controls.Label with the content "View Expense Report". This label is the title of the page.

    [!code-xamlExpenseIt#13]

  7. Build and run the application.

The following illustration shows the results of what you just added:

ExpenseIt sample screenshot showing the new image background and page title

Add code to handle events

  1. In ExpenseItHome.xaml, add a xref:System.Windows.Controls.Primitives.ButtonBase.Click event handler to the xref:System.Windows.Controls.Button element. For more information, see How to: Create a simple event handler.

    [!code-xamlExpenseIt#15]

  2. Open ExpenseItHome.xaml.vb or ExpenseItHome.xaml.cs.

  3. Add the following code to the ExpenseItHome class to add a button click event handler. The event handler opens the ExpenseReportPage page.

    [!code-csharpExpenseIt#16] [!code-vbExpenseIt#16]

Create the UI for ExpenseReportPage

ExpenseReportPage.xaml displays the expense report for the person that's selected on the ExpenseItHome page. In this section, you'll create the UI for ExpenseReportPage. You'll also add background and fill colors to the various UI elements.

  1. Open ExpenseReportPage.xaml.

  2. Add the following XAML between the xref:System.Windows.Controls.Grid tags:

    [!code-xamlExpenseIt#17]

    This UI is similar to ExpenseItHome.xaml, except the report data is displayed in a xref:System.Windows.Controls.DataGrid.

  3. Build and run the application.

  4. Select the View button.

    The expense report page appears. Also notice that the back navigation button is enabled.

The following illustration shows the UI elements added to ExpenseReportPage.xaml.

ExpenseIt sample screenshot showing the UI just created for the ExpenseReportPage.

Style controls

The appearance of various elements is often the same for all elements of the same type in a UI. UI uses styles to make appearances reusable across multiple elements. The reusability of styles helps to simplify XAML creation and management. This section replaces the per-element attributes that were defined in previous steps with styles.

  1. Open Application.xaml or App.xaml.

  2. Add the following XAML between the xref:System.Windows.Application.Resources%2A?displayProperty=nameWithType tags:

    [!code-xamlExpenseIt#18]

    This XAML adds the following styles:

    • headerTextStyle: To format the page title xref:System.Windows.Controls.Label.

    • labelStyle: To format the xref:System.Windows.Controls.Label controls.

    • columnHeaderStyle: To format the xref:System.Windows.Controls.Primitives.DataGridColumnHeader.

    • listHeaderStyle: To format the list header xref:System.Windows.Controls.Border controls.

    • listHeaderTextStyle: To format the list header xref:System.Windows.Controls.Label.

    • buttonStyle: To format the xref:System.Windows.Controls.Button on ExpenseItHome.xaml.

    Notice that the styles are resources and children of the xref:System.Windows.Application.Resources%2A?displayProperty=nameWithType property element. In this location, the styles are applied to all the elements in an application. For an example of using resources in a .NET app, see Use Application Resources.

  3. In ExpenseItHome.xaml, replace everything between the xref:System.Windows.Controls.Grid elements with the following XAML:

    [!code-xamlExpenseIt#19]

    The properties such as xref:System.Windows.VerticalAlignment and xref:System.Windows.Media.FontFamily that define the look of each control are removed and replaced by applying the styles. For example, the headerTextStyle is applied to the "View Expense Report" xref:System.Windows.Controls.Label.

  4. Open ExpenseReportPage.xaml.

  5. Replace everything between the xref:System.Windows.Controls.Grid elements with the following XAML:

    [!code-xamlExpenseIt#20]

    This XAML adds styles to the xref:System.Windows.Controls.Label and xref:System.Windows.Controls.Border elements.

  6. Build and run the application. The window appearance is the same as previously.

    ExpenseIt sample screenshot with the same appearance as in the last section.

  7. Close the application to return to Visual Studio.

Bind data to a control

In this section, you'll create the XML data that is bound to various controls.

  1. In ExpenseItHome.xaml, after the opening xref:System.Windows.Controls.Grid element, add the following XAML to create an xref:System.Windows.Data.XmlDataProvider that contains the data for each person:

    [!code-xamlExpenseIt#23]

    The data is created as a xref:System.Windows.Controls.Grid resource. Normally this data would be loaded as a file, but for simplicity the data is added inline.

  2. Within the <Grid.Resources> element, add the following <xref:System.Windows.DataTemplate> element, which defines how to display the data in the xref:System.Windows.Controls.ListBox, after the <XmlDataProvider> element:

    [!code-xamlExpenseIt#24]

    For more information about data templates, see Data templating overview.

  3. Replace the existing xref:System.Windows.Controls.ListBox with the following XAML:

    [!code-xamlExpenseIt#25]

    This XAML binds the xref:System.Windows.Controls.ItemsControl.ItemsSource%2A property of the xref:System.Windows.Controls.ListBox to the data source and applies the data template as the xref:System.Windows.Controls.ItemsControl.ItemTemplate%2A.

Connect data to controls

Next, you'll add code to retrieve the name that's selected on the ExpenseItHome page and pass it to the constructor of ExpenseReportPage. ExpenseReportPage sets its data context with the passed item, which is what the controls defined in ExpenseReportPage.xaml bind to.

  1. Open ExpenseReportPage.xaml.vb or ExpenseReportPage.xaml.cs.

  2. Add a constructor that takes an object so you can pass the expense report data of the selected person.

    [!code-csharpExpenseIt#26] [!code-vbExpenseIt#26]

  3. Open ExpenseItHome.xaml.vb or ExpenseItHome.xaml.cs.

  4. Change the xref:System.Windows.Controls.Primitives.ButtonBase.Click event handler to call the new constructor passing the expense report data of the selected person.

    [!code-csharpExpenseIt#27] [!code-vbExpenseIt#27]

Style data with data templates

In this section, you'll update the UI for each item in the data-bound lists by using data templates.

  1. Open ExpenseReportPage.xaml.

  2. Bind the content of the "Name" and "Department" xref:System.Windows.Controls.Label elements to the appropriate data source property. For more information about data binding, see Data binding overview.

    [!code-xamlExpenseIt#31]

  3. After the opening xref:System.Windows.Controls.Grid element, add the following data templates, which define how to display the expense report data:

    [!code-xamlExpenseIt#30]

  4. Replace the xref:System.Windows.Controls.DataGridTextColumn elements with xref:System.Windows.Controls.DataGridTemplateColumn under the xref:System.Windows.Controls.DataGrid element and apply the templates to them. Also, specify the ItemsSource attribute with its value in the DataGrid Element.

    [!code-xamlExpenseIt#32]

  5. Build and run the application.

  6. Select a person and then select the View button.

The following illustration shows both pages of the ExpenseIt application with controls, layout, styles, data binding, and data templates applied:

Both pages of the app showing the names list and an expense report.

Note

This sample demonstrates a specific feature of WPF and doesn't follow all best practices for things like security, localization, and accessibility. For comprehensive coverage of WPF and the .NET app development best practices, see the following topics:

Next steps

In this walkthrough you learned a number of techniques for creating a UI using Windows Presentation Foundation (WPF). You should now have a basic understanding of the building blocks of a data-bound .NET app. For more information about the WPF architecture and programming models, see the following topics:

For more information about creating applications, see the following topics:

See also