From 232e200ce3b9c7d0c75a42bd09f95ba0dcde051a Mon Sep 17 00:00:00 2001 From: Kristen Schau <47155823+krschau@users.noreply.github.com> Date: Wed, 10 Apr 2024 11:35:17 -0400 Subject: [PATCH 01/13] Move navconfig.md --- docs/{ => tools}/navconfig.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename docs/{ => tools}/navconfig.md (97%) diff --git a/docs/navconfig.md b/docs/tools/navconfig.md similarity index 97% rename from docs/navconfig.md rename to docs/tools/navconfig.md index 8f1efc001c..831e115aee 100644 --- a/docs/navconfig.md +++ b/docs/tools/navconfig.md @@ -6,7 +6,7 @@ - path: #/navMenu - **_Properties_** - groups `required` - - Future: Items in navigation menu can be put into expand/collapsable groupings + - Future: Items in navigation menu can be put into expand/collapsible groupings - This is not yet supported and all tools are placed in top-level list - Type: `array` - path: #/navMenu/groups From 882c2d3f9a8fb1473c5a32f2ba4cea76de63aa65 Mon Sep 17 00:00:00 2001 From: Kristen Schau <47155823+krschau@users.noreply.github.com> Date: Wed, 10 Apr 2024 11:35:25 -0400 Subject: [PATCH 02/13] Update roadmap --- docs/roadmap.md | 40 +++++++++++++++++++++++++--------------- 1 file changed, 25 insertions(+), 15 deletions(-) diff --git a/docs/roadmap.md b/docs/roadmap.md index 475c3ea72c..ba9b7c1009 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -30,21 +30,24 @@ Last, but certainly not least are features and bugs with the most 👍 indicatin ## Release cadence -Dev Home is engineered and delivered as a set of 4-week [milestones]. Below is the schedule for when milestones will be included in release builds of Dev Home. The dates are rough estimates and are subject to change. - -| Milestone end date | Milestone name | Blog post | -| ------------------ | -------------- | --------- | -| 2023-05-23 | 0.1 | [Introducing Dev Home] | -| 2023-06-15 | [0.2] | [Dev Home Preview 0.2 Release] | -| 2023-07-13 | [0.3] | [Dev Home Preview 0.3 Release] | -| 2023-08-17 | [0.4] | [Dev Home Preview 0.4 Release] | -| 2023-09-14 | [0.5] | | -| 2023-10-12 | [0.6] | | -| 2023-11-16 | [0.7] | | -| 2023-12-14 | 0.8 | | -| 2024-01-18 | 0.9 | | -| 2024-02-15 | 0.10 | | -| 2024-03-14 | 0.11 | | +Dev Home is engineered and delivered as a set of monthly [milestones]. Below is the schedule for when milestones will be included in release builds of Dev Home. The dates are rough estimates and are subject to change. + +| Milestone end date | Milestone name | Blog post | +| ------------------- | -------------- | --------- | +| 2023-05-23 | 0.1 | [Introducing Dev Home] | +| 2023-06-15 | [0.2] | [Dev Home Preview 0.2 Release] | +| 2023-07-13 | [0.3] | [Dev Home Preview 0.3 Release] | +| 2023-08-17 | [0.4] | [Dev Home Preview 0.4 Release] | +| 2023-09-19 | [0.5] | | +| 2023-10-17 | [0.6] | | +| 2023-11-14 | [0.7] | | +| 2023-12-12 | [0.8] | | +| 2024-01-08 | [0.9] | | +| 2024-01-16 | [0.10] | | +| 2024-02-21 | [0.11] | | +| 2024-03-12 | [0.12] | | +| 2024-04-16 | [0.13] | | +| 2024-05-14 | [0.14] | | [Features]: https://github.com/microsoft/devhome/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc+label%3AIssue-Feature+ [Bugs]: https://github.com/microsoft/devhome/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc+label%3AIssue-Bug+ @@ -56,6 +59,13 @@ Dev Home is engineered and delivered as a set of 4-week [milestones]. Below is t [0.5]: https://github.com/microsoft/devhome/milestone/5 [0.6]: https://github.com/microsoft/devhome/milestone/9 [0.7]: https://github.com/microsoft/devhome/milestone/10 +[0.8]: https://github.com/microsoft/devhome/milestone/11 +[0.9]: https://github.com/microsoft/devhome/milestone/12 +[0.10]: https://github.com/microsoft/devhome/milestone/13 +[0.11]: https://github.com/microsoft/devhome/milestone/14 +[0.12]: https://github.com/microsoft/devhome/milestone/15 +[0.13]: https://github.com/microsoft/devhome/milestone/16 +[0.14]: https://github.com/microsoft/devhome/milestone/17 [Introducing Dev Home]: https://blogs.windows.com/windowsdeveloper/2023/05/30/introducing-dev-home/ [Dev Home Preview 0.2 Release]: https://blogs.windows.com/windowsdeveloper/2023/06/21/dev-home-preview-0-2-release/ From 2d0e1446745e799b9ed30bf6f43c73d3eb1b3e84 Mon Sep 17 00:00:00 2001 From: Kristen Schau <47155823+krschau@users.noreply.github.com> Date: Wed, 10 Apr 2024 11:40:34 -0400 Subject: [PATCH 03/13] update tools --- docs/tools.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/tools.md b/docs/tools.md index 5a76119de2..d3462f0dd1 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -8,6 +8,11 @@ Tools utilize data and functionality from out-of-process [extensions](./extensio 1. Create a new directory with your tool's name under `tools` with three subdirectories `src`, `test`, and `uitest` 1. Create a new `WinUI 3 Class Library` project in your `src` directory +1. In your project file, remove `TargetFramework` and `TargetPlatformMinVersion`. Add the following line to the top: + ```xml + + ``` +1. Remove the PackageReference to WindowsAppSDK, since it will be added via the Common project in a few steps. 1. Create the `Strings\en-us` directories under `src`. Add `Resources.resw` and include the following code: ```xml @@ -15,7 +20,7 @@ Tools utilize data and functionality from out-of-process [extensions](./extensio [Extra information about the name of your tool that may help translation] ``` -1. Add a project reference from `DevHome` to your project +1. Add a project reference from `DevHome.csproj` to your project 1. Add a project reference from your project to `DevHome.Common.csproj` project under [/common/](/common) 1. Create your XAML View and ViewModel. Your View class must inherit from `ToolPage` and implement [tool interface requirements](#tool-requirements). 1. Update [NavConfig.jsonc](/src/NavConfig.jsonc) with your tool. Specifications for the [NavConfig.json schema](navconfig.md). @@ -73,7 +78,3 @@ navigationService.NavigateTo(KnownPageKeys.); ``` This keeps the dependency tree simple, and prevents circular references when two projects want to navigate to each other. - -## Existing tools - -[Dashboard](./tools/Dashboard.md) From d78693e8d519a62e7b854e4ef65049fc6512dc0e Mon Sep 17 00:00:00 2001 From: Kristen Schau <47155823+krschau@users.noreply.github.com> Date: Wed, 10 Apr 2024 11:45:10 -0400 Subject: [PATCH 04/13] move stuff around --- docs/{ => extensions}/environments/Environments-General.md | 0 docs/{ => extensions}/environments/Interfaces/IComputeSystem.md | 0 .../environments/Interfaces/IComputeSystemProvider.md | 0 docs/{ => extensions}/extensions.md | 0 docs/{ => tools}/ExperimentalFeatures.md | 0 docs/{ => tools}/common/CloseButton.md | 0 docs/{ => tools}/common/Readme.md | 0 docs/{ => tools}/common/SecondaryWindow.md | 0 docs/{ => tools}/common/StringResource.md | 0 docs/{ => tools}/common/WindowOpenFileDialog.md | 0 docs/{ => tools}/common/WindowOpenFolderDialog.md | 0 docs/{ => tools}/common/WindowSaveFileDialog.md | 0 docs/{ => tools}/common/WindowTitleBar.md | 0 docs/{ => tools}/tools.md | 0 14 files changed, 0 insertions(+), 0 deletions(-) rename docs/{ => extensions}/environments/Environments-General.md (100%) rename docs/{ => extensions}/environments/Interfaces/IComputeSystem.md (100%) rename docs/{ => extensions}/environments/Interfaces/IComputeSystemProvider.md (100%) rename docs/{ => extensions}/extensions.md (100%) rename docs/{ => tools}/ExperimentalFeatures.md (100%) rename docs/{ => tools}/common/CloseButton.md (100%) rename docs/{ => tools}/common/Readme.md (100%) rename docs/{ => tools}/common/SecondaryWindow.md (100%) rename docs/{ => tools}/common/StringResource.md (100%) rename docs/{ => tools}/common/WindowOpenFileDialog.md (100%) rename docs/{ => tools}/common/WindowOpenFolderDialog.md (100%) rename docs/{ => tools}/common/WindowSaveFileDialog.md (100%) rename docs/{ => tools}/common/WindowTitleBar.md (100%) rename docs/{ => tools}/tools.md (100%) diff --git a/docs/environments/Environments-General.md b/docs/extensions/environments/Environments-General.md similarity index 100% rename from docs/environments/Environments-General.md rename to docs/extensions/environments/Environments-General.md diff --git a/docs/environments/Interfaces/IComputeSystem.md b/docs/extensions/environments/Interfaces/IComputeSystem.md similarity index 100% rename from docs/environments/Interfaces/IComputeSystem.md rename to docs/extensions/environments/Interfaces/IComputeSystem.md diff --git a/docs/environments/Interfaces/IComputeSystemProvider.md b/docs/extensions/environments/Interfaces/IComputeSystemProvider.md similarity index 100% rename from docs/environments/Interfaces/IComputeSystemProvider.md rename to docs/extensions/environments/Interfaces/IComputeSystemProvider.md diff --git a/docs/extensions.md b/docs/extensions/extensions.md similarity index 100% rename from docs/extensions.md rename to docs/extensions/extensions.md diff --git a/docs/ExperimentalFeatures.md b/docs/tools/ExperimentalFeatures.md similarity index 100% rename from docs/ExperimentalFeatures.md rename to docs/tools/ExperimentalFeatures.md diff --git a/docs/common/CloseButton.md b/docs/tools/common/CloseButton.md similarity index 100% rename from docs/common/CloseButton.md rename to docs/tools/common/CloseButton.md diff --git a/docs/common/Readme.md b/docs/tools/common/Readme.md similarity index 100% rename from docs/common/Readme.md rename to docs/tools/common/Readme.md diff --git a/docs/common/SecondaryWindow.md b/docs/tools/common/SecondaryWindow.md similarity index 100% rename from docs/common/SecondaryWindow.md rename to docs/tools/common/SecondaryWindow.md diff --git a/docs/common/StringResource.md b/docs/tools/common/StringResource.md similarity index 100% rename from docs/common/StringResource.md rename to docs/tools/common/StringResource.md diff --git a/docs/common/WindowOpenFileDialog.md b/docs/tools/common/WindowOpenFileDialog.md similarity index 100% rename from docs/common/WindowOpenFileDialog.md rename to docs/tools/common/WindowOpenFileDialog.md diff --git a/docs/common/WindowOpenFolderDialog.md b/docs/tools/common/WindowOpenFolderDialog.md similarity index 100% rename from docs/common/WindowOpenFolderDialog.md rename to docs/tools/common/WindowOpenFolderDialog.md diff --git a/docs/common/WindowSaveFileDialog.md b/docs/tools/common/WindowSaveFileDialog.md similarity index 100% rename from docs/common/WindowSaveFileDialog.md rename to docs/tools/common/WindowSaveFileDialog.md diff --git a/docs/common/WindowTitleBar.md b/docs/tools/common/WindowTitleBar.md similarity index 100% rename from docs/common/WindowTitleBar.md rename to docs/tools/common/WindowTitleBar.md diff --git a/docs/tools.md b/docs/tools/tools.md similarity index 100% rename from docs/tools.md rename to docs/tools/tools.md From 99f551648e249bc64faeb45e65c3f6954ca8a3c8 Mon Sep 17 00:00:00 2001 From: Kristen Schau <47155823+krschau@users.noreply.github.com> Date: Wed, 10 Apr 2024 11:52:52 -0400 Subject: [PATCH 05/13] Delete src/readme.md copied from TemplateStudio --- src/README.md | 27 --------------------------- 1 file changed, 27 deletions(-) delete mode 100644 src/README.md diff --git a/src/README.md b/src/README.md deleted file mode 100644 index 723a8306c5..0000000000 --- a/src/README.md +++ /dev/null @@ -1,27 +0,0 @@ -*Recommended Markdown Viewer: [Markdown Editor](https://marketplace.visualstudio.com/items?itemName=MadsKristensen.MarkdownEditor2)* - -## Getting Started - -Browse and address `TODO:` comments in `View -> Task List` to learn the codebase and understand next steps for turning the generated code into production code. - -Explore the [WinUI Gallery](https://www.microsoft.com/store/productId/9P3JFPWWDZRC) to learn about available controls and design patterns. - -Relaunch Template Studio to modify the project by right-clicking on the project in `View -> Solution Explorer` then selecting `Add -> New Item (Template Studio)`. - -## Publishing - -For projects with MSIX packaging, right-click on the application project and select `Package and Publish -> Create App Packages...` to create an MSIX package. - -For projects without MSIX packaging, follow the [deployment guide](https://docs.microsoft.com/windows/apps/windows-app-sdk/deploy-unpackaged-apps) or add the `Self-Contained` Feature to enable xcopy deployment. - -## CI Pipelines - -See [README.md](https://github.com/microsoft/TemplateStudio/blob/main/docs/WinUI/pipelines/README.md) for guidance on building and testing projects in CI pipelines. - -## Changelog - -See [releases](https://github.com/microsoft/TemplateStudio/releases) and [milestones](https://github.com/microsoft/TemplateStudio/milestones). - -## Feedback - -Bugs and feature requests should be filed at https://aka.ms/templatestudio. From 7d043654ec06856b7db1307176611c7ddf32f94a Mon Sep 17 00:00:00 2001 From: Kristen Schau <47155823+krschau@users.noreply.github.com> Date: Wed, 10 Apr 2024 11:53:21 -0400 Subject: [PATCH 06/13] Update architecture links --- docs/architecture.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 4e7b27fd8f..23691025d8 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -49,11 +49,11 @@ Dev Home Core is the central part of Dev Home where all the components come toge The Dev Home Common component contains code that is shared among the tools, core, and settings components. It also imports libraries that are used across Dev Home. One such library is the **Dev Home Extension SDK** used to get references to out-of-process extensions. -Dev Home Common also provides logging and telemetry functionality. +Dev Home Common also provides telemetry functionality. ## Settings -This is a special component that acts similarly a tool but isn't actually a tool. The Settings component, like other tools, consumes the Common project and is used by Dev Home Core. It manages user preferences across all tools and extensions. +This is a special component that acts similarly to a tool but isn't actually a tool. The Settings component, like other tools, consumes the Common project and is used by Dev Home Core. It manages user preferences across all tools and extensions. ## Tools @@ -61,13 +61,13 @@ The tools are a set of functionalities that are integrated within Dev Home's cod These tools can use the APIs in the extension SDK to get data or functionality from the extensions. -Learn more about [writing a tool](./tools.md). +Learn more about [writing a tool](./tools/tools.md). Dev Home currently has the following tools: -- [Dashboard](./tools.md#dashboard-tool) -- [Setup flow](./tools.md#setup-flow-tool) -- Extensions +- [Dashboard](./tools/Dashboard.md) +- Setup flow +- Extensions Library - [Windows customization](../tools/Customization/DevHome.Customization/Customization.md) ## Extensions @@ -76,4 +76,4 @@ Extensions are separate packages living as out-of-process components that provid Extensions can be developed by third-party developers or by Dev Home's core development team. These extensions allow Dev Home to be extended without modifying its core codebase. -Learn more about [writing an extension](./extensions.md). +Learn more about [writing an extension](./extensions/extensions.md). From 7913bbcd0bbb00db8f6b497aede213429eb73409 Mon Sep 17 00:00:00 2001 From: Kristen Schau <47155823+krschau@users.noreply.github.com> Date: Wed, 10 Apr 2024 12:01:05 -0400 Subject: [PATCH 07/13] remove duplicated content between readme and contributing --- CONTRIBUTING.md | 8 ++++++++ docs/readme.md | 20 ++------------------ 2 files changed, 10 insertions(+), 18 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 26526cba71..39dc2417d4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -153,6 +153,14 @@ Once you've discussed your proposed feature/fix/etc. with a team member and you' 5. Work on your changes 6. Build and see if it works +### Rules + +- **Follow the pattern of what you already see in the code.** +- [Coding style](style.md). +- Try to package new ideas/components into libraries that have nicely defined interfaces. +- Package new ideas into classes or refactor existing ideas into a class as you extend. +- When adding new classes/methods/changing existing code: add new unit tests or update the existing tests. + ### Code review When you'd like the team to take a look (even if the work is not yet fully-complete), mark the PR as 'Ready For Review' so that the team can review your work and provide comments, suggestions, and request changes. It may take several cycles but the end result will be solid, testable, conformant code that is safe for us to merge. diff --git a/docs/readme.md b/docs/readme.md index fe9db5461b..f1bf0317ef 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -1,21 +1,5 @@ # Dev Documentation -## Fork, Clone, Branch and Create your PR - -Once you've discussed your proposed feature/fix/etc. with a team member, and you've agreed on an approach or a spec has been written and approved, it's time to start development: - -1. Fork the repo if you haven't already -1. Clone your fork locally -1. Create & push a feature branch -1. Work on your changes - -## Rules - -- **Follow the pattern of what you already see in the code.** -- [Coding style](style.md). -- Try to package new ideas/components into libraries that have nicely defined interfaces. -- Package new ideas into classes or refactor existing ideas into a class as you extend. -- When adding new classes/methods/changing existing code: add new unit tests or update the existing tests. -## Compiling Dev Home - -### Compiling Source Code - -There are two ways to compile locally. - -- Open the Developer Command Prompt for Visual Studio -- Run `Build` from Dev Home's root directory. You can pass in a list of platforms/configurations -- The Dev Home MSIX will be in your repo under `AppxPackages\x64\debug` - -Alternatively - -- Open `DevHome.sln` in Visual Studio, in the `Solutions Configuration` drop-down menu select `Release` or `Debug`, from the `Build` menu choose `Build Solution`. - -### Dev Home framework - -The Dev Home project contains the wrapping framework for Dev Home. -It's responsible for: -- Loading the individual Dev Home tools. -- Loading out-of-process extensions. -- Loading the main window and creating a skeleton UI. - - -## More - +Before you dive into developing for Dev Home, check out these resources: - [Dev Home Architecture](./architecture.md) - [Dev Home Tools](./tools/tools.md) - [Dev Home Extensions](./extensions/extensions.md) + From e5348c78305031f8cccc778fdbf6d038a9726f2b Mon Sep 17 00:00:00 2001 From: Kristen Schau <47155823+krschau@users.noreply.github.com> Date: Wed, 10 Apr 2024 12:34:18 -0400 Subject: [PATCH 09/13] add common adaptive card schema coming soon --- docs/tools/common/Readme.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/tools/common/Readme.md b/docs/tools/common/Readme.md index af87ea4a2f..bfca75325c 100644 --- a/docs/tools/common/Readme.md +++ b/docs/tools/common/Readme.md @@ -17,4 +17,8 @@ List of common controls that are generic, customizable and reusable from all pag - [WindowOpenFileDialog](./WindowOpenFileDialog.md) - [WindowOpenFolderDialog](./WindowOpenFolderDialog.md) -- [WindowSaveFileDialog](./WindowSaveFileDialog.md) \ No newline at end of file +- [WindowSaveFileDialog](./WindowSaveFileDialog.md) + +## Custom Adaptive Card schema + +Coming soon. From 92d527ba152c5597ad57424baaeda35281a62ae8 Mon Sep 17 00:00:00 2001 From: Kristen Schau <47155823+krschau@users.noreply.github.com> Date: Wed, 10 Apr 2024 12:34:08 -0400 Subject: [PATCH 10/13] Split up Tools page --- docs/architecture.md | 2 +- docs/readme.md | 2 +- docs/tools/advanced-tool-behavior.md | 24 ++++ docs/tools/{tools.md => creating-a-tool.md} | 139 +++++++++----------- docs/tools/readme.md | 9 ++ 5 files changed, 94 insertions(+), 82 deletions(-) create mode 100644 docs/tools/advanced-tool-behavior.md rename docs/tools/{tools.md => creating-a-tool.md} (53%) create mode 100644 docs/tools/readme.md diff --git a/docs/architecture.md b/docs/architecture.md index 23691025d8..b913056885 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -61,7 +61,7 @@ The tools are a set of functionalities that are integrated within Dev Home's cod These tools can use the APIs in the extension SDK to get data or functionality from the extensions. -Learn more about [writing a tool](./tools/tools.md). +Learn more about [tools](./tools/readme.md). Dev Home currently has the following tools: diff --git a/docs/readme.md b/docs/readme.md index e22860d2fe..31bd0c698f 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -2,6 +2,6 @@ Before you dive into developing for Dev Home, check out these resources: - [Dev Home Architecture](./architecture.md) -- [Dev Home Tools](./tools/tools.md) +- [Dev Home Tools](./tools/readme.md) - [Dev Home Extensions](./extensions/extensions.md) diff --git a/docs/tools/advanced-tool-behavior.md b/docs/tools/advanced-tool-behavior.md new file mode 100644 index 0000000000..fc653ff186 --- /dev/null +++ b/docs/tools/advanced-tool-behavior.md @@ -0,0 +1,24 @@ +# Advanced Tool behavior + +## Headers + +Coming soon. + +## Navigation + +In order to allow navigation to your tool, your page and ViewModel must be registered with the PageService. If your tool only contains one page, it is automatically registered for you since you added your page to `NavConfig.jsonc`. However, you may have other sub-pages you wish to register. + +In order to do so, you must create an extension method for the PageService inside your tool. See examples in [Settings](../settings/DevHome.Settings/Extensions/PageExtensions.cs) or [Extensions](../tools/ExtensionLibrary/DevHome.ExtensionLibrary/Extensions/PageExtensions.cs). Then, call your extension from the [PageService](../src/Services/PageService.cs). + +### Navigating away from your tool + +If you want a user action (such as clicking a link) to navigate away from your tool and your project does not otherwise rely on the destination project, do not create a PackageReference to the destination project from yours. Instead, add the destination page to `INavigationService.KnownPageKeys` and use it for navigation, like in this example: +```cs +navigationService.NavigateTo(KnownPageKeys.); +``` + +This keeps the dependency tree simple, and prevents circular references when two projects want to navigate to each other. + +## Common controls + +Dev Home has a set of common controls that are generic, customizable and reusable from all pages and tools in Dev Home. See [Common controls](./common/Readme.md). \ No newline at end of file diff --git a/docs/tools/tools.md b/docs/tools/creating-a-tool.md similarity index 53% rename from docs/tools/tools.md rename to docs/tools/creating-a-tool.md index d3462f0dd1..a8be7e740b 100644 --- a/docs/tools/tools.md +++ b/docs/tools/creating-a-tool.md @@ -1,80 +1,59 @@ -# Tools - -Dev Home adds functionality through a set of tools. Each tool provides a page in the Dev Home navigation view. Currently, all tools come from in-package assemblies. Third party or out-of-process tools are not supported at this time. - -Tools utilize data and functionality from out-of-process [extensions](./extensions.md). This is done through the Extension SDK API. - -## Writing a Tool - -1. Create a new directory with your tool's name under `tools` with three subdirectories `src`, `test`, and `uitest` -1. Create a new `WinUI 3 Class Library` project in your `src` directory -1. In your project file, remove `TargetFramework` and `TargetPlatformMinVersion`. Add the following line to the top: - ```xml - - ``` -1. Remove the PackageReference to WindowsAppSDK, since it will be added via the Common project in a few steps. -1. Create the `Strings\en-us` directories under `src`. Add `Resources.resw` and include the following code: - ```xml - - [Name of your tool that will appear in navigation menu] - [Extra information about the name of your tool that may help translation] - - ``` -1. Add a project reference from `DevHome.csproj` to your project -1. Add a project reference from your project to `DevHome.Common.csproj` project under [/common/](/common) -1. Create your XAML View and ViewModel. Your View class must inherit from `ToolPage` and implement [tool interface requirements](#tool-requirements). -1. Update [NavConfig.jsonc](/src/NavConfig.jsonc) with your tool. Specifications for the [NavConfig.json schema](navconfig.md). - -### Tool requirements - -Each tool must define a custom page view extending from the [`ToolPage`](../common/ToolPage.cs) abstract class, and implement it like in this example: - -```cs -public class SampleToolPage : ToolPage -{ - public override string ShortName => "SampleTool"; - - public SampleToolPage() - { - ViewModel = Application.Current.GetService(); - InitializeComponent(); - } -} -``` - -The Dev Home framework will look at all types in its assembly for any inheriting from `ToolPage`: - -On a found type, the framework will use: - - ShortName property to get the name of the tool - -#### Method definition - -This section contains a more detailed description of each of the interface methods. - -ShortName - -```cs -public abstract string ShortName { get; } -``` - -Returns the name of the tool. This is used for the navigation menu text. - -### Code organization - -[`toolpage.cs`](../common/ToolPage.cs) -Contains the interface definition for Dev Home tools. - -### Navigation - -In order to allow navigation to your tool, your page and ViewModel must be registered with the PageService. If your tool only contains one page, it is automatically registered for you since you added your page to `NavConfig.jsonc`. However, you may have other sub-pages you wish to register. - -In order to do so, you must create an extension method for the PageService inside your tool. See examples in [Settings](../settings/DevHome.Settings/Extensions/PageExtensions.cs) or [Extensions](../tools/ExtensionLibrary/DevHome.ExtensionLibrary/Extensions/PageExtensions.cs). Then, call your extension from the [PageService](../src/Services/PageService.cs). - -#### Navigating away from your tool - -If you want a user action (such as clicking a link) to navigate away from your tool and your project does not otherwise rely on the destination project, do not create a PackageReference to the destination project from yours. Instead, add the destination page to `INavigationService.KnownPageKeys` and use it for navigation, like in this example: -```cs -navigationService.NavigateTo(KnownPageKeys.); -``` - -This keeps the dependency tree simple, and prevents circular references when two projects want to navigate to each other. +# Creating a tool + +1. Create a new directory with your tool's name under `tools` with three subdirectories `src`, `test`, and `uitest` +1. Create a new `WinUI 3 Class Library` project in your `src` directory +1. In your project file, remove `TargetFramework` and `TargetPlatformMinVersion`. Add the following line to the top: + ```xml + + ``` +1. Remove the PackageReference to WindowsAppSDK, since it will be added via the Common project in a few steps. +1. Create the `Strings\en-us` directories under `src`. Add `Resources.resw` and include the following code: + ```xml + + [Name of your tool that will appear in navigation menu] + [Extra information about the name of your tool that may help translation] + + ``` +1. Add a project reference from `DevHome.csproj` to your project +1. Add a project reference from your project to `DevHome.Common.csproj` project under [/common/](/common) +1. Create your XAML View and ViewModel. Your View class must inherit from `ToolPage` and implement [tool interface requirements](#tool-requirements). +1. Update [NavConfig.jsonc](/src/NavConfig.jsonc) with your tool. Specifications for the [NavConfig.json schema](./navconfig.md). + +## Tool requirements + +Each tool must define a custom page view extending from the [`ToolPage`](../common/ToolPage.cs) abstract class, and implement it like in this example: + +```cs +public class SampleToolPage : ToolPage +{ + public override string ShortName => "SampleTool"; + + public SampleToolPage() + { + ViewModel = Application.Current.GetService(); + InitializeComponent(); + } +} +``` + +The Dev Home framework will look at all types in its assembly for any inheriting from `ToolPage`: + +On a found type, the framework will use: + - ShortName property to get the name of the tool + +### Method definition + +This section contains a more detailed description of each of the interface methods. + +ShortName + +```cs +public abstract string ShortName { get; } +``` + +Returns the name of the tool. This is used for the navigation menu text. + +## Code organization + +[`toolpage.cs`](../common/ToolPage.cs) +Contains the interface definition for Dev Home tools. \ No newline at end of file diff --git a/docs/tools/readme.md b/docs/tools/readme.md new file mode 100644 index 0000000000..eaa038ac69 --- /dev/null +++ b/docs/tools/readme.md @@ -0,0 +1,9 @@ +# Tools + +Dev Home adds functionality through a set of tools. Each tool provides a page in the Dev Home navigation view. Currently, all tools come from in-package assemblies. Third party or out-of-process tools are not supported at this time. + +Learn more about [creating a tool](./creating-a-tool.md). Then, learn about [advanced tool behavior](./advanced-tool-behavior.md). + +Tools utilize data and functionality from out-of-process [extensions](../extensions/extensions.md). This is done through the Extension SDK API. + +Tools support [experimental features](./ExperimentalFeatures.md). \ No newline at end of file From 341ca059a485d59f2f5f5799a0256746d58667d5 Mon Sep 17 00:00:00 2001 From: Kristen Schau <47155823+krschau@users.noreply.github.com> Date: Wed, 10 Apr 2024 12:54:21 -0400 Subject: [PATCH 11/13] update extensions readme --- docs/extensions/{extensions.md => readme.md} | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) rename docs/extensions/{extensions.md => readme.md} (89%) diff --git a/docs/extensions/extensions.md b/docs/extensions/readme.md similarity index 89% rename from docs/extensions/extensions.md rename to docs/extensions/readme.md index 8056407375..a65f70bfb1 100644 --- a/docs/extensions/extensions.md +++ b/docs/extensions/readme.md @@ -1,8 +1,8 @@ # Extensions -Dev Home is an app extension host which uses [out-of-process COM](https://learn.microsoft.com/en-us/samples/dotnet/samples/out-of-process-com-server/) to talk to external COM Server processes that declare themselves to be extensions of Dev Home. +Dev Home is an app extension host which uses [out-of-process COM](https://learn.microsoft.com/samples/dotnet/samples/out-of-process-com-server/) to talk to external COM Server processes that declare themselves to be extensions of Dev Home. -Dev Home currently supports extending two interfaces through the Extension SDK. In addition, extensions can provide widgets to Dev Home using [Widget providers](https://learn.microsoft.com/en-us/windows/apps/develop/widgets/widget-providers). +Dev Home currently supports extending two interfaces through the Extension SDK. In addition, extensions can provide widgets to Dev Home using [Widget providers](https://learn.microsoft.com/windows/apps/develop/widgets/widget-providers). ## Extension basics @@ -13,9 +13,9 @@ An extension can provide functionality for one or more extensibility points. Cur - Developer IDs: Allow developers to sign in and out of a service by implementing the [`IDeveloperIdProvider`](#ideveloperidprovider) interface. - Repositories: Allow developers to get available repositories associated with their Developer IDs or parse repositories from URLs and clone them by implementing the [`IRepositoryProvider`](#irepositoryprovider) interface. -Read more about [Provider interfaces](#provider-interfaces) below. Each extension also must have a class that implements `IExtension`. DevHome needs to create an instance of this class. The GUID of this class must be reflected in the manifest. See [Sample Extension](../SampleExtension/SampleExtension.cs) +Read more about [Provider interfaces](#provider-interfaces) below. Each extension also must have a class that implements `IExtension`. DevHome needs to create an instance of this class. The GUID of this class must be reflected in the manifest. See [Sample Extension](../../extensions/SampleExtension/SampleExtension.cs) -![Extension Flow](./images/extension-flow.png) +![Extension Flow](../images/extension-flow.png) ## Extension manifest @@ -120,7 +120,7 @@ public interface IRepository ## Sequence diagram -![Extension Sequence](./images/extension-sequence.png) +![Extension Sequence](../images/extension-sequence.png) ## Runtime logic From f93931dacdd0310a1ffcba97a11d0d9efef8fd8a Mon Sep 17 00:00:00 2001 From: Kristen Schau <47155823+krschau@users.noreply.github.com> Date: Wed, 10 Apr 2024 12:57:27 -0400 Subject: [PATCH 12/13] update environments --- docs/architecture.md | 2 +- .../environments/{Environments-General.md => readme.md} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename docs/extensions/environments/{Environments-General.md => readme.md} (100%) diff --git a/docs/architecture.md b/docs/architecture.md index b913056885..7fb47116df 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -76,4 +76,4 @@ Extensions are separate packages living as out-of-process components that provid Extensions can be developed by third-party developers or by Dev Home's core development team. These extensions allow Dev Home to be extended without modifying its core codebase. -Learn more about [writing an extension](./extensions/extensions.md). +Learn more about [writing an extension](./extensions/readme.md). diff --git a/docs/extensions/environments/Environments-General.md b/docs/extensions/environments/readme.md similarity index 100% rename from docs/extensions/environments/Environments-General.md rename to docs/extensions/environments/readme.md From 92ad94623f4f4a69ec6e12af5b1a59febf84823f Mon Sep 17 00:00:00 2001 From: Kristen Schau <47155823+krschau@users.noreply.github.com> Date: Wed, 10 Apr 2024 13:00:58 -0400 Subject: [PATCH 13/13] remove en-us from microsoft.learn links --- .../environments/Interfaces/IComputeSystemProvider.md | 2 +- docs/sampleConfigurations/Templates/Introduction/C#/README.md | 4 ++-- .../Templates/Introduction/C#/configuration.dsc.yaml | 2 +- .../sampleConfigurations/Templates/Introduction/C++/README.md | 4 ++-- .../Templates/Introduction/C++/configuration.dsc.yaml | 2 +- .../Templates/Introduction/JavaScript.NodeJS/README.md | 2 +- .../Introduction/JavaScript.NodeJS/configuration.dsc.yaml | 2 +- .../Templates/Introduction/PowerShell/README.md | 2 +- .../Templates/Introduction/Python3.12/README.md | 4 ++-- .../Templates/Introduction/Python3.12/configuration.dsc.yaml | 2 +- docs/sampleConfigurations/Templates/Introduction/README.md | 2 +- 11 files changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/extensions/environments/Interfaces/IComputeSystemProvider.md b/docs/extensions/environments/Interfaces/IComputeSystemProvider.md index ce2ca6a0d1..35decc5ef9 100644 --- a/docs/extensions/environments/Interfaces/IComputeSystemProvider.md +++ b/docs/extensions/environments/Interfaces/IComputeSystemProvider.md @@ -4,7 +4,7 @@ A **compute system provider** is the provider type that Dev Home will query when 1. Retrieve a list of `IComputeSystem`s 2. Create a new compute system -3. Provide Dev Home with an [Adaptive card](https://learn.microsoft.com/en-us/adaptive-cards/) for the creation of a new compute system +3. Provide Dev Home with an [Adaptive card](https://learn.microsoft.com/adaptive-cards/) for the creation of a new compute system 4. Provide Dev Home with an Adaptive card for the modification of a compute systems properties Dev Home will look at the [ComputeSystemProviderOperations](https://github.com/microsoft/devhome/blob/3dc0dd739b0175357cc3e74c713d305c09248537/extensionsdk/Microsoft.Windows.DevHome.SDK/Microsoft.Windows.DevHome.SDK.idl#L461) enum to determine what operations the provider supports. diff --git a/docs/sampleConfigurations/Templates/Introduction/C#/README.md b/docs/sampleConfigurations/Templates/Introduction/C#/README.md index 11f9ed7a30..e63e6c902c 100644 --- a/docs/sampleConfigurations/Templates/Introduction/C#/README.md +++ b/docs/sampleConfigurations/Templates/Introduction/C#/README.md @@ -1,12 +1,12 @@ ## Understanding WinGet Configuration Files -This folder contains a [Windows Package Manager](https://learn.microsoft.com/en-us/windows/package-manager/winget/) (WinGet) [Configuration File](https://learn.microsoft.com/en-us/windows/package-manager/configuration/) (*configuration.dsc.yaml*) that will work with the WinGet command line interface (`winget configure --file [path: configuration.dsc.yaml]`) or can be run using [Microsoft Dev Home](https://learn.microsoft.com/en-us/windows/dev-home/) Device Configuration. +This folder contains a [Windows Package Manager](https://learn.microsoft.com/windows/package-manager/winget/) (WinGet) [Configuration File](https://learn.microsoft.com/windows/package-manager/configuration/) (*configuration.dsc.yaml*) that will work with the WinGet command line interface (`winget configure --file [path: configuration.dsc.yaml]`) or can be run using [Microsoft Dev Home](https://learn.microsoft.com/windows/dev-home/) Device Configuration. When run, the `configuration.dsc.yaml` file will install the following list of applications: * Microsoft Visual Studio Community 2022 * Required Visual Studio Workloads (ManagedDesktop, Universal) * GitHub Desktop -The `configuration.dsc.yaml` file will also enable [Developer Mode](https://learn.microsoft.com/en-us/windows/apps/get-started/developer-mode-features-and-debugging) on your device. +The `configuration.dsc.yaml` file will also enable [Developer Mode](https://learn.microsoft.com/windows/apps/get-started/developer-mode-features-and-debugging) on your device. ## How to use the WinGet Configuration File The following two options are available for running a WinGet Configuration file on your device. diff --git a/docs/sampleConfigurations/Templates/Introduction/C#/configuration.dsc.yaml b/docs/sampleConfigurations/Templates/Introduction/C#/configuration.dsc.yaml index 00094e3d28..2f2e74114c 100644 --- a/docs/sampleConfigurations/Templates/Introduction/C#/configuration.dsc.yaml +++ b/docs/sampleConfigurations/Templates/Introduction/C#/configuration.dsc.yaml @@ -2,7 +2,7 @@ ########################################################################################################## # This configuration will install the tools necessary to get started with C# development on Windows # -# Reference: https://learn.microsoft.com/en-us/visualstudio/get-started/csharp/tutorial-console # +# Reference: https://learn.microsoft.com/visualstudio/get-started/csharp/tutorial-console # # # # This will: # # * Enable Developer Mode # diff --git a/docs/sampleConfigurations/Templates/Introduction/C++/README.md b/docs/sampleConfigurations/Templates/Introduction/C++/README.md index f65a4a8da4..a643d69e1b 100644 --- a/docs/sampleConfigurations/Templates/Introduction/C++/README.md +++ b/docs/sampleConfigurations/Templates/Introduction/C++/README.md @@ -1,12 +1,12 @@ ## Understanding WinGet Configuration Files -This folder contains a [Windows Package Manager](https://learn.microsoft.com/en-us/windows/package-manager/winget/) (WinGet) [Configuration File](https://learn.microsoft.com/en-us/windows/package-manager/configuration/) (*configuration.dsc.yaml*) that will work with the WinGet command line interface (`winget configure --file [path: configuration.dsc.yaml]`) or can be run using [Microsoft Dev Home](https://learn.microsoft.com/en-us/windows/dev-home/) Device Configuration. +This folder contains a [Windows Package Manager](https://learn.microsoft.com/windows/package-manager/winget/) (WinGet) [Configuration File](https://learn.microsoft.com/windows/package-manager/configuration/) (*configuration.dsc.yaml*) that will work with the WinGet command line interface (`winget configure --file [path: configuration.dsc.yaml]`) or can be run using [Microsoft Dev Home](https://learn.microsoft.com/windows/dev-home/) Device Configuration. When run, the `configuration.dsc.yaml` file will install the following list of applications: * Microsoft Visual Studio Community 2022 * Required Visual Studio Workloads (NativeDesktop, Universal) * GitHub Desktop -The `configuration.dsc.yaml` file will also enable [Developer Mode](https://learn.microsoft.com/en-us/windows/apps/get-started/developer-mode-features-and-debugging) on your device. +The `configuration.dsc.yaml` file will also enable [Developer Mode](https://learn.microsoft.com/windows/apps/get-started/developer-mode-features-and-debugging) on your device. ## How to use the WinGet Configuration File The following two options are available for running a WinGet Configuration file on your device. diff --git a/docs/sampleConfigurations/Templates/Introduction/C++/configuration.dsc.yaml b/docs/sampleConfigurations/Templates/Introduction/C++/configuration.dsc.yaml index f22a0ae98f..62943701e9 100644 --- a/docs/sampleConfigurations/Templates/Introduction/C++/configuration.dsc.yaml +++ b/docs/sampleConfigurations/Templates/Introduction/C++/configuration.dsc.yaml @@ -2,7 +2,7 @@ ########################################################################################################## # This configuration will install the tools necessary to get started with C++ development on Windows # -# Reference: https://learn.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-170 # +# Reference: https://learn.microsoft.com/cpp/build/vscpp-step-0-installation?view=msvc-170 # # # # This will: # # * Enable Developer Mode # diff --git a/docs/sampleConfigurations/Templates/Introduction/JavaScript.NodeJS/README.md b/docs/sampleConfigurations/Templates/Introduction/JavaScript.NodeJS/README.md index 6e9d897571..cc0dea182d 100644 --- a/docs/sampleConfigurations/Templates/Introduction/JavaScript.NodeJS/README.md +++ b/docs/sampleConfigurations/Templates/Introduction/JavaScript.NodeJS/README.md @@ -7,7 +7,7 @@ When run, the `configuration.dsc.yaml` file will install the following list of a * GitHub Desktop -The `configuration.dsc.yaml` file will also enable [Developer Mode](https://learn.microsoft.com/en-us/windows/apps/get-started/developer-mode-features-and-debugging) on your device. +The `configuration.dsc.yaml` file will also enable [Developer Mode](https://learn.microsoft.com/windows/apps/get-started/developer-mode-features-and-debugging) on your device. ## How to use the WinGet Configuration File diff --git a/docs/sampleConfigurations/Templates/Introduction/JavaScript.NodeJS/configuration.dsc.yaml b/docs/sampleConfigurations/Templates/Introduction/JavaScript.NodeJS/configuration.dsc.yaml index c58bb2f066..660d9b8ec4 100644 --- a/docs/sampleConfigurations/Templates/Introduction/JavaScript.NodeJS/configuration.dsc.yaml +++ b/docs/sampleConfigurations/Templates/Introduction/JavaScript.NodeJS/configuration.dsc.yaml @@ -2,7 +2,7 @@ ########################################################################################################## # This configuration will install the tools necessary to get started with NodeJS development on Windows # -# Reference: https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-windows # +# Reference: https://learn.microsoft.com/windows/dev-environment/javascript/nodejs-on-windows # # # # This will: # # * Enable Developer Mode # diff --git a/docs/sampleConfigurations/Templates/Introduction/PowerShell/README.md b/docs/sampleConfigurations/Templates/Introduction/PowerShell/README.md index baa22881a9..522711c667 100644 --- a/docs/sampleConfigurations/Templates/Introduction/PowerShell/README.md +++ b/docs/sampleConfigurations/Templates/Introduction/PowerShell/README.md @@ -1,5 +1,5 @@ ## Understanding WinGet Configuration Files -This folder contains a [Windows Package Manager](https://learn.microsoft.com/en-us/windows/package-manager/winget/) (WinGet) [Configuration File](https://learn.microsoft.com/en-us/windows/package-manager/configuration/) (*configuration.dsc.yaml*) that will work with the WinGet command line interface (`winget configure --file [path: configuration.dsc.yaml]`) or can be run using [Microsoft Dev Home](https://learn.microsoft.com/en-us/windows/dev-home/) Device Configuration. +This folder contains a [Windows Package Manager](https://learn.microsoft.com/windows/package-manager/winget/) (WinGet) [Configuration File](https://learn.microsoft.com/windows/package-manager/configuration/) (*configuration.dsc.yaml*) that will work with the WinGet command line interface (`winget configure --file [path: configuration.dsc.yaml]`) or can be run using [Microsoft Dev Home](https://learn.microsoft.com/windows/dev-home/) Device Configuration. When run, the `configuration.dsc.yaml` file will install the following list of applications: * Microsoft Visual Studio Code diff --git a/docs/sampleConfigurations/Templates/Introduction/Python3.12/README.md b/docs/sampleConfigurations/Templates/Introduction/Python3.12/README.md index 361b2ea0d9..df711a8bd6 100644 --- a/docs/sampleConfigurations/Templates/Introduction/Python3.12/README.md +++ b/docs/sampleConfigurations/Templates/Introduction/Python3.12/README.md @@ -1,5 +1,5 @@ ## Understanding WinGet Configuration Files -This folder contains a [Windows Package Manager](https://learn.microsoft.com/en-us/windows/package-manager/winget/) (WinGet) [Configuration File](https://learn.microsoft.com/en-us/windows/package-manager/configuration/) (*configuration.dsc.yaml*) that will work with the WinGet command line interface (`winget configure --file [path: configuration.dsc.yaml]`) or can be run using [Microsoft Dev Home](https://learn.microsoft.com/en-us/windows/dev-home/) Device Configuration. +This folder contains a [Windows Package Manager](https://learn.microsoft.com/windows/package-manager/winget/) (WinGet) [Configuration File](https://learn.microsoft.com/windows/package-manager/configuration/) (*configuration.dsc.yaml*) that will work with the WinGet command line interface (`winget configure --file [path: configuration.dsc.yaml]`) or can be run using [Microsoft Dev Home](https://learn.microsoft.com/windows/dev-home/) Device Configuration. When run, the `configuration.dsc.yaml` file will install the following list of applications: * Microsoft Visual Studio Community 2022 @@ -7,7 +7,7 @@ When run, the `configuration.dsc.yaml` file will install the following list of a * GitHub Desktop * Python 3.12 -The `configuration.dsc.yaml` file will also enable [Developer Mode](https://learn.microsoft.com/en-us/windows/apps/get-started/developer-mode-features-and-debugging) on your device. +The `configuration.dsc.yaml` file will also enable [Developer Mode](https://learn.microsoft.com/windows/apps/get-started/developer-mode-features-and-debugging) on your device. ## How to use the WinGet Configuration File The following two options are available for running a WinGet Configuration file on your device. diff --git a/docs/sampleConfigurations/Templates/Introduction/Python3.12/configuration.dsc.yaml b/docs/sampleConfigurations/Templates/Introduction/Python3.12/configuration.dsc.yaml index a24bfc53f8..3d9dbf1d31 100644 --- a/docs/sampleConfigurations/Templates/Introduction/Python3.12/configuration.dsc.yaml +++ b/docs/sampleConfigurations/Templates/Introduction/Python3.12/configuration.dsc.yaml @@ -2,7 +2,7 @@ ########################################################################################################## # This configuration will install the tools necessary to get started with Python development on Windows # -# Reference: https://learn.microsoft.com/en-us/windows/python/beginners # +# Reference: https://learn.microsoft.com/windows/python/beginners # # # # This will: # # * Enable Developer Mode # diff --git a/docs/sampleConfigurations/Templates/Introduction/README.md b/docs/sampleConfigurations/Templates/Introduction/README.md index c7b7cff19b..f7b364226b 100644 --- a/docs/sampleConfigurations/Templates/Introduction/README.md +++ b/docs/sampleConfigurations/Templates/Introduction/README.md @@ -1,4 +1,4 @@ -This directory contains different [Windows Package Manager](https://learn.microsoft.com/en-us/windows/package-manager/winget/) (WinGet) [Configuration files](https://learn.microsoft.com/en-us/windows/package-manager/configuration/) that will be used for setting up your device for a specific software development language. These files are designed specifically for providing an introduction to software development, creating the default *Hello World* project, without having to focus on understanding the complexities of what needs to be installed, and how should it be configured. +This directory contains different [Windows Package Manager](https://learn.microsoft.com/windows/package-manager/winget/) (WinGet) [Configuration files](https://learn.microsoft.com/windows/package-manager/configuration/) that will be used for setting up your device for a specific software development language. These files are designed specifically for providing an introduction to software development, creating the default *Hello World* project, without having to focus on understanding the complexities of what needs to be installed, and how should it be configured. ## Language specific folders (Naming Standard) Each folder in this folder will be labeled with the name of the Software Development language it is associated with. If the language is inclusive of another language, it'll be seperated by a decimal. If the language contains a version specific release that needs to be accounted for, then the version will be considered as the language.