Edit

Share via

Tutorial: Create a simple WPF application with C#

  • Article

By completing this tutorial, you become familiar with many of the tools, dialog boxes, and designers that you can use when you develop applications with Visual Studio. You create a "Hello, World" application, design the UI, add code, and debug errors, while you learn about working in the integrated development environment (IDE).

Prerequisites

  • If you haven't already installed Visual Studio, go to the Visual Studio downloads page to install it for free.
  • Make sure the .NET desktop development workload is installed. You can verify this configuration in the Visual Studio Installer.
  • You can use either .NET Framework or .NET Core for this tutorial. .NET Core is the newer, more modern framework. .NET Core requires Visual Studio 2019 version 16.3 or later.

What is WPF?

WPF, or Windows Presentation Foundation, is a UI (user interface) framework that creates desktop client applications. The WPF development platform supports a broad set of application development features, including an application model, resources, controls, graphics, layout, data binding, documents, and security.

WPF is part of .NET, so if you have previously built applications with .NET using ASP.NET or Windows Forms, the programming experience should be familiar. WPF uses the Extensible Application Markup Language XAML to provide a declarative model for application programming. For more information, see WPF .NET overview.

Configure the IDE

When you launch Visual Studio, the start window opens first. Select Continue without code to open the development environment. You see tool windows, the menus and toolbars, and the main window space. Tool windows are docked on the left and right sides of the application window. The search box, menu bar, and the standard toolbar are located at the top. When you load a solution or project, editors and designers appear in the central space of the application window. When you develop an application, you spend most of your time in this central area.

Create the project

When you create an application in Visual Studio, you first create a project and a solution. For this example, you create a Windows Presentation Foundation (WPF) project.

  1. Open Visual Studio.

  2. On the start window, choose Create new project.

    View the 'Create a new project' window

  3. On the Create a new project screen, search for "WPF," choose WPF Application, and then choose Next.

    Screenshot of the 'Create a new project' dialog with 'WPF' entered in the search box, and the 'WPF Application' project template highlighted.

  4. At the next screen, give the project a name, HelloWPFApp, and choose Next.

    Screenshot of the 'Configure your new project' dialog in Visual Studio with 'HelloWPFApp' entered in the Project name field.

  5. In the Additional information window, .NET Core 3.1 should already be selected for your target framework. If not, select .NET Core 3.1. Then, choose Create.

    Screenshot that shows the Additional information window in Visual Studio with .NET Core 3.1 selected as the target framework for the new project.

Visual Studio creates the HelloWPFApp project and solution, and Solution Explorer shows the various files. The WPF Designer shows a design view and a XAML view of MainWindow.xaml in a split view. You can slide the splitter to show more or less of either view. You can choose to see only the visual view or only the XAML view.

WPF project and solution in the IDE

Note

For more information about XAML (eXtensible Application Markup Language), see the XAML overview for WPF page.

After you create the project, you can customize it. To do so, choose Properties Window from the View menu, or press F4. Then, you can display and change options for project items, controls, and other items in an application.

Properties window

  1. Open Visual Studio.

  2. On the start window, choose Create a new project.

    Screenshot of the start window in Visual Studio 2022 with the 'Create a new project' option highlighted.

  3. On the Create a new project screen, search for "WPF," choose WPF Application, and then choose Next.

    Screenshot of the 'Create a new project' dialog with 'WPF' entered in the search box, and the 'WPF Application' project template highlighted.

  4. At the next screen, give the project a name, HelloWPFApp, and choose Next.

    Screenshot that shows the 'Configure your new project' dialog in Visual Studio with 'HelloWPFApp' entered in the Project name field.

  5. In the Additional information window, verify that .NET 8.0 is selected for your target framework. Then, choose Create.

    Screenshot that shows the Additional information window in Visual Studio with .NET 8.0 selected as the target framework for the new project.

Visual Studio creates the HelloWPFApp project and solution, and Solution Explorer shows the various files. The WPF Designer shows a design view and a XAML view of MainWindow.xaml in a split view. You can slide the splitter to show more or less of either view. You can choose to see only the visual view or only the XAML view.

Screenshot of the HelloWPFApp project and solution in Solution Explorer, and the XAML and designer views of 'MainWindow.xaml' open in the WPF Designer.

Note

