Skip to content

Commit 881da1a

Browse files
michael-hawkerArlodotexe
michael-hawker
authored and
Arlodotexe
committed
Move project template from /template/ProjectTemplate to /common/ProjectTemplate
1 parent d570dba commit 881da1a

34 files changed

Lines changed: 1204 additions & 1 deletion

‎CommunityToolkit.Tooling.SampleGen/ToolkitSampleMetadataGenerator.Documentation.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -148,7 +148,7 @@ private ImmutableArray<ToolkitFrontMatter> GatherDocumentFrontMatter(SourceProdu
148148
}
149149

150150
// Get the filepath we need to be able to load the markdown file in sample app.
151-
var filepath = file.Path.Split(new string[] { @"\components\", "/components/", @"\template\", "/template/" }, StringSplitOptions.RemoveEmptyEntries).LastOrDefault();
151+
var filepath = file.Path.Split(new string[] { @"\components\", "/components/", @"\common\", "/common/" }, StringSplitOptions.RemoveEmptyEntries).LastOrDefault();
152152

153153
// Look for sample id tags
154154
var matches = MarkdownRegexSampleTag.Matches(content);

‎ProjectTemplate/.template.config/ide.host.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"unsupportedHosts": [
3+
{
4+
"id": "vs"
5+
}
6+
]
7+
}

‎ProjectTemplate/.template.config/template.json‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
{
2+
"$schema": "https://json.schemastore.org/template",
3+
"author": "Microsoft",
4+
"classifications": [
5+
"Windows",
6+
"Community",
7+
"Toolkit",
8+
"Labs"
9+
],
10+
"name": "Community Toolkit Labs Experiment",
11+
"identity": "CommunityToolkit.Labs.ProjectTemplate",
12+
"shortName": "labexp",
13+
"tags": {
14+
"language": "C#",
15+
"type": "solution"
16+
},
17+
"sourceName": "ProjectTemplate",
18+
"preferNameDirectory": true,
19+
"sources": [
20+
{
21+
"source": "./",
22+
"target": "./",
23+
24+
"exclude": [
25+
"README.md",
26+
"**/[Bb]in/**",
27+
"**/[Oo]bj/**",
28+
".template.config/**/*"
29+
]
30+
}
31+
],
32+
"guids": [
33+
"A17E5FCF-1282-4567-A5BC-811F2F45DD7E",
34+
"2AB4591A-6877-487A-9733-0F06771832FF",
35+
"E25BF6D0-24D6-459C-A180-1E9405D59F87",
36+
"507C24FC-DD1C-4B91-BB6F-4A4CFB30A252",
37+
"ACD20BEE-45EF-4CAB-BA06-40F38A0C98EA",
38+
"7F03DDE8-FC53-451D-B0A4-E852EC44C0E9",
39+
"19AC7A6A-B001-45AA-ACBE-0536F688DB74",
40+
"FE390707-A244-460A-BC1C-5559038A1975",
41+
"7134BD2E-0A74-4345-868A-E425FC452A89",
42+
"FC4ACA4C-2390-44E2-B85C-B7763D87C6AB",
43+
"6926A425-E734-4B73-A479-78D4773F7FDD",
44+
"956F45AA-3810-48E9-8795-9051BBCC5C09",
45+
"D4DCFA4B-63B3-4D93-8C91-FBEE3B92E5A0",
46+
"E648080E-263D-4920-9B3D-2F6BF541586C",
47+
"ED318A01-D129-4F06-A9EB-8D911000E243"
48+
],
49+
"symbols": {
50+
"copyrightYear": {
51+
"type": "generated",
52+
"generator": "now",
53+
"replaces": "CUR_YEAR",
54+
"parameters": {
55+
"format": "yyyy"
56+
}
57+
},
58+
"HttpPortGenerated": {
59+
"type": "generated",
60+
"generator": "port",
61+
"replaces": "52475",
62+
"parameters": {
63+
"low": 50000,
64+
"high": 59999
65+
}
66+
},
67+
"HttpsPortGenerated": {
68+
"type": "generated",
69+
"generator": "port",
70+
"replaces": "44386",
71+
"parameters": {
72+
"low": 44300,
73+
"high": 44399
74+
}
75+
}
76+
}
77+
}

‎ProjectTemplate/OpenSolution.bat‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
@ECHO OFF
2+
3+
powershell ..\..\common\ProjectHeads\GenerateSingleSampleHeads.ps1 -componentPath %CD% %*

‎ProjectTemplate/README.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Windows Community Toolkit Labs - Experiment project template
2+
3+
This directory includes the template for creating new labs experiments.
4+
5+
## dotnet new
6+
7+
To use the template to create a new experiment, open a command prompt in the **root directory** and run the following commands:
8+
9+
```ascii
10+
dotnet new --install .\common\ProjectTemplate\
11+
12+
cd components
13+
14+
dotnet new labexp -n MyExperimentNameHere
15+
```
16+
17+
This creates a new experiment called "MyExperimentNameHere".
18+
You can now open `./components/MyExperimentNameHere/OpenSolution.bat` to start your experiment.
19+
20+
### Inside the generated solution
21+
22+
The solution includes many projects but is not as complicated as you might first think.
23+
24+
#### Things you can ignore
25+
26+
The `Labs Dependencies` folder can be ignored. The projects it contains are referenced in other projects and you should not change anything here.
27+
28+
The `Platforms` folder contains projects that host your sample(s) on different platforms. Run any of these projects to see your sample running inside a UWP, WASM, or WinAppSdk/WinUI3 app. Again, you shouldn't modify anything in these projects.
29+
30+
The `Tests` folder contains projects used to run the tests on different platforms UWP or WinAppSDK. Again, you shouldn't modify anything in these projects. Details of where to create tests for the code in the experiment are below.
31+
32+
#### Where to add your code
33+
34+
The main code of your experiment will go in the project `CommunityToolkit.WinUI.Controls.MyExperimentNameHere`. When an experiment is merged into Labs, this code will be bundled automatically in a NuGet package and pushed to the Labs DevOps feed. This will let others try out your experiment and provide feedback to further your experiment.
35+
You will find an empty class in `MyExperimentNameHere.cs` that you can use as your starting point or one of the templated variants. You can find more info in the `MyExperimentNameHere.md` file in the sample project.
36+
37+
The project `MyExperimentNameHere.Sample`is where you can put code that will allow you to demonstrate and exercise the experiment. In this project you'll find a sample page that includes an example of how to use settings and properties that can be controlled within the sample app. This folder also contains a **markdown** file that contains the documentation for the experiment and how to use it.
38+
39+
You can add additional markdown files as desired, each one will create a new page in the aggregated sample app. Generally you'll want to have one page per component your experiment is creating. A page can have multiple samples embedded in it to showcase different scenarios. Try to keep examples light-weight and showcase singular elements of a component in different ways. If you have a complex end-to-end example, consider giving it its own page to break-down how the example works and showcase the singular complex sample.
40+
41+
Tests for the code in the experiment go in the `MyExperimentNameHere.Tests` project. This is a shared project that is referenced by the other test projects. This makes it easy to check that the experiment's code works in more than one place. There's an example test inside the `ExampleMyExperimentNameHereTestClass.cs` file
42+
43+
### If things go wrong
44+
45+
Hopefully, you'll have no problems creating your experiment. However, here are details of how to address some of the things that might go wrong.
46+
47+
#### Missing components or workloads
48+
49+
Visual Studio will prompt if any required components or workloads are missing. Make sure all these are installed before continuing.
50+
51+
#### Creating an experiment in the wrong place
52+
53+
The generated solution and some of the projects it contains rely on relative paths that assume the experiment is created in the `components` directory. If the experiment is created elsewhere, the error message "One or more projects in the solution were not loaded correctly." will be shown when opening the solution. Deleting the incorrect solution and recreating in the correct location is the most reliable way to address this.
54+
55+
#### Long Paths
56+
57+
Labs requires long paths to be enabled. You'll want to modify the `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem\LongPathsEnabled` registry key to be a `1` and well as run the following command from an _elevated_ command prompt:
58+
59+
```dos
60+
> git config --system core.longpaths true
61+
```
62+
63+
This may require a reboot.
64+
65+
#### Updating NuGet Package
66+
67+
Packages are manually versioned right now, [see this issue here](https://github.com/CommunityToolkit/Labs-Windows/issues/133). In order to update your NuGet package, update the `<Version>` tag in your library's `CommunityToolkit.WinUI.Controls.MyExperimentNameHere.csproj` file.
68+
69+
#### WebAssembly Sample Project
70+
71+
Sometimes it can be tricky to run the WASM sample project head under Visual Studio with the default IIS run configuration. Use the drop-down within the run button itself to instead select the `ExperimentName.Wasm` configuration over `IIS Express`.
72+
73+
#### Uno Templates
74+
75+
It can be helpful to install the [Uno Platform Templates](https://marketplace.visualstudio.com/items?itemName=unoplatform.uno-platform-addin-2022) in order to use their templates when creating new Pages in Sample and Test projects.
76+
77+
For instance, you never want to add a 'Content Page' or use the other Xamarin based templates, use UWP, WinUI 3/WinAppSDK, or (ideally) the Uno based item templates when adding new XAML pages/dictionaries to projects.
78+
79+
#### Sample Page
80+
81+
If when adding a new page to the sample project you run into errors, try resetting the csproj file, it's setup to automatically include all XAML files.
82+
83+
#### Windows.UI.Xaml.Controls (WUXC) vs. Microsoft.UI.Xaml.Controls (MUXC) w/ WinUI 2 vs. WinUI 3
84+
85+
If you are referring to a control from the system like `TextBlock`, the build system will automatically pick the system one on UWP or the WinUI 3 one in the Windows App SDK.
86+
87+
However, if you need to refer to a component that was part of the WinUI 2 library like `NavigationView` or `ItemsRepeater`, then preface your C# code type with `MUXC.` to clarify you are referring to the WinUI 2 or WinUI 3 versions of the components. In XAML this is done automatically as the namespace is the same (and it is effectively ignored in the WinUI 3 case).
88+
89+
#### DEP0600 error (WinAppSDK)
90+
91+
Your experiment name is probably too long (max 32 characters), use a shorter more concise name when generating your template. See [this issue here](https://github.com/microsoft/microsoft-ui-xaml/issues/7059).

‎ProjectTemplate/samples/Dependencies.props‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
<!--
2+
WinUI 2 under UWP uses TargetFramework uap10.0.*
3+
WinUI 3 under WinAppSdk uses TargetFramework net6.0-windows10.*
4+
However, under Uno-powered platforms, both WinUI 2 and 3 can share the same TargetFramework.
5+
6+
MSBuild doesn't play nicely with this out of the box, so we've made it easy for you.
7+
8+
For .NET Standard packages, you can use the Nuget Package Manager in Visual Studio.
9+
For UWP / WinAppSDK / Uno packages, place the package references here.
10+
-->
11+
<Project>
12+
<!-- WinUI 2 / UWP -->
13+
<ItemGroup Condition="'$(IsUwp)' == 'true'">
14+
<!-- <PackageReference Include="Microsoft.Toolkit.Uwp.UI.Controls.Primitives" Version="7.1.2"/> -->
15+
</ItemGroup>
16+
17+
<!-- WinUI 2 / Uno -->
18+
<ItemGroup Condition="'$(IsUno)' == 'true' AND '$(WinUIMajorVersion)' == '2'">
19+
<!-- <PackageReference Include="Uno.Microsoft.Toolkit.Uwp.UI.Controls.Primitives" Version="7.1.11"/> -->
20+
</ItemGroup>
21+
22+
<!-- WinUI 3 / WinAppSdk -->
23+
<ItemGroup Condition="'$(IsWinAppSdk)' == 'true'">
24+
<!-- <PackageReference Include="CommunityToolkit.WinUI.UI.Controls.Primitives" Version="7.1.2"/> -->
25+
</ItemGroup>
26+
27+
<!-- WinUI 3 / Uno -->
28+
<ItemGroup Condition="'$(IsUno)' == 'true' AND '$(WinUIMajorVersion)' == '3'">
29+
<!-- <PackageReference Include="Uno.CommunityToolkit.WinUI.UI.Controls.Primitives" Version="7.1.100-dev.15.g12261e2626"/> -->
30+
</ItemGroup>
31+
</Project>

‎ProjectTemplate/samples/ProjectTemplate.Samples.csproj‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
<Project Sdk="MSBuild.Sdk.Extras/3.0.23">
2+
<PropertyGroup>
3+
<ToolkitComponentName>ProjectTemplate</ToolkitComponentName>
4+
</PropertyGroup>
5+
6+
<!-- Sets this up as a toolkit component's sample project -->
7+
<Import Project="$(RepositoryDirectory)common\ToolkitComponent.SampleProject.props" />
8+
</Project>

‎ProjectTemplate/samples/ProjectTemplate.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
title: ProjectTemplate
3+
author: githubaccount
4+
description: TODO: Your experiment's description here
5+
keywords: ProjectTemplate, Control, Layout
6+
dev_langs:
7+
- csharp
8+
category: Controls
9+
subcategory: Layout
10+
discussion-id: 0
11+
issue-id: 0
12+
---
13+
14+
<!-- To know about all the available Markdown syntax, Check out https://docs.microsoft.com/contribute/markdown-reference -->
15+
<!-- Ensure you remove all comments before submission, to ensure that there are no formatting issues when displaying this page. -->
16+
<!-- It is recommended to check how the Documentation will look in the sample app, before Merging a PR -->
17+
<!-- **Note:** All links to other docs.microsoft.com pages should be relative without locale, i.e. for the one above would be /contribute/markdown-reference -->
18+
<!-- Included images should be optimized for size and not include any Intellectual Property references. -->
19+
20+
<!-- Be sure to update the discussion/issue numbers above with your Labs discussion/issue id numbers in order for UI links to them from the sample app to work. -->
21+
22+
# ProjectTemplate
23+
24+
TODO: Fill in information about this experiment and how to get started here...
25+
26+
## Custom Control
27+
28+
You can inherit from an existing component as well, like `Panel`, this example shows a control without a
29+
XAML Style that will be more light-weight to consume by an app developer:
30+
31+
> [!Sample ProjectTemplateCustomSample]
32+
33+
## Templated Controls
34+
35+
The Toolkit is built with templated controls. This provides developers a flexible way to restyle components
36+
easily while still inheriting the general functionality a control provides. The examples below show
37+
how a component can use a default style and then get overridden by the end developer.
38+
39+
TODO: Two types of templated control building methods are shown. Delete these if you're building a custom component.
40+
Otherwise, pick one method for your component and delete the files related to the unchosen `_ClassicBinding` or `_xBind`
41+
classes (and the custom non-suffixed one as well). Then, rename your component to just be your component name.
42+
43+
The `_ClassicBinding` class shows the traditional method used to develop components with best practices.
44+
45+
### Implict style
46+
47+
> [!SAMPLE ProjectTemplateTemplatedSample]
48+
49+
### Custom style
50+
51+
> [!SAMPLE ProjectTemplateTemplatedStyleCustomSample]
52+
53+
## Templated Controls with x:Bind
54+
55+
This is an _experimental_ new way to define components which allows for the use of x:Bind within the style.
56+
57+
### Implict style
58+
59+
> [!SAMPLE ProjectTemplateXbindBackedSample]
60+
61+
### Custom style
62+
63+
> [!SAMPLE ProjectTemplateXbindBackedStyleCustomSample]
64+

‎ProjectTemplate/samples/ProjectTemplateCustomSample.xaml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
<!-- Licensed to the .NET Foundation under one or more agreements. The .NET Foundation licenses this file to you under the MIT license. See the LICENSE file in the project root for more information. -->
2+
<Page x:Class="ProjectTemplateExperiment.Samples.ProjectTemplateCustomSample"
3+
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
4+
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
5+
xmlns:controls="using:CommunityToolkit.WinUI.Controls"
6+
xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
7+
xmlns:local="using:ProjectTemplateExperiment.Samples"
8+
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
9+
mc:Ignorable="d">
10+
11+
<StackPanel Spacing="16">
12+
<TextBlock Style="{StaticResource BodyStrongTextBlockStyle}"
13+
Text="{x:Bind TitleText, Mode=OneWay}" />
14+
<StackPanel Spacing="16">
15+
<controls:ProjectTemplate Orientation="{x:Bind local:ProjectTemplateCustomSample.ConvertStringToOrientation(LayoutOrientation), Mode=OneWay}">
16+
<TextBlock Text="1" />
17+
<TextBlock Text="2" />
18+
<TextBlock Text="3" />
19+
<TextBlock Text="4" />
20+
<TextBlock Text="5" />
21+
<TextBlock Text="6" />
22+
</controls:ProjectTemplate>
23+
</StackPanel>
24+
</StackPanel>
25+
</Page>

‎ProjectTemplate/samples/ProjectTemplateCustomSample.xaml.cs‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
// Licensed to the .NET Foundation under one or more agreements.
2+
// The .NET Foundation licenses this file to you under the MIT license.
3+
// See the LICENSE file in the project root for more information.
4+
5+
using CommunityToolkit.WinUI.Controls;
6+
7+
namespace ProjectTemplateExperiment.Samples;
8+
9+
/// <summary>
10+
/// An example sample page of a custom control inheriting from Panel.
11+
/// </summary>
12+
[ToolkitSampleTextOption("TitleText", "This is a title", Title = "Input the text")]
13+
[ToolkitSampleMultiChoiceOption("LayoutOrientation", "Horizontal", "Vertical", Title = "Orientation")]
14+
15+
[ToolkitSample(id: nameof(ProjectTemplateCustomSample), "Custom control", description: $"A sample for showing how to create and use a {nameof(ProjectTemplate)} custom control.")]
16+
public sealed partial class ProjectTemplateCustomSample : Page
17+
{
18+
public ProjectTemplateCustomSample()
19+
{
20+
this.InitializeComponent();
21+
}
22+
23+
// TODO: See https://github.com/CommunityToolkit/Labs-Windows/issues/149
24+
public static Orientation ConvertStringToOrientation(string orientation) => orientation switch
25+
{
26+
"Vertical" => Orientation.Vertical,
27+
"Horizontal" => Orientation.Horizontal,
28+
_ => throw new System.NotImplementedException(),
29+
};
30+
}

0 commit comments

Comments
 (0)