Initial publish of WinForms for .NET 5. (#96)

* Migrate inprogress winforms contnet from docs

* Fix preview note

* Fix vb code

* Minor fixes to keyboard articles

* Minor adjustment to overview

* Test redirects for 4.0 -> 5.0

* adjust links

* Add mouse input section winforms (#81)

* Update projects to .NET 5

* Update keyboard desc

* Finish mouse events

* Add remaining mouse articles;code

* finish mouse input

* minor fixes

* Remove branch restriction (#82)

* Update build-validation.yml (#84)

* Update build-validation.yml (#85)

* Fix vb proj

* Add WinForms tutorial (#91)

* redirect between overview

* New create an app tutorial

* Fix markdown

* Fix preserve view setting

* Add forms articles (#93)

* Add forms articles

* Fix warnings

* Winforms publish (#95)

* Prep TOC for publish

* Updated date

* Automatic how-to topic type

* Update desc/headers

* Fix links

* Fix build errors

* Add preview note

* Update toc landing page

* Convert old style project files

* update download links

* Apply suggestions from code review

Co-authored-by: Genevieve Warren <[email protected]>

* Adjust number key

* Update dotnet-desktop-guide/net/winforms/overview/index.md

* Try toc position task via bookmark

* Improve images

* Remove sentence

* File redirects

Co-authored-by: Genevieve Warren <[email protected]>
This commit is contained in:
Andy De George
2020-10-28 10:44:16 -07:00
committed by GitHub
co-authored by Genevieve Warren
parent f7e5ce92ea
commit 184e6c9a0c
225 changed files with 8864 additions and 35 deletions
@@ -0,0 +1,163 @@
---
title: "Create a new app with Visual Studio tutorial"
description: Follow this tutorial to learn how to create a new Windows Forms app for .NET with Visual Studio 2019.
ms.date: 10/26/2020
ms.topic: tutorial
dev_langs:
- "csharp"
- "vb"
---
# Tutorial: Create a new WinForms app (Windows Forms .NET)
In this short tutorial, you'll learn how to create a new Windows Forms (WinForms) app with Visual Studio. Once the initial app has been generated, you'll learn how to add controls and how to handle events. By the end of this tutorial, you'll have a simple app that adds names to a list box.
[!INCLUDE [desktop guide under construction](../../includes/desktop-guide-preview-note.md)]
In this tutorial, you learn how to:
> [!div class="checklist"]
>
> - Create a new WinForms app
> - Add controls to a form
> - Handle control events to provide app functionality
> - Run the app
## Prerequisites
- [Visual Studio 2019 version 16.8 Preview](https://visualstudio.microsoft.com/downloads/?utm_medium=microsoft&utm_source=docs.microsoft.com&utm_campaign=inline+link&utm_content=download+vs2019+desktopguide+winforms)
- [Visual Studio Desktop workload](/visualstudio/install/modify-visual-studio?view=vs-2019&preserve-view=true)
## Create a WinForms app
The first step to creating a new app is opening Visual Studio and generating the app from a template.
01. Open Visual Studio.
01. Select **Create a new project**.
:::image type="content" source="media/create-app-visual-studio/vs-create-new-project.png" alt-text="Create a new Windows Forms project in Visual Studio 2019 for .NET":::
01. In the **Search for templates** box, type **winforms**, and then press <kbd>Enter</kbd>.
01. In the **code language** dropdown, choose **C#** or **Visual Basic**.
01. In the templates list, select **Windows Forms App (.NET)** and then click **Next**.
> [!IMPORTANT]
> Don't select the **Windows Forms App (.NET _Framework_)** template.
:::image type="content" source="media/create-app-visual-studio/vs-template-search.png" alt-text="Search for the Windows Forms template in Visual Studio 2019 for .NET":::
01. In the **Configure your new project** window, set the **Project name** to **Names** and click **Create**.
You can also save your project to a different folder by adjusting the **Location** setting.
:::image type="content" source="media/create-app-visual-studio/vs-config-new-project.png" alt-text="Configure new Windows Forms project in Visual Studio 2019 for .NET":::
Once the app is generated, Visual Studio should open the designer pane for the default form, _Form1_. If the form designer isn't visible, double-click on the form in the **Solution Explorer** pane to open the designer window.
### Important parts of Visual Studio
Support for WinForms in Visual Studio has four important components that you'll interact with as you create an app:
:::image type="content" source="media/create-app-visual-studio/vs-main-window.png" alt-text="The important components of Visual Studio you should know when creating a Windows Forms project for .NET":::
01. Solution Explorer
All if your project files, code, forms, resources, will appear in this pane.
02. Properties
This pane shows property settings you can configure based on the item selected. For example, if you select an item from **Solution Explorer**, you'll see property settings related to the file. If you select an object in the **Designer**, you'll see settings for the control or form.
03. Form Designer
This is the designer for the form. It's interactive and you can drag-and-drop objects from the **Toolbox**. By selecting and moving items in the designer, you can visually compose the user interface (UI) for your app.
04. Toolbox
The toolbox contains all of the controls you can add to a form. To add a control to the current form, double-click a control or drag-and-drop the control.
## Add controls to the form
With the _Form1_ form designer open, use the **Toolbox** pane to add the following controls to the form:
- Label
- Button
- Listbox
- Textbox
You can position and size the controls according to the following settings. Either visually move them to match the screenshot that follows, or click on each control and configure the settings in the **Properties** pane. You can also click on the form title area to select the form:
| Object | Setting | Value |
|---------|----------|------------|
| Form | Text | `Names` |
| | Size | `268, 180` |
| Label | Location | `12, 9` |
| | Text | `Names` |
| Listbox | Name | `lstNames` |
| | Location | `12, 27` |
| | Size | `120, 94` |
| Textbox | Name | `txtName` |
| | Location | `138, 26` |
| | Size | `100, 23` |
| Button | Name | `btnAdd` |
| | Location | `138, 55` |
| | Size | `100, 23` |
| | Text | `Add Name` |
You should have a form in the designer that looks similar to the following:
:::image type="content" source="media/create-app-visual-studio/vs-form-preview.png" alt-text="Visual Studio 2019 designer with the form open for Windows Forms for .NET":::
## Handle events
Now that the form has all of its controls laid out, you need to handle the events of the controls to respond to user input. With the form designer still open, perform the following steps:
01. Select the button control on the form.
01. In the **Properties** pane, click on the events icon :::image type="icon" source="media/create-app-visual-studio/icon-events.png" border="false"::: to list the events of the button.
01. Find the **Click** event and double-click it to generate an event handler.
This action adds the following code to the the form:
```csharp
private void btnAdd_Click(object sender, EventArgs e)
{
}
```
```vb
Private Sub btnAdd_Click(sender As Object, e As EventArgs) Handles btnAdd.Click
End Sub
```
The code we'll put in this handler will add the name specified by the `txtName` textbox control to the `lstNames` listbox control. However, we want there to be two conditions to adding the name: the name provided must not be blank, and the name must not already exist.
01. The following code demonstrates adding a name to the `lstNames` control:
```csharp
private void btnAdd_Click(object sender, EventArgs e)
{
if (!string.IsNullOrWhiteSpace(txtName.Text) && !lstNames.Items.Contains(txtName.Text))
lstNames.Items.Add(txtName.Text);
}
```
```vb
Private Sub btnAdd_Click(sender As Object, e As EventArgs) Handles btnAdd.Click
If Not String.IsNullOrWhiteSpace(txtName.Text) And Not lstNames.Items.Contains(txtName.Text) Then
lstNames.Items.Add(txtName.Text)
End If
End Sub
```
## Run the app
Now that the event has been coded, you can run the app by pressing the <kbd>F5</kbd> key or by selecting **Debug** > **Start Debugging** from the menu. The form displays and you can enter a name in the textbox and then add it by clicking the button.
:::image type="content" source="media/create-app-visual-studio/app-running.png" alt-text="Running a Windows Forms for .NET app.":::
## Next steps
> [!div class="nextstepaction"]
> [Learn more about Windows Forms](../overview/index.md)
Binary file not shown.

After

Width:  |  Height:  |  Size: 3.5 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 263 B

Binary file not shown.

After

Width:  |  Height:  |  Size: 270 B

Binary file not shown.

After

Width:  |  Height:  |  Size: 21 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 38 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 6.4 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 44 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 11 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 9.7 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 38 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 39 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 38 KiB

@@ -0,0 +1,98 @@
namespace project
{
partial class Form1
{
/// <summary>
/// Required designer variable.
/// </summary>
private System.ComponentModel.IContainer components = null;
/// <summary>
/// Clean up any resources being used.
/// </summary>
/// <param name="disposing">true if managed resources should be disposed; otherwise, false.</param>
protected override void Dispose(bool disposing)
{
if (disposing && (components != null))
{
components.Dispose();
}
base.Dispose(disposing);
}
#region Windows Form Designer generated code
/// <summary>
/// Required method for Designer support - do not modify
/// the contents of this method with the code editor.
/// </summary>
private void InitializeComponent()
{
this.label1 = new System.Windows.Forms.Label();
this.lstNames = new System.Windows.Forms.ListBox();
this.btnAdd = new System.Windows.Forms.Button();
this.txtName = new System.Windows.Forms.TextBox();
this.SuspendLayout();
//
// label1
//
this.label1.AutoSize = true;
this.label1.Location = new System.Drawing.Point(12, 9);
this.label1.Name = "label1";
this.label1.Size = new System.Drawing.Size(44, 15);
this.label1.TabIndex = 0;
this.label1.Text = "Names";
//
// lstNames
//
this.lstNames.FormattingEnabled = true;
this.lstNames.ItemHeight = 15;
this.lstNames.Location = new System.Drawing.Point(12, 27);
this.lstNames.Name = "lstNames";
this.lstNames.Size = new System.Drawing.Size(120, 94);
this.lstNames.TabIndex = 1;
//
// btnAdd
//
this.btnAdd.Location = new System.Drawing.Point(138, 55);
this.btnAdd.Name = "btnAdd";
this.btnAdd.Size = new System.Drawing.Size(100, 23);
this.btnAdd.TabIndex = 2;
this.btnAdd.Text = "Add Name";
this.btnAdd.UseVisualStyleBackColor = true;
this.btnAdd.Click += new System.EventHandler(this.btnAdd_Click);
//
// txtName
//
this.txtName.Location = new System.Drawing.Point(138, 26);
this.txtName.Name = "txtName";
this.txtName.Size = new System.Drawing.Size(100, 23);
this.txtName.TabIndex = 3;
//
// Form1
//
this.AutoScaleDimensions = new System.Drawing.SizeF(7F, 15F);
this.AutoScaleMode = System.Windows.Forms.AutoScaleMode.Font;
this.ClientSize = new System.Drawing.Size(252, 141);
this.Controls.Add(this.txtName);
this.Controls.Add(this.btnAdd);
this.Controls.Add(this.lstNames);
this.Controls.Add(this.label1);
this.Cursor = System.Windows.Forms.Cursors.Default;
this.Name = "Form1";
this.Text = "Names";
this.Load += new System.EventHandler(this.Form1_Load);
this.ResumeLayout(false);
this.PerformLayout();
}
#endregion
private System.Windows.Forms.Label label1;
private System.Windows.Forms.ListBox lstNames;
private System.Windows.Forms.Button btnAdd;
private System.Windows.Forms.TextBox txtName;
}
}
@@ -0,0 +1,33 @@
using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Windows.Forms;
using System.Runtime.InteropServices;
namespace project
{
public partial class Form1 : Form
{
public Form1()
{
InitializeComponent();
}
private void Form1_Load(object sender, EventArgs e)
{
}
private void btnAdd_Click(object sender, EventArgs e)
{
if (!string.IsNullOrWhiteSpace(txtName.Text) && !lstNames.Items.Contains(txtName.Text))
lstNames.Items.Add(txtName.Text);
}
}
}
@@ -0,0 +1,60 @@
<root>
<xsd:schema id="root" xmlns="" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
<xsd:import namespace="http://www.w3.org/XML/1998/namespace" />
<xsd:element name="root" msdata:IsDataSet="true">
<xsd:complexType>
<xsd:choice maxOccurs="unbounded">
<xsd:element name="metadata">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="value" type="xsd:string" minOccurs="0" />
</xsd:sequence>
<xsd:attribute name="name" use="required" type="xsd:string" />
<xsd:attribute name="type" type="xsd:string" />
<xsd:attribute name="mimetype" type="xsd:string" />
<xsd:attribute ref="xml:space" />
</xsd:complexType>
</xsd:element>
<xsd:element name="assembly">
<xsd:complexType>
<xsd:attribute name="alias" type="xsd:string" />
<xsd:attribute name="name" type="xsd:string" />
</xsd:complexType>
</xsd:element>
<xsd:element name="data">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
<xsd:element name="comment" type="xsd:string" minOccurs="0" msdata:Ordinal="2" />
</xsd:sequence>
<xsd:attribute name="name" type="xsd:string" use="required" msdata:Ordinal="1" />
<xsd:attribute name="type" type="xsd:string" msdata:Ordinal="3" />
<xsd:attribute name="mimetype" type="xsd:string" msdata:Ordinal="4" />
<xsd:attribute ref="xml:space" />
</xsd:complexType>
</xsd:element>
<xsd:element name="resheader">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
</xsd:sequence>
<xsd:attribute name="name" type="xsd:string" use="required" />
</xsd:complexType>
</xsd:element>
</xsd:choice>
</xsd:complexType>
</xsd:element>
</xsd:schema>
<resheader name="resmimetype">
<value>text/microsoft-resx</value>
</resheader>
<resheader name="version">
<value>2.0</value>
</resheader>
<resheader name="reader">
<value>System.Resources.ResXResourceReader, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
</resheader>
<resheader name="writer">
<value>System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
</resheader>
</root>
@@ -0,0 +1,23 @@
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using System.Windows.Forms;
namespace project
{
static class Program
{
/// <summary>
/// The main entry point for the application.
/// </summary>
[STAThread]
static void Main()
{
Application.SetHighDpiMode(HighDpiMode.SystemAware);
Application.EnableVisualStyles();
Application.SetCompatibleTextRenderingDefault(false);
Application.Run(new Form1());
}
}
}
@@ -0,0 +1,13 @@
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>WinExe</OutputType>
<TargetFramework>net5.0-windows</TargetFramework>
<UseWindowsForms>true</UseWindowsForms>
</PropertyGroup>
<ItemGroup>
<Compile Update="Main.cs" />
</ItemGroup>
</Project>
@@ -0,0 +1,85 @@
<Global.Microsoft.VisualBasic.CompilerServices.DesignerGenerated()>
Partial Class Form1
Inherits System.Windows.Forms.Form
'Form overrides dispose to clean up the component list.
<System.Diagnostics.DebuggerNonUserCode()>
Protected Overrides Sub Dispose(ByVal disposing As Boolean)
Try
If disposing AndAlso components IsNot Nothing Then
components.Dispose()
End If
Finally
MyBase.Dispose(disposing)
End Try
End Sub
'Required by the Windows Form Designer
Private components As System.ComponentModel.IContainer
'NOTE: The following procedure is required by the Windows Form Designer
'It can be modified using the Windows Form Designer.
'Do not modify it using the code editor.
<System.Diagnostics.DebuggerStepThrough()>
Private Sub InitializeComponent()
Me.Label1 = New System.Windows.Forms.Label()
Me.lstNames = New System.Windows.Forms.ListBox()
Me.txtName = New System.Windows.Forms.TextBox()
Me.btnAdd = New System.Windows.Forms.Button()
Me.SuspendLayout()
'
'Label1
'
Me.Label1.AutoSize = True
Me.Label1.Location = New System.Drawing.Point(12, 9)
Me.Label1.Name = "Label1"
Me.Label1.Size = New System.Drawing.Size(44, 15)
Me.Label1.TabIndex = 0
Me.Label1.Text = "Names"
'
'lstNames
'
Me.lstNames.FormattingEnabled = True
Me.lstNames.ItemHeight = 15
Me.lstNames.Location = New System.Drawing.Point(12, 27)
Me.lstNames.Name = "lstNames"
Me.lstNames.Size = New System.Drawing.Size(120, 94)
Me.lstNames.TabIndex = 1
'
'txtName
'
Me.txtName.Location = New System.Drawing.Point(138, 26)
Me.txtName.Name = "txtName"
Me.txtName.Size = New System.Drawing.Size(100, 23)
Me.txtName.TabIndex = 2
'
'btnAdd
'
Me.btnAdd.Location = New System.Drawing.Point(138, 55)
Me.btnAdd.Name = "btnAdd"
Me.btnAdd.Size = New System.Drawing.Size(100, 23)
Me.btnAdd.TabIndex = 3
Me.btnAdd.Text = "Add Name"
Me.btnAdd.UseVisualStyleBackColor = True
'
'Form1
'
Me.AutoScaleDimensions = New System.Drawing.SizeF(7.0!, 15.0!)
Me.AutoScaleMode = System.Windows.Forms.AutoScaleMode.Font
Me.ClientSize = New System.Drawing.Size(252, 141)
Me.Controls.Add(Me.btnAdd)
Me.Controls.Add(Me.txtName)
Me.Controls.Add(Me.lstNames)
Me.Controls.Add(Me.Label1)
Me.Name = "Form1"
Me.Text = "Names"
Me.ResumeLayout(False)
Me.PerformLayout()
End Sub
Friend WithEvents Label1 As Windows.Forms.Label
Friend WithEvents lstNames As Windows.Forms.ListBox
Friend WithEvents txtName As Windows.Forms.TextBox
Friend WithEvents btnAdd As Windows.Forms.Button
End Class
@@ -0,0 +1,60 @@
<root>
<xsd:schema id="root" xmlns="" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
<xsd:import namespace="http://www.w3.org/XML/1998/namespace" />
<xsd:element name="root" msdata:IsDataSet="true">
<xsd:complexType>
<xsd:choice maxOccurs="unbounded">
<xsd:element name="metadata">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="value" type="xsd:string" minOccurs="0" />
</xsd:sequence>
<xsd:attribute name="name" use="required" type="xsd:string" />
<xsd:attribute name="type" type="xsd:string" />
<xsd:attribute name="mimetype" type="xsd:string" />
<xsd:attribute ref="xml:space" />
</xsd:complexType>
</xsd:element>
<xsd:element name="assembly">
<xsd:complexType>
<xsd:attribute name="alias" type="xsd:string" />
<xsd:attribute name="name" type="xsd:string" />
</xsd:complexType>
</xsd:element>
<xsd:element name="data">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
<xsd:element name="comment" type="xsd:string" minOccurs="0" msdata:Ordinal="2" />
</xsd:sequence>
<xsd:attribute name="name" type="xsd:string" use="required" msdata:Ordinal="1" />
<xsd:attribute name="type" type="xsd:string" msdata:Ordinal="3" />
<xsd:attribute name="mimetype" type="xsd:string" msdata:Ordinal="4" />
<xsd:attribute ref="xml:space" />
</xsd:complexType>
</xsd:element>
<xsd:element name="resheader">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
</xsd:sequence>
<xsd:attribute name="name" type="xsd:string" use="required" />
</xsd:complexType>
</xsd:element>
</xsd:choice>
</xsd:complexType>
</xsd:element>
</xsd:schema>
<resheader name="resmimetype">
<value>text/microsoft-resx</value>
</resheader>
<resheader name="version">
<value>2.0</value>
</resheader>
<resheader name="reader">
<value>System.Resources.ResXResourceReader, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
</resheader>
<resheader name="writer">
<value>System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
</resheader>
</root>
@@ -0,0 +1,19 @@
Imports System.Windows.Forms
Imports System.Drawing
Partial Public Class Form1
Public Sub New()
InitializeComponent()
End Sub
Private Sub Form1_Load(sender As Object, e As EventArgs) Handles MyBase.Load
End Sub
Private Sub btnAdd_Click(sender As Object, e As EventArgs) Handles btnAdd.Click
If Not String.IsNullOrWhiteSpace(txtName.Text) And Not lstNames.Items.Contains(txtName.Text) Then
lstNames.Items.Add(txtName.Text)
End If
End Sub
End Class
@@ -0,0 +1,15 @@
Imports System
Imports System.Collections.Generic
Imports System.Linq
Imports System.Threading.Tasks
Imports System.Windows.Forms
Module Program
Sub Main(args As String())
Application.SetHighDpiMode(HighDpiMode.SystemAware)
Application.EnableVisualStyles()
Application.SetCompatibleTextRenderingDefault(False)
Application.Run(New Form1())
End Sub
End Module
@@ -0,0 +1,14 @@
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>WinExe</OutputType>
<TargetFramework>net5.0-windows</TargetFramework>
<UseWindowsForms>true</UseWindowsForms>
<StartupObject>Sub Main</StartupObject>
</PropertyGroup>
<ItemGroup>
<Compile Update="Main.vb" />
</ItemGroup>
</Project>