For more information about XAML (eXtensible Application Markup Language), see the XAML overview for WPF page.

After you create the project, you can customize it. To do so, choose Properties Window from the View menu, or press F4. Then, you can display and change options for project items, controls, and other items in an application.

Screenshot of the Properties window showing the Misc section of the Solution Properties for the HelloWPFApp project.

Design the user interface (UI)

If the designer isn't open, select MainWindow.xaml and press Shift+F7 to open the designer.

We add three types of controls to this application: a TextBlock control, two RadioButton controls, and a Button control.

Add a TextBlock control

  1. Press Ctrl+Q to activate the search box and type Toolbox. Choose View > Toolbox from the results list.

  2. In the Toolbox, expand the Common WPF Controls node to see the TextBlock control.

    Toolbox with the TextBlock control highlighted

  3. Add a TextBlock control to the design surface by choosing the TextBlock item and dragging it to the window on the design surface. Center the control near the top of the window. In Visual Studio 2019 and later, you can use the red guidelines to center the control.

    Your window should resemble the following illustration:

    TextBlock control on the MainWindow form

    The XAML markup should look something like the following example:

    <Grid>
    <TextBlock HorizontalAlignment="Left" Margin="387,60,0,0" TextWrapping="Wrap" Text="TextBlock" VerticalAlignment="Top"/>
</Grid>

  1. Press Ctrl+Q to activate the search box and type Toolbox. Choose View > Toolbox from the results list.

  2. In the Toolbox, expand the Common WPF Controls node to see the TextBlock control.

    Screenshot of the Toolbox window with the TextBlock control selected in the list of Common WPF Controls.

  3. Add a TextBlock control to the design surface by choosing the TextBlock item and dragging it to the window on the design surface. Center the control near the top of the window. You can use the guidelines to center the control.

    Your window should resemble the following image:

    Screenshot of the TextBlock control on the design surface. Guidelines are shown for positioning and resizing the control.

    The XAML markup should look something like the following example:

    <Grid>
    <TextBlock HorizontalAlignment="Left" Margin="387,60,0,0" TextWrapping="Wrap" Text="TextBlock" VerticalAlignment="Top"/>
</Grid>

Customize the text in the text block

  1. In the XAML view, locate the markup for TextBlock and change the Text attribute from TextBlock to Select a message option and then choose the Display button.

    The XAML markup should look something like the following example:

    <Grid>
    <TextBlock HorizontalAlignment="Left" Margin="387,60,0,0" TextWrapping="Wrap" Text="Select a message option and then choose the Display button." VerticalAlignment="Top"/>
</Grid>

  2. Center the TextBlock again if you like, and then save your changes by pressing Ctrl+S or using the File menu item.

Next, you add two RadioButton controls to the form.

Add radio buttons

  1. In the Toolbox, find the RadioButton control.

    Toolbox window with RadioButton control selected

  2. Add two RadioButton controls to the design surface by choosing the RadioButton item and dragging it to the window on the design surface. Move the buttons (by selecting them and using the arrow keys) so that the buttons appear side by side under the TextBlock control. Use the red guidelines to align the controls.

    Your window should look like this:

    MainWindow form with TextBlock and two radio buttons

  3. In the Properties window for the left RadioButton control, change the Name property (the property at the top of the Properties window) to HelloButton.

    RadioButton properties window

  4. In the Properties window for the right RadioButton control, change the Name property to GoodbyeButton, and then save your changes.

Next, you add display text for each RadioButton control. The following procedure updates the Content property for a RadioButton control.

  1. In the Toolbox, find the RadioButton control.

    Screenshot of the Toolbox window with the RadioButton control selected in the list of Common WPF Controls.

  2. Add two RadioButton controls to the design surface by choosing the RadioButton item and dragging it to the window on the design surface. Move the buttons (by selecting them and using the arrow keys) so that the buttons appear side by side under the TextBlock control. You can use the guidelines to align the controls.

    Your window should look like this:

    Screenshot of the Design window for Greetings.xaml, showing a TextBlock control and two RadioButton controls positioned on the design surface.

  3. In the Properties window for the left RadioButton control, change the Name property (the property at the top of the Properties window) to HelloButton.

    Screenshot of the Properties window for a RadioButton control. The value of the Name property has been changed to HelloButton.

  4. In the Properties window for the right RadioButton control, change the Name property to GoodbyeButton, and then save your changes.

