Update file-based app skill to mention features from 10.0.300

.github/CODEOWNERS

@@ -10,8 +10,8 @@
 /tests/dotnet-msbuild/ @ViktorHofer @JanKrivanek @dotnet/skills-msbuild-reviewers
 
 # dotnet (common everyday C#/.NET)
-/plugins/dotnet/skills/csharp-scripts/ @dotnet/roslyn @dotnet/skills-csharp-language-reviewers
-/tests/dotnet/csharp-scripts/ @dotnet/roslyn @dotnet/skills-csharp-language-reviewers
+/plugins/dotnet/skills/csharp-scripts/ @dotnet/run-file @dotnet/skills-csharp-language-reviewers
+/tests/dotnet/csharp-scripts/ @dotnet/run-file @dotnet/skills-csharp-language-reviewers
 
 /plugins/dotnet/lsp.json @dotnet/roslyn-ide @dotnet/skills-csharp-language-reviewers
 

plugins/dotnet/skills/csharp-scripts/SKILL.md

@@ -1,41 +1,42 @@
 ---
 name: csharp-scripts
-description: Run single-file C# programs as scripts (file-based apps) for quick experimentation, prototyping, and concept testing. Use when the user wants to write and execute a small C# program without creating a full project.
+description: "Run file-based C# apps with the .NET CLI for quick experimentation, prototyping, and small utilities without creating a project. Use for one-file apps or small multi-file apps composed with `#:include`/`#:exclude` or linked with `#:ref`. Do not use when the user needs a full project, solution integration, or project references in an existing app."
 license: MIT
 ---
 
-# C# Scripts
+# File-Based C# Apps
 
 ## When to Use
 
-- Testing a C# concept, API, or language feature with a quick one-file program
+- Testing a C# concept, API, or language feature with a quick file-based app
 - Prototyping logic before integrating it into a larger project
+- Building a small utility from one entry-point file and a few helper `.cs` files
 
 ## When Not to Use
 
-- The user needs a full project with multiple files or project references
+- The user needs a full project, solution integration, or project references in an existing app
 - The user is working inside an existing .NET solution and wants to add code there
-- The program is too large or complex for a single file
+- The app is large enough that project structure, build customization, tests, or publish configuration should live in a `.csproj`
 
 ## Inputs
 
 | Input | Required | Description |
 |-------|----------|-------------|
