diff --git a/template/README.md b/template/README.md index 33933c172..22dcbdb22 100644 --- a/template/README.md +++ b/template/README.md @@ -15,4 +15,37 @@ dotnet new labexp -n MyExperimentNameHere ``` This creates a new experiment called "MyExperimentNameHere". -You can now open `./labs/MyExperimentNameHere/MyExperimentNameHere.sln` and create something amazing! +You can now open `./labs/MyExperimentNameHere/MyExperimentNameHere.sln` and start your experiment. + +### Inside the generated solution + +The solution includes many projects but is not as complicated as you might first think. + +#### Things you can ignore + +The `Labs Dependencies` folder can be ignored. The projects it contains are referenced in other projects and you should not change anything here. + +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. + +The `Tests` folder contains projects used to run the tests on different platforms. Details of where to create tests for the code in the experiment are below. + +#### Where to add your code + +The main code of your experiment will go in the project `CommunityToolkit.Labs.WinUI.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. +You will find an empty class in `MyExperimentNameHere.cs` that you can use as your starting point. + +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. + +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 + +### If things go wrong + +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. + +#### Missing components or workloads + +Visual Studio will prompt if any required components or workloads are missing. Make sure all these are installed before continuing. + +#### Creating an experiment in the wrong place + +The generated solution and some of the projects it contains rely on relative paths that assume the experiment is created in the `labs` 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. diff --git a/template/lab/.template.config/ide.host.json b/template/lab/.template.config/ide.host.json new file mode 100644 index 000000000..d58bb2b5f --- /dev/null +++ b/template/lab/.template.config/ide.host.json @@ -0,0 +1,7 @@ +{ + "unsupportedHosts": [ + { + "id": "vs" + } + ] +} diff --git a/template/lab/.template.config/template.json b/template/lab/.template.config/template.json index 46702b956..5cff3cc60 100644 --- a/template/lab/.template.config/template.json +++ b/template/lab/.template.config/template.json @@ -7,12 +7,12 @@ "Toolkit", "Labs" ], - "name": "Community Toolkit Labs Project Template", + "name": "Community Toolkit Labs Experiment", "identity": "CommunityToolkit.Labs.ProjectTemplate", "shortName": "labexp", "tags": { "language": "C#", - "type": "project" + "type": "solution" }, "sourceName": "ProjectTemplate", "preferNameDirectory": true, diff --git a/template/lab/samples/ProjectTemplate.Sample/ProjectTemplate.md b/template/lab/samples/ProjectTemplate.Sample/ProjectTemplate.md index 90fb15e61..80c19d2ca 100644 --- a/template/lab/samples/ProjectTemplate.Sample/ProjectTemplate.md +++ b/template/lab/samples/ProjectTemplate.Sample/ProjectTemplate.md @@ -17,6 +17,10 @@ subcategory: Layout # ProjectTemplate +For more information about this experiment see: +- Discussion: TODO: PASTE LINK HERE +- Issue: TODO: PASTE LINK HERE + TODO: Fill in information about this experiment and how to get started here... > [!SAMPLE ProjectTemplateFirstSamplePage] diff --git a/template/lab/src/AdditionalAssemblyInfo.cs b/template/lab/src/AdditionalAssemblyInfo.cs new file mode 100644 index 000000000..fbe06364c --- /dev/null +++ b/template/lab/src/AdditionalAssemblyInfo.cs @@ -0,0 +1,13 @@ +// 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. + +using System.Runtime.CompilerServices; + +// These `InternalsVisibleTo` calls are intended to make it easier for +// for any internal code to be testable in all the different test projects +// used with the Labs infrastructure. +[assembly: InternalsVisibleTo("ProjectTemplate.UnitTests.Uwp")] +[assembly: InternalsVisibleTo("ProjectTemplate.UnitTests.WinAppSdk")] +[assembly: InternalsVisibleTo("CommunityToolkit.Labs.UnitTests.Uwp")] +[assembly: InternalsVisibleTo("CommunityToolkit.Labs.UnitTests.WinAppSdk")] diff --git a/template/lab/src/ProjectTemplate.cs b/template/lab/src/ProjectTemplate.cs index 5ec17a8d5..be6e7c8cb 100644 --- a/template/lab/src/ProjectTemplate.cs +++ b/template/lab/src/ProjectTemplate.cs @@ -6,13 +6,23 @@ using System.Collections.Generic; using Windows.Foundation; +// TODO: remove any unneeded namespaces before creating a PR //-:cnd:noEmit #if !WINAPPSDK +using Windows.UI; +using Windows.UI.Core; using Windows.UI.Xaml; using Windows.UI.Xaml.Controls; +using Windows.UI.Xaml.Data; +using Windows.UI.Xaml.Markup; +using Windows.UI.Xaml.Media; #else +using Microsoft.UI; using Microsoft.UI.Xaml; using Microsoft.UI.Xaml.Controls; +using Microsoft.UI.Xaml.Data; +using Microsoft.UI.Xaml.Markup; +using Microsoft.UI.Xaml.Media; #endif //+:cnd:noEmit diff --git a/template/lab/tests/ProjectTemplate.Tests/ExampleProjectTemplateTestClass.cs b/template/lab/tests/ProjectTemplate.Tests/ExampleProjectTemplateTestClass.cs index 587f4d3fd..30b397846 100644 --- a/template/lab/tests/ProjectTemplate.Tests/ExampleProjectTemplateTestClass.cs +++ b/template/lab/tests/ProjectTemplate.Tests/ExampleProjectTemplateTestClass.cs @@ -6,6 +6,26 @@ using System.Collections.Generic; using System.Text; using Microsoft.VisualStudio.TestTools.UnitTesting; +using CommunityToolkit.Labs.WinUI; + +//-:cnd:noEmit +#if !WINAPPSDK +using Windows.UI; +using Windows.UI.Core; +using Windows.UI.Xaml; +using Windows.UI.Xaml.Controls; +using Windows.UI.Xaml.Data; +using Windows.UI.Xaml.Markup; +using Windows.UI.Xaml.Media; +#else +using Microsoft.UI; +using Microsoft.UI.Xaml; +using Microsoft.UI.Xaml.Controls; +using Microsoft.UI.Xaml.Data; +using Microsoft.UI.Xaml.Markup; +using Microsoft.UI.Xaml.Media; +#endif +//+:cnd:noEmit namespace ProjectTemplate.Tests { @@ -13,9 +33,10 @@ namespace ProjectTemplate.Tests public class ExampleProjectTemplateTestClass { [TestMethod] - public void Just_an_example_test() + public void SimpleExampleTest() { - Assert.AreEqual(1, 1); + var systemUnderTest = new CommunityToolkit.Labs.WinUI.ProjectTemplate(); + Assert.IsNotNull(systemUnderTest); } } }