Next, you add display text for each RadioButton control. The following procedure updates the Content property for a RadioButton control.

Add display text for each radio button

  1. Update the Content attribute for the two radio buttons HelloButton and GoodbyeButton to "Hello" and "Goodbye" in the XAML. The XAML markup should now look similar to the following example:

    <Grid>
     <TextBlock HorizontalAlignment="Left" Margin="252,47,0,0" TextWrapping="Wrap" Text="Select a message option and then choose the Display button." VerticalAlignment="Top"/>
     <RadioButton x:Name="HelloButton" Content="Hello" HorizontalAlignment="Left" Margin="297,161,0,0" VerticalAlignment="Top"/>
     <RadioButton x:Name="GoodbyeButton" Content="Goodbye" HorizontalAlignment="Left" Margin="488,161,0,0" VerticalAlignment="Top"/>
</Grid>

Set a radio button to be checked by default

In this step, we set HelloButton to be checked by default so that one of the two radio buttons is always selected.

  1. In the XAML view, locate the markup for HelloButton.

  2. Add an IsChecked attribute and set it to True. Specifically, add IsChecked="True".

    The XAML markup should now look similar to the following example:

    <Grid>
     <TextBlock HorizontalAlignment="Left" Margin="252,47,0,0" TextWrapping="Wrap" Text="Select a message option and then choose the Display button." VerticalAlignment="Top"/>
     <RadioButton x:Name="HelloButton" Content="Hello" IsChecked="True" HorizontalAlignment="Left" Margin="297,161,0,0" VerticalAlignment="Top"/>
     <RadioButton x:Name="GoodbyeButton" Content="Goodbye" HorizontalAlignment="Left" Margin="488,161,0,0" VerticalAlignment="Top"/>
</Grid>

The final UI element that you add is a Button control.

Add the button control

  1. In the Toolbox, find the Button control, and then add it to the design surface under the RadioButton controls by dragging it to the form in the design view. If you're using Visual Studio 2019 or later, a red line helps you center the control.

  2. In the XAML view, change the value of Content for the Button control from Content="Button" to Content="Display", and then save the changes.

    Your window should resemble the following illustration.

    MainWindow form with control labels

    The XAML markup should now look similar to the following example:

    <Grid>
     <TextBlock HorizontalAlignment="Left" Margin="252,47,0,0" TextWrapping="Wrap" Text="Select a message option and then choose the Display button." VerticalAlignment="Top"/>
     <RadioButton x:Name="HelloButton" Content="Hello" IsChecked="True" HorizontalAlignment="Left" Margin="297,161,0,0" VerticalAlignment="Top"/>
     <RadioButton x:Name="GoodbyeButton" Content="Goodbye" HorizontalAlignment="Left" Margin="488,161,0,0" VerticalAlignment="Top"/>
     <Button Content="Display" HorizontalAlignment="Left" Margin="377,270,0,0" VerticalAlignment="Top" Width="75"/>
</Grid>

  1. In the Toolbox, find the Button control, and then add it to the design surface under the RadioButton controls by dragging it to the form in the design view. The guidelines can help you center the control.

  2. In the XAML view, change the value of Content for the Button control from Content="Button" to Content="Display", and then save the changes.

    Your window should resemble the following screenshot.

    Screenshot of the Design window for Greetings.xaml showing a TextBlock control, two RadioButton controls labeled 'Hello' and 'Goodbye', and a button labeled 'Display'.

    The XAML markup should now look similar to the following example:

    <Grid>
     <TextBlock HorizontalAlignment="Left" Margin="252,47,0,0" TextWrapping="Wrap" Text="Select a message option and then choose the Display button." VerticalAlignment="Top"/>
     <RadioButton x:Name="HelloButton" Content="Hello" IsChecked="True" HorizontalAlignment="Left" Margin="297,161,0,0" VerticalAlignment="Top"/>
     <RadioButton x:Name="GoodbyeButton" Content="Goodbye" HorizontalAlignment="Left" Margin="488,161,0,0" VerticalAlignment="Top"/>
     <Button Content="Display" HorizontalAlignment="Left" Margin="377,270,0,0" VerticalAlignment="Top" Width="75"/>
</Grid>

Add code to the display button

