Add user control to the Start Page

Article
11/04/2016

Applies to: Visual Studio Visual Studio for Mac

Note

This article applies to Visual Studio 2017. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

This walkthrough shows how to add a DLL reference to a custom Start Page. The example adds a user control to the solution, builds the user control, and then references the built assembly from the Start Page .xaml file. A new tab hosts the user control, which functions as a basic Web browser.

You can use the same process to add any assembly that can be called from a .xaml file.

Add a WPF user control to the solution

First, add a Windows Presentation Foundation (WPF) user control to the Start Page solution.

Create a Start Page by using we created in Create a custom Start Page.
In Solution Explorer, right-click the solution, click Add, and then click New Project.
In the left pane of the New Project dialog box, expand either the Visual Basic or Visual C# node, and click Windows. In the middle pane, select WPF User Control Library.
Name the control WebUserControl and then click OK.

Implement the user control

To implement a WPF user control, build the user interface (UI) in XAML and then write the code-behind events in C# or another .NET language.

To write the XAML for the user control

Open the XAML file for the user control. In the <Grid> element, add the following row definitions to the control.

<Grid.RowDefinitions>
    <RowDefinition Height="Auto"/>
    <RowDefinition Height="*" />
</Grid.RowDefinitions>

In the main <Grid> element, add the following new <Grid> element, which contains a text box for typing Web addresses and a button for setting the new address.

<Grid Grid.Row="0">
    <Grid.ColumnDefinitions>
        <ColumnDefinition Width="*" />
        <ColumnDefinition Width="Auto" />
    </Grid.ColumnDefinitions>
    <TextBox x:Name="UserSource" Grid.Column="0" />
    <Button Grid.Column="1" x:Name="SetButton" Content="Set Address" Click="SetButton_Click" />
</Grid>

Add the following frame to the top-level <Grid> element just after the <Grid> element that contains the button and textbox.
```
<Frame Grid.Row="1" x:Name="WebFrame" Source="http://www.bing.com" Navigated="WebFrame_Navigated" />
```

The following example shows the completed XAML for the user control.

<UserControl x:Class="WebUserControl.UserControl1"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
             xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
             mc:Ignorable="d"
             d:DesignHeight="300" d:DesignWidth="300">
    <Grid>
        <Grid.RowDefinitions>
            <RowDefinition Height="Auto"/>
            <RowDefinition Height="*" />
        </Grid.RowDefinitions>
        <Grid Grid.Row="0">
            <Grid.ColumnDefinitions>
                <ColumnDefinition Width="*" />
                <ColumnDefinition Width="Auto" />
            </Grid.ColumnDefinitions>
            <TextBox x:Name="UserSource" Grid.Column="0" />
            <Button Grid.Column="1" x:Name="SetButton" Content="Set Address" Click="SetButton_Click" />
        </Grid>
        <Frame Grid.Row="1" x:Name="WebFrame" Source="http://www.bing.com" Navigated="WebFrame_Navigated" />
    </Grid>
</UserControl>

To write the code-behind events for the user control

In the XAML designer, double-click the Set Address button you added to the control.

The UserControl1.cs file opens in the code editor.

Fill in the SetButton_Click Event Handler as follows.

private void SetButton_Click(object sender, RoutedEventArgs e)
{
    try
    {
        this.WebFrame.Source = new Uri(this.UserSource.Text, UriKind.Absolute);
    }
    catch (Exception error)
    {
        MessageBox.Show(error.Message);
    }
}

This code sets the Web address that is typed in the text box as the target for the Web browser. If the address is not valid, the code throws an error.

You must also handle the WebFrame_Navigated event:

private void WebFrame_Navigated(object sender, EventArgs e)
{ }

Build the solution.

Add the user control to the Start Page

To make this control available to the Start Page project, in the Start Page project file, add a reference to the new control library. Then you can add the control to the Start Page XAML markup.

In Solution Explorer, in the Start Page project, right-click References and then click Add Reference.
On the Projects tab, select WebUserControl and then click OK.
On the Build menu, click Build Solution.

Building the solution makes the user control available to IntelliSense for other files in the solution.

To add the control to the Start Page XAML markup, add a namespace reference to the assembly, then put the control on the page.

To add the control to the markup

In Solution Explorer, open the Start Page .xaml file.
In the XAML pane, add the following namespace declaration to the top-level Grid element.
```
xmlns:vsc="clr-namespace:WebUserControl;assembly=WebUserControl"
```
In the XAML pane, scroll to the <Grid> section.

The section contains a TabControl element in a Grid element.
Add a <TabControl> element containing a <TabItem> that contains a reference to your user control.
```
<TabItem Header="Web" Height="Auto">
    <vsc:UserControl1 />
</TabItem>
```
Now you can test the control.

Test a manually created custom Start Page

Copy your XAML file, and any supporting text files or markup files, to the %USERPROFILE%\My Documents\Visual Studio 2015\StartPages\ folder.
If your start page references any controls or types in assemblies that are not installed by Visual Studio, copy the assemblies and then paste them in Visual Studio installation folder\Common7\IDE\PrivateAssemblies\.
At a Visual Studio command prompt, type devenv /rootsuffix Exp to open an experimental instance of Visual Studio.
In the experimental instance, go to the Tools > Options > Environment > Startup page and select your XAML file from the Customize Start Page dropdown.
On the View menu, click Start Page.

Your custom start page should be displayed. If you want to change any files, you must close the experimental instance, make the changes, copy and paste the changed files, and then re-open the experimental instance to view the changes.

Share via