-| C# code or intent | Yes | The code to run, or a description of what the script should do |
+| C# code or intent | Yes | The code to run, or a description of what the file-based app should do |
 
 ## Workflow
 
 ### Step 1: Check the .NET SDK version
 
 Run `dotnet --version` to verify the SDK is installed and note the major version number. File-based apps require .NET 10 or later. If the version is below 10, follow the [fallback for older SDKs](#fallback-for-net-9-and-earlier) instead.
 
-### Step 2: Write the script file
+### Step 2: Write the app file
 
-Create a single `.cs` file using top-level statements. Place it outside any existing project directory to avoid conflicts with `.csproj` files.
+Create an entry-point `.cs` file using top-level statements. Place it outside any existing project directory to avoid conflicts with `.csproj` files.
 
 ```csharp
 // hello.cs
-Console.WriteLine("Hello from a C# script!");
+Console.WriteLine("Hello from a file-based app!");
 
 var numbers = new[] { 1, 2, 3, 4, 5 };
 Console.WriteLine($"Sum: {numbers.Sum()}");
@@ -47,7 +48,7 @@ Guidelines:
 - Place `using` directives at the top of the file (after the `#!` line and any `#:` directives if present)
 - Place type declarations (classes, records, enums) after all top-level statements
 
-### Step 3: Run the script
+### Step 3: Run the app
 
 ```bash
 dotnet hello.cs
@@ -65,7 +66,7 @@ Place directives at the top of the file (immediately after an optional shebang l
 
 #### `#:package` — NuGet package references
 
-Always specify a version:
+Specify a version unless the app intentionally uses central package management. Use `@*` when the latest available package is acceptable (or `@*-*` for pre-release):
 
 ```csharp
 #:package Humanizer@2.14.1
@@ -109,6 +110,26 @@ Reference another project by relative path:
 #:project ../MyLibrary/MyLibrary.csproj
 ```
 
+#### `#:ref` — File-based app references
+
+Reference another `.cs` file as a separate file-based app project when it should compile into a separate assembly instead of being included in the same compilation. Use `#:include` for ordinary helper files that should share the same assembly as the entry point; use `#:ref` when you want project-reference-like boundaries.
+
+```csharp
+#:property ExperimentalFileBasedProgramEnableRefDirective=true
+#:ref ../Shared/Formatter.cs
+
+Console.WriteLine(Formatter.Title("hello world"));
+```
+
+Guidelines:
+
+- The referenced file is compiled as its own virtual project and added as a project reference.
+- If the referenced file is a library without top-level statements, put `#:property OutputType=Library` in that referenced file.
+- Members that must be consumed by the referencing app should be public; internal members are not visible across the assembly boundary.
+- `#:ref` is transitive: a referenced file can contain its own `#:ref` and other `#:` directives.
+- Relative paths are resolved relative to the file containing the directive.
+- Some SDK builds require `#:property ExperimentalFileBasedProgramEnableRefDirective=true`; remove that property if the SDK accepts `#:ref` without it.
+
 #### `#:sdk` — SDK selection
 
 Override the default SDK (`Microsoft.NET.Sdk`):
@@ -117,9 +138,64 @@ Override the default SDK (`Microsoft.NET.Sdk`):
 #:sdk Microsoft.NET.Sdk.Web
 ```
 
+#### `#:include` and `#:exclude` — Multi-file apps
+
+In .NET SDK 10.0.300 and later, file-based apps can include additional files in the same virtual project. Use `#:include` for helper source files and supported assets, and `#:exclude` to remove files from an include pattern or default item set.
+
+```csharp
+#!/usr/bin/env dotnet
+#:include Helpers.cs
+#:include Models/*.cs
+#:exclude Models/Generated/*.cs
+
+Console.WriteLine(Formatter.Title("hello world"));
+```
+
+Guidelines:
+
+- Treat the file passed to `dotnet` as the entry point; put top-level statements there.
+- Put declarations such as classes, records, and enums in included `.cs` files.
+- Prefer explicit globs such as `Helpers.cs` or `Models/*.cs` over broad recursive globs.
+- Paths are resolved relative to the file containing the directive.
+- Include directives from non-entry-point C# files are processed too, so a helper file can declare its own `#:package`, `#:property`, `#:sdk`, `#:project`, `#:ref`, `#:include`, or `#:exclude` directives.
+- Avoid duplicate directives across included files unless the directive kind explicitly supports duplicates; duplicate `#:package`, `#:property`, `#:sdk`, `#:include`, and `#:exclude` entries can fail.
+- When an app uses `#:include`, add a shebang (`#!/usr/bin/env dotnet`) to the entry-point file on Unix-like systems to make the entry point clear to tools. Use `LF` line endings and no BOM for shebang files.
+
+Example layout:
+
+```text
+scratch/
+    hello.cs
+    Helpers.cs
+    Models/
+        Person.cs
+```
+
+```csharp
+// hello.cs
+#:include Helpers.cs
+#:include Models/*.cs
+
+var person = new Person("Ada");
+Console.WriteLine(Formatter.Title(person.Name));
+```
+
+```csharp
+// Helpers.cs
+static class Formatter
+{
+    public static string Title(string value) => value.ToUpperInvariant();
+}
+```
+
+```csharp
+// Models/Person.cs
+record Person(string Name);
+```
+
 ### Step 5: Clean up
 
-Remove the script file when the user is done. To clear cached build artifacts:
+Remove the app files when the user is done. To clear cached build artifacts:
 
 ```bash
 dotnet clean hello.cs
@@ -173,7 +249,7 @@ partial class AppJsonContext : JsonSerializerContext;
 
 ## Converting to a project
 
-When a script outgrows a single file, convert it to a full project:
+When a file-based app outgrows this workflow, convert it to a full project:
 
 ```bash
 dotnet project convert hello.cs
@@ -184,29 +260,34 @@ dotnet project convert hello.cs
 If the .NET SDK version is below 10, file-based apps are not available. Use a temporary console project instead:
 
 ```bash
-mkdir -p /tmp/csharp-script && cd /tmp/csharp-script
+mkdir -p /tmp/csharp-file-based-app && cd /tmp/csharp-file-based-app
 dotnet new console -o . --force
 ```
 
-Replace the generated `Program.cs` with the script content and run with `dotnet run`. Add NuGet packages with `dotnet add package <name>`. Remove the directory when done.
+Replace the generated `Program.cs` with the app content and run with `dotnet run`. Add NuGet packages with `dotnet add package <name>`. Remove the directory when done.
 
 ## Validation
 
 - [ ] `dotnet --version` reports 10.0 or later (or fallback path is used)
-- [ ] The script compiles without errors (can be checked explicitly with `dotnet build <file>.cs`)
+- [ ] The app compiles without errors (can be checked explicitly with `dotnet build <file>.cs`)
 - [ ] `dotnet <file>.cs` produces the expected output
-- [ ] Script file and cached artifacts are cleaned up after the session
+- [ ] Multi-file apps include every required helper file and exclude unintended matches
+- [ ] App files and cached artifacts are cleaned up after the session
 
 ## Common Pitfalls
 
 | Pitfall | Solution |
 |---------|----------|
-| `.cs` file is inside a directory with a `.csproj` | Move the script outside the project directory, or use `dotnet run --file file.cs` |
+| `.cs` file is inside a directory with a `.csproj` | Move the app outside the project directory, or use `dotnet run --file file.cs` |
 | `#:package` without a version | Specify a version: `#:package PackageName@1.2.3` or `@*` for latest |
 | `#:property` with wrong syntax | Use `PropertyName=Value` with no spaces around `=` and no quotes: `#:property AllowUnsafeBlocks=true` |
 | Directives placed after C# code | All `#:` directives must appear immediately after an optional shebang line (if present) and before any `using` directives or other C# statements |
+| Helper file is not compiled | Add `#:include Helper.cs` or an appropriate glob to the entry-point file |
+| Shared file needs an assembly boundary | Use `#:ref Shared.cs` instead of `#:include Shared.cs`, and set `#:property OutputType=Library` in the referenced file if it has no entry point |
+| Broad include pulls in unrelated files | Prefer narrow include patterns and use `#:exclude` for generated, backup, or experimental files |
+| Duplicate directives in included files | Keep package, property, SDK, include, and exclude directives unique across the entry point and included C# files |
 | Reflection-based JSON serialization fails | Use source-generated JSON with `JsonSerializerContext` (see [Source-generated JSON](#source-generated-json)) |
-| Unexpected build behavior or version errors | File-based apps inherit `global.json`, `Directory.Build.props`, `Directory.Build.targets`, and `nuget.config` from parent directories. Move the script to an isolated directory if the inherited settings conflict |
+| Unexpected build behavior or version errors | File-based apps inherit `global.json`, `Directory.Build.props`, `Directory.Build.targets`, and `nuget.config` from parent directories. Move the app to an isolated directory if the inherited settings conflict |
 
 ## More info
 

tests/dotnet/csharp-scripts/eval.yaml

@@ -1,5 +1,5 @@
 scenarios:
-  - name: "Test a C# language feature with a script"
+  - name: "Test a C# language feature with a file-based app"
     prompt: "Does C# support creating a stackalloc'd Span of native-sized integers? Can you test it and see?"
     assertions:
       - type: "exit_success"
@@ -14,3 +14,21 @@ scenarios:
       - "Runs the test using 'dotnet <file>.cs' (file-based app) rather than creating a full project with 'dotnet new console'"
       - "The code compiles and runs, demonstrating that stackalloc with Span<nint> works"
     timeout: 120
+
+  - name: "Compose a file-based app from helper files"
+    prompt: "Can you make and run a tiny C# app that keeps the entry point separate from helper and model files, excludes a scratch file from the build, and prints a transformed person's name?"
+    assertions:
+      - type: "exit_success"
+      - type: "output_contains"
+        value: "#:include"
+      - type: "output_contains"
+        value: "#:exclude"
+      - type: "output_not_matches"
+        pattern: "dotnet new console"
+    expect_tools: ["bash"]
+    rubric:
+      - "Uses a file-based app with an entry-point .cs file rather than creating a project"
+      - "Uses #:include to compile helper/model .cs files with the entry point"
+      - "Uses #:exclude to keep an unwanted scratch/generated .cs file out of the build"
+      - "Runs the app with dotnet <file>.cs and reports the successful output"
+    timeout: 120