When this application runs, a message box appears after a user chooses a radio button and then chooses the Display button. One message box appears for Hello, and another appears for Goodbye. To create this behavior, you add code to the Button_Click event in MainWindow.xaml.cs.

  1. On the design surface, double-click the Display button.

    MainWindow.xaml.cs opens, with the cursor in the Button_Click event.

    private void Button_Click(object sender, RoutedEventArgs e)
{

}

  2. Enter the following code:

    if (HelloButton.IsChecked == true)
{
     MessageBox.Show("Hello.");
}
else if (GoodbyeButton.IsChecked == true)
{
    MessageBox.Show("Goodbye.");
}

  3. Save the application.

When this application runs, a message box appears after a user chooses a radio button and then chooses the Display button. One message box appears for Hello, and another appears for Goodbye. To create this behavior, you add code to the Button_Click event in MainWindow.xaml.cs.

  1. On the design surface, double-click the Display button.

    MainWindow.xaml.cs opens, with the cursor in the Button_Click event.

    private void Button_Click(object sender, RoutedEventArgs e)
{

}

    When you double-click the Display button, Click="Button_Click" is added to the XAML.

    The XAML markup should now look similar to the following example:

    <Grid>
     <TextBlock HorizontalAlignment="Left" Margin="252,47,0,0" TextWrapping="Wrap" Text="Select a message option and then choose the Display button." VerticalAlignment="Top"/>
     <RadioButton x:Name="HelloButton" Content="Hello" IsChecked="True" HorizontalAlignment="Left" Margin="297,161,0,0" VerticalAlignment="Top"/>
     <RadioButton x:Name="GoodbyeButton" Content="Goodbye" HorizontalAlignment="Left" Margin="488,161,0,0" VerticalAlignment="Top"/>
     <Button Content="Display" HorizontalAlignment="Left" Margin="377,270,0,0" VerticalAlignment="Top" Width="75" Click="Button_Click"/>
</Grid>

  2. Enter the following code:

    if (HelloButton.IsChecked == true)
{
     MessageBox.Show("Hello.");
}
else if (GoodbyeButton.IsChecked == true)
{
    MessageBox.Show("Goodbye.");
}

  3. Save the application.

Debug and test the application

Next, you debug the application to look for errors and test that both message boxes appear correctly. The following instructions tell you how to build and launch the debugger, but later you might read Build a WPF application (WPF) and Debug WPF for more information.

Change the name of MainWindow.xaml

Let's give MainWindow a more specific name. In Solution Explorer, right-click on MainWindow.xaml and choose Rename. Rename the file to Greetings.xaml.

Find and fix errors

In this step, you find the error that we caused earlier by changing the name of the MainWindow.xaml file.

Start debugging and find the error

  1. Start the debugger by pressing F5 or selecting Debug, then Start Debugging.

    A Break Mode window appears, and the Output window indicates that an IOException has occurred: Cannot locate resource mainwindow.xaml.

    IOException message

  2. Stop the debugger by choosing Debug > Stop Debugging.

We renamed MainWindow.xaml to Greetings.xaml, but the code still refers to MainWindow.xaml as the startup URI for the application, so the project can't start.

  1. Start the debugger by pressing F5 or selecting Debug, then Start Debugging.

    A Break Mode window appears, and the Output window indicates that an IOException has occurred: Cannot locate resource mainwindow.xaml.

    Screenshot of the Output window showing a System.IO.IOException with the message, Cannot locate resource mainwindow.xaml.

  2. Stop the debugger by choosing Debug > Stop Debugging.

We renamed MainWindow.xaml to Greetings.xaml at the start of this tutorial, but the code still refers to MainWindow.xaml as the startup URI for the application, so the project can't start.

Specify Greetings.xaml as the startup URI

  1. In Solution Explorer, open the App.xaml file.

  2. Change StartupUri="MainWindow.xaml" to StartupUri="Greetings.xaml", and save the changes.

As an optional step, it avoids confusion to change the title of your application window to match this new name.

  1. In Solution Explorer, open the Greetings.xaml file that you just renamed.

  2. Change the value of the Window.Title property from Title="MainWindow" to Title="Greetings", and save the changes.

Start the debugger again (press F5). You should now see the Greetings window of your application.

Screenshot of running app

