diff --git a/docs/repo/property-pages/README.md b/docs/repo/property-pages/README.md index 40da453dd70..1d50aad6c95 100644 --- a/docs/repo/property-pages/README.md +++ b/docs/repo/property-pages/README.md @@ -12,6 +12,17 @@ This documentation details the updated Project Properties UI and associated back 4. Extensibility. We need to support 3rd parties (both internal and external) adding both entirely new pages _and_ customizing the pages we provide. 5. Support new functionality. We want to enable scenarios such as searching for properties, editing the MSBuild expressions that underpin many properties, and collecting the most commonly used properties in one area. +## Customising Project Properties + +To customise or extend the properties displayed for a given project start with these HOW TO guides: + +- [HOW TO: Add a new property page](how-to-add-a-new-property-page.md) + +And then check these documents for more details: + +- [Property Specification](property-specification.md) +- [Visibility Conditions](visibility-conditions.md) + ## Architecture The Property Pages can be broken down into two high-level layers, the UI via through which the user interacts, and the back-end through which the UI communicates with the underlying project system to retrieve and update data. This separation allows the feature to work in Codespaces, where the project system is running on the server and the client contains only UI code. @@ -20,10 +31,3 @@ Each layer is documented in more detail: - [UI Architecture](ui-architecture.md) - [Back-end Architecture](back-end-architecture.md) - -## Customising Project Properties - -If your goal is to customise or extend the properties displayed for a given project, you're unlikely to need information about the architecture of the system. Instead, start with these documents: - -- [Property Specification](property-specification.md) -- [Visibility Conditions](visibility-conditions.md) diff --git a/docs/repo/property-pages/how-to-add-a-new-property-page.md b/docs/repo/property-pages/how-to-add-a-new-property-page.md new file mode 100644 index 00000000000..cd5c0460dc9 --- /dev/null +++ b/docs/repo/property-pages/how-to-add-a-new-property-page.md @@ -0,0 +1,88 @@ +# HOW TO: Add a New Property Page + +Property pages are defined by XAML files describing an instance of the [Rule](https://docs.microsoft.com/en-us/dotnet/api/microsoft.build.framework.xamltypes.rule) class. Visual Studio uses these XAML files to dynamically build the UI and bind the controls to properties in your project. This HOW TO describes two options for defining and distributing these XAML files. At the end your property page will look something like this: + +![New Property Page](new-property-page.png) + +## Option 1: XAML file on disk + +In this option, the XAML resides in a standalone .xaml file on disk and is included in the end user's project as a specific kind of MSBuild item, `PropertyPageSchema`. Visual Studio reads these items from the project to determine which property pages to show. + +This may be an attractive option if you already have a NuGet package or Visual Studio extension that injects MSBuild .props and .targets files into the end user's project, or if you want to use MSBuild `Condition`s to control when the property page is available to a project. + +### Step 1 (optional): Add the Microsoft.Build.Framework package + +Use the NuGet Package Manager to add the Microsoft.Build.Framework package to your project. This is an optional step, but it will allow the XAML editor to find the [Rule](https://docs.microsoft.com/en-us/dotnet/api/microsoft.build.framework.xamltypes.rule) type (and related types) and provide code completion, tool tips, Go to Definition, and other features while you type. + +### Step 2: Define the XAML file + +Add a new XAML file named "MyPropertyPage.xaml" to your project. Depending on how the file is created you may end up with a `` item in your project but this is not what we want as we're not using the file to describe a piece of WPF UI. + +Update your project to replace the `` item with one of the following: + +- SDK-style projects: + ``` xml + + PreserveNewest + + ``` +- Non-SDK-style projects: + ``` xml + + PreserveNewest + + ``` + +Now VS won't do anything with this file but copy it to the output directory when you build. + +### Step 3: Define the `PropertyPageSchema` item + +Next you need to update the .props or .targets files imported by the end users' projects to properly reference the property page so Visual Studio can find it. Note that the creation and distribution of the .props and .targets files (as well as the distribution of MyPropertyPage.xaml itself) is beyond the scope of this document. + +Add the following item to your .props or .targets file: + +``` xml + + Project + +``` + +### Step 4: Describe the property page + +Replace the contents of MyPropertyPage.xaml with the following: + +```xml + + + + + + + + + + +``` + +The format of the file is described in detail in [Property Specification](property-specification.md), but the most important points are: +- The `Name` must be unique. +- The `PageTemplate` attribute must have the value `"generic"`. + +You should now be able to build and see the MyPropertyPage.xaml copied as-is to the output directory. + +And you're done. Projects that import the .targets file will now show this page when editing the project properties. + +## Option 2: Embedded XAML file + +In this option the XAML file is embedded in an assembly as a resource and discovered by means of a MEF export. Compared to Option 1 this requires more initial setup but does not require you to distribute an additional file. This may be an attractive option if you are already exporting MEF components for use in Visual Studio. + +_Steps to be determined._ diff --git a/docs/repo/property-pages/new-property-page.png b/docs/repo/property-pages/new-property-page.png new file mode 100644 index 00000000000..1957ec442e6 Binary files /dev/null and b/docs/repo/property-pages/new-property-page.png differ