Screenshot of the Greetings window with the TextBlock, RadioButtons, and Button controls visible. The 'Hello' radio button is selected.

Now close the application window to stop debugging.

Debug with breakpoints

You can test the code during debugging by adding some breakpoints. You can add breakpoints by choosing Debug > Toggle Breakpoint, by clicking in the left margin of the editor next to the line of code where you want the break to occur, or by pressing F9.

Add breakpoints

  1. Open Greetings.xaml.cs, and select the following line: MessageBox.Show("Hello.")

  2. Add a breakpoint from the menu by selecting Debug, then Toggle Breakpoint.

    A red circle appears next to the line of code in the far left margin of the editor window.

  3. Select the following line: MessageBox.Show("Goodbye.").

  4. Press the F9 key to add a breakpoint, and then press F5 to start debugging.

  5. In the Greetings window, choose the Hello radio button, and then choose the Display button.

    The line MessageBox.Show("Hello.") is highlighted in yellow. At the bottom of the IDE, the Autos, Locals, and Watch windows are docked together on the left side, and the Call Stack, Breakpoints, Exception Settings, Command, Immediate, and Output windows are docked together on the right side.

    Breakpoint in the debugger

  6. On the menu bar, choose Debug > Step Out.

    The application resumes execution, and a message box with the word "Hello" appears.

  7. Choose the OK button on the message box to close it.

  8. In the Greetings window, choose the Goodbye radio button, and then choose the Display button.

    The line MessageBox.Show("Goodbye.") is highlighted in yellow.

  9. Choose the F5 key to continue debugging. When the message box appears, choose the OK button on the message box to close it.

  10. Close the application window to stop debugging.

  11. On the menu bar, choose Debug > Disable All Breakpoints.

  1. Open Greetings.xaml.cs, and select the following line: MessageBox.Show("Hello.")

  2. Add a breakpoint from the menu by selecting Debug, then Toggle Breakpoint.

    A red circle appears next to the line of code in the far left margin of the editor window.

  3. Select the following line: MessageBox.Show("Goodbye.").

  4. Press the F9 key to add a breakpoint, and then press F5 to start debugging.

  5. In the Greetings window, choose the Hello radio button, and then choose the Display button.

    The line MessageBox.Show("Hello.") is highlighted in yellow. At the bottom of the IDE, the Autos, Locals, and Watch windows are docked together on the left side, and the Call Stack, Breakpoints, Exception Settings, Command, Immediate, and Output windows are docked together on the right side.

    Screenshot of a debug session in Visual Studio. The code window for Greetings.xaml.cs shows execution stopped at a breakpoint with a line highlighted in yellow.

  6. On the menu bar, choose Debug > Step Out.

    The application resumes execution, and a message box with the word "Hello" appears.

  7. Choose the OK button on the message box to close it.

  8. In the Greetings window, choose the Goodbye radio button, and then choose the Display button.

    The line MessageBox.Show("Goodbye.") is highlighted in yellow.

  9. Choose the F5 key to continue debugging. When the message box appears, choose the OK button on the message box to close it.

  10. Close the application window to stop debugging.

  11. On the menu bar, choose Debug > Disable All Breakpoints.

View a representation of the UI elements

In the running app, you should see a widget that appears at the top of your window. The widget is a runtime helper that provides quick access to some helpful debugging features. Select the first button, Go to Live Visual Tree. You should see a window with a tree that contains all the visual elements of your page. Expand the nodes to find the buttons you added.

Screenshot of Live Visual Tree window

Screenshot of the Live Visual Tree window, showing the tree of visual elements in HelloWPFApp.exe while it's running.

Build a release version of the application

Now that you've verified that everything works, you can prepare a release build of the application.

  1. On the main menu, select Build > Clean solution to delete intermediate files and output files that were created during previous builds. This step isn't required, but it cleans up the debug build outputs.

  2. Change the build configuration for HelloWPFApp from Debug to Release by using the dropdown control on the toolbar (it says "Debug" currently).

  3. Build the solution by choosing Build > Build Solution.

Congratulations on completing this tutorial! You can find the .exe you built under your solution and project directory (...\HelloWPFApp\HelloWPFApp\bin\Release).

Next steps

Congratulations on completing this tutorial! To learn even more, continue with the following tutorials.

Continue with more WPF tutorials

See also