From 640013b49c857513b25e97ab9e4158859840101c Mon Sep 17 00:00:00 2001 From: "Andy De George (adegeo)" Date: Mon, 21 Apr 2025 18:06:18 -0700 Subject: [PATCH 1/8] Initial draft of diagnostic redesign --- docs/diagnostics/ASPIRE006.md | 27 ++++++ docs/diagnostics/ASPIREACADOMAINS001.md | 64 +++++++++++++ docs/diagnostics/ASPIREAZURE001.md | 40 ++++++++ docs/diagnostics/ASPIRECOSMOSDB001.md | 57 +++++++++++ docs/diagnostics/ASPIREHOSTINGPYTHON001.md | 51 ++++++++++ docs/diagnostics/ASPIREPUBLISHERS001.md | 42 ++++++++ docs/diagnostics/overview.md | 106 +++++---------------- docs/toc.yml | 28 +++++- 8 files changed, 330 insertions(+), 85 deletions(-) create mode 100644 docs/diagnostics/ASPIRE006.md create mode 100644 docs/diagnostics/ASPIREACADOMAINS001.md create mode 100644 docs/diagnostics/ASPIREAZURE001.md create mode 100644 docs/diagnostics/ASPIRECOSMOSDB001.md create mode 100644 docs/diagnostics/ASPIREHOSTINGPYTHON001.md create mode 100644 docs/diagnostics/ASPIREPUBLISHERS001.md diff --git a/docs/diagnostics/ASPIRE006.md b/docs/diagnostics/ASPIRE006.md new file mode 100644 index 0000000000..e166bd8bfa --- /dev/null +++ b/docs/diagnostics/ASPIRE006.md @@ -0,0 +1,27 @@ +--- +title: Compiler Error ASPIRE006 +description: Learn more about compiler Error ASPIRE006. Application model items must have valid names +ms.date: 04/21/2025 +f1_keywords: + - "ASPIRE006" +helpviewer_keywords: + - "ASPIRE006" +--- + +# Compiler Error ASPIRE006 + +**Version introduced:** 8.2.2 + +> Application model items must have valid names + +This diagnostic error is reported when two or more resources share the same name. + +## Example + +The following code generates `ASPIRE006`: + + + +## To correct this Error + +Give each resource a unique name. diff --git a/docs/diagnostics/ASPIREACADOMAINS001.md b/docs/diagnostics/ASPIREACADOMAINS001.md new file mode 100644 index 0000000000..49054d005f --- /dev/null +++ b/docs/diagnostics/ASPIREACADOMAINS001.md @@ -0,0 +1,64 @@ +--- +title: Compiler Error ASPIREACADOMAINS001 +description: Learn more about compiler Error ASPIREACADOMAINS001. `ConfigureCustomDomain` is for evaluation purposes only and is subject to change or removal in future updates. +ms.date: 04/21/2025 +f1_keywords: + - "ASPIREACADOMAINS001" +helpviewer_keywords: + - "ASPIREACADOMAINS001" +--- + +# Compiler Error ASPIREACADOMAINS001 + +**Version introduced:** 9.0 + +> `ConfigureCustomDomain` is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed. + +.NET Aspire 9.0 introduces the ability to customize container app resources using any of the following extension methods: + +- `Aspire.Hosting.AzureContainerAppProjectExtensions.PublishAsAzureContainerApp` +- `Aspire.Hosting.AzureContainerAppContainerExtensions.PublishAsAzureContainerApp` +- `Aspire.Hosting.AzureContainerAppExecutableExtensions.PublishAsAzureContainerApp` + +When you use one of these methods, the Azure Developer CLI (`azd`) can no longer preserve custom domains. Instead use the `Aspire.Hosting.ContainerAppExtensions.ConfigureCustomDomain` method to configure a custom domain within the .NET Aspire app host. + +However, `app.ConfigureCustomDomain` is an experimental API and you must suppress it to use it. + +## Example + +The following code generates `ASPIREACADOMAINS001`: + +```csharp +var customDomain = builder.AddParameter("customDomain"); +var certificateName = builder.AddParameter("certificateName"); + +builder.AddProject("api") + .WithExternalHttpEndpoints() + .PublishAsAzureContainerApp((infra, app) => + { + app.ConfigureCustomDomain(customDomain, certificateName); + }); +``` + +## To correct this error + +Suppress the error with either of the following methods: + +- Set the severity of the rule in the _.editorConfig_ file. + + ```ini + [*.{cs,vb}] + dotnet_diagnostic.ASPIREACADOMAINS001.severity = none + ``` + + For more information about editor config files, see [Configuration files for code analysis rules](/dotnet/fundamentals/code-analysis/configuration-files). + +- Add the following `PropertyGroup` to your project file: + + ```xml + + $(NoWarn);ASPIREACADOMAINS001 + + ``` + +- Suppress in code with the `#pragma warning disable ASPIREACADOMAINS001` directive. diff --git a/docs/diagnostics/ASPIREAZURE001.md b/docs/diagnostics/ASPIREAZURE001.md new file mode 100644 index 0000000000..46489cf297 --- /dev/null +++ b/docs/diagnostics/ASPIREAZURE001.md @@ -0,0 +1,40 @@ +--- +title: Compiler Error ASPIREAZURE001 +description: Learn more about compiler Error ASPIREAZURE001. Publishers are for evaluation purposes only and are subject to change or removal in future updates. +ms.date: 04/21/2025 +f1_keywords: + - "ASPIREAZURE001" +helpviewer_keywords: + - "ASPIREAZURE001" +--- + +# Compiler Error ASPIREAZURE001 + +**Version introduced:** 9.2 + +> Publishers are for evaluation purposes only and are subject to change or removal in future updates. Suppress this diagnostic to proceed. + +The .NET Aspire Azure hosting integration now ships with a publisher. If you're using any of the APIs, you might see a compiler error/warning indicating that the API is experimental. This is expected behavior, as the API is still in preview and the shape of this API is expected to change in the future. + +## To correct this Error + +Suppress the Error with either of the following methods: + +- Set the severity of the rule in the _.editorConfig_ file. + + ```ini + [*.{cs,vb}] + dotnet_diagnostic.ASPIREAZURE001.severity = none + ``` + + For more information about editor config files, see [Configuration files for code analysis rules](/dotnet/fundamentals/code-analysis/configuration-files). + +- Add the following `PropertyGroup` to your project file: + + ```xml + + $(NoWarn);ASPIREAZURE001 + + ``` + +- Suppress in code with the `#pragma warning disable ASPIREAZURE001` directive. diff --git a/docs/diagnostics/ASPIRECOSMOSDB001.md b/docs/diagnostics/ASPIRECOSMOSDB001.md new file mode 100644 index 0000000000..fcd956960f --- /dev/null +++ b/docs/diagnostics/ASPIRECOSMOSDB001.md @@ -0,0 +1,57 @@ +--- +title: Compiler Error ASPIRECOSMOSDB001 +description: Learn more about compiler Error ASPIRECOSMOSDB001. `RunAsPreviewEmulator` is for evaluation purposes only and is subject to change or removal in future updates. +ms.date: 04/21/2025 +f1_keywords: + - "ASPIRECOSMOSDB001" +helpviewer_keywords: + - "ASPIRECOSMOSDB001" +--- + +# Compiler Error ASPIRECOSMOSDB001 + +**Version introduced:** 9.0 + +> `RunAsPreviewEmulator` is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed. + +-or- + +> `WithDataExplorer` is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed. + +Both `RunAsPreviewEmulator` and `WithDataExplorer` are considered experimental APIs. + +.NET Aspire provides a way to use the Cosmos DB Linux-based (preview) emulator and data explorer. These APIs are considered experimental and are expected to change in the future. + +## Example + +The following sample generates `ASPIRECOSMOSDB001`: + +```csharp +var builder = DistributedApplication.CreateBuilder(args); + +var cosmos = builder.AddAzureCosmosDB("cosmos") + .RunAsPreviewEmulator(e => e.WithDataExplorer()); +``` + +## To correct this error + +Suppress the Error with either of the following methods: + +- Set the severity of the rule in the _.editorConfig_ file. + + ```ini + [*.{cs,vb}] + dotnet_diagnostic.ASPIRECOSMOSDB001.severity = none + ``` + + For more information about editor config files, see [Configuration files for code analysis rules](/dotnet/fundamentals/code-analysis/configuration-files). + +- Add the following `PropertyGroup` to your project file: + + ```xml + + $(NoWarn);ASPIRECOSMOSDB001 + + ``` + +- Suppress in code with the `#pragma warning disable ASPIRECOSMOSDB001` directive. diff --git a/docs/diagnostics/ASPIREHOSTINGPYTHON001.md b/docs/diagnostics/ASPIREHOSTINGPYTHON001.md new file mode 100644 index 0000000000..38827f6564 --- /dev/null +++ b/docs/diagnostics/ASPIREHOSTINGPYTHON001.md @@ -0,0 +1,51 @@ +--- +title: Compiler Error ASPIREHOSTINGPYTHON001 +description: Learn more about compiler Error ASPIREHOSTINGPYTHON001. `AddPythonApp` is for evaluation purposes only and is subject to change or removal in future updates. +ms.date: 04/21/2025 +f1_keywords: + - "ASPIREHOSTINGPYTHON001" +helpviewer_keywords: + - "ASPIREHOSTINGPYTHON001" +--- + +# Compiler Error ASPIREHOSTINGPYTHON001 + +**Version introduced:** 9.0 + +> `AddPythonApp` is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed. + +.NET Aspire provides a way to add Python executables or applications to the .NET Aspire app host with the `AddPythonApp` extension. Since the shape of this API is expected to change in the future, it's experimental. + +## Example + +The following code generates `ASPIREHOSTINGPYTHON001`: + +```csharp +var pythonApp = builder.AddPythonApp("hello-python", "../hello-python", "main.py") + .WithHttpEndpoint(env: "PORT") + .WithExternalHttpEndpoints() + .WithOtlpExporter(); +``` + +## To correct this Error + +Suppress the Error with either of the following methods: + +- Set the severity of the rule in the _.editorConfig_ file. + + ```ini + [*.{cs,vb}] + dotnet_diagnostic.ASPIREHOSTINGPYTHON001.severity = none + ``` + + For more information about editor config files, see [Configuration files for code analysis rules](/dotnet/fundamentals/code-analysis/configuration-files). + +- Add the following `PropertyGroup` to your project file: + + ```xml + + $(NoWarn);ASPIREHOSTINGPYTHON001 + + ``` + +- Suppress in code with the `#pragma warning disable ASPIREHOSTINGPYTHON001` directive. diff --git a/docs/diagnostics/ASPIREPUBLISHERS001.md b/docs/diagnostics/ASPIREPUBLISHERS001.md new file mode 100644 index 0000000000..af873aba4d --- /dev/null +++ b/docs/diagnostics/ASPIREPUBLISHERS001.md @@ -0,0 +1,42 @@ +--- +title: Compiler Error ASPIREPUBLISHERS001 +description: Learn more about compiler Error ASPIREPUBLISHERS001. Publishers are for evaluation purposes only and are subject to change or removal in future updates. +ms.date: 04/21/2025 +f1_keywords: + - "ASPIREPUBLISHERS001" +helpviewer_keywords: + - "ASPIREPUBLISHERS001" +--- + +# Compiler Error ASPIREPUBLISHERS001 + +**Version introduced:** 9.2 + +> Publishers are for evaluation purposes only and are subject to change or removal in future updates. Suppress this diagnostic to proceed. + +.NET Aspire introduced the concept of _Publishers_ starting in version 9.2. Publishers play a pivotal role in the deployment process, enabling the transformation of your distributed app into deployable assets. This alleviates the intermediate step of producing the publishing [manifest](../deployment/manifest-format.md) for tools to act on, instead empowering the developer to express their intent directly in C#. + +Publishers are considered experimental and are expected to change in the future. + +## To correct this Error + +Suppress the Error with either of the following methods: + +- Set the severity of the rule in the _.editorConfig_ file. + + ```ini + [*.{cs,vb}] + dotnet_diagnostic.ASPIREPUBLISHERS001.severity = none + ``` + + For more information about editor config files, see [Configuration files for code analysis rules](/dotnet/fundamentals/code-analysis/configuration-files). + +- Add the following `PropertyGroup` to your project file: + + ```xml + + $(NoWarn);ASPIREPUBLISHERS001 + + ``` + +- Suppress in code with the `#pragma warning disable ASPIREPUBLISHERS001` directive. diff --git a/docs/diagnostics/overview.md b/docs/diagnostics/overview.md index 039a61846d..4c4ac74a41 100644 --- a/docs/diagnostics/overview.md +++ b/docs/diagnostics/overview.md @@ -3,84 +3,24 @@ title: .NET Aspire diagnostics overview description: Learn about the diagnostics tools and features available in .NET Aspire. ms.topic: overview ms.date: 04/15/2025 -ai-usage: ai-assisted --- -# .NET Aspire diagnostics overview +# .NET Aspire diagnostics list -Several APIs of .NET Aspire are decorated with the . This attribute indicates that the API is experimental and might be removed or changed in future versions of .NET Aspire. The attribute is used to identify APIs that aren't yet stable and might not be suitable for production use. +The following table lists the possible MSBuild and .NET Analyzer warnings and errors you might encounter while developing a .NET Aspire app: -## ASPIREACADOMAINS001 - - - -.NET Aspire 9.0 introduces the ability to customize container app resources using any of the following extension methods: - -- -- -- - -When you use one of these methods, the Azure Developer CLI (`azd`) can no longer preserve custom domains. Instead use the method to configure a custom domain within the .NET Aspire app host. The `ConfigureCustomDomain(...)` extension method is experimental. To suppress the compiler error/warning, use the following code: - -To suppress the `ASPIREACADOMAINS001` diagnostic, select the **Copy** button from the following diagnostic ID, and see [Suppress diagnostic](#suppress-diagnostic): - -```plaintext -ASPIREACADOMAINS001 -``` - -## ASPIREHOSTINGPYTHON001 - - - -.NET Aspire provides a way to add Python executables or applications to the .NET Aspire app host. Since the shape of this API is expected to change in the future, it's experimental (). To suppress the compiler error/warning, use the following code: - -To suppress the `ASPIREHOSTINGPYTHON001` diagnostic, select the **Copy** button from the following diagnostic ID, and see [Suppress diagnostic](#suppress-diagnostic): - -```plaintext -ASPIREAZURE001 -``` - -## ASPIRECOSMOSDB001 - - - -.NET Aspire provides a way to use the Cosmos DB Linux-based (preview) emulator. Since this emulator is in preview and the shape of this API is expected to change in the future, it's experimental (). To suppress the compiler error/warning, use the following code: - -To suppress the `ASPIRECOSMOSDB001` diagnostic, select the **Copy** button from the following diagnostic ID, and see [Suppress diagnostic](#suppress-diagnostic): - -```plaintext -ASPIRECOSMOSDB001 -``` - -## ASPIREPUBLISHERS001 - - - -.NET Aspire introduced the concept of _Publishers_ starting in version 9.2. Publishers play a pivotal role in the deployment process, enabling the transformation of your distributed app into deployable assets. This alleviates the intermediate step of producing the publishing [manifest](../deployment/manifest-format.md) for tools to act on, instead empowering the developer to express their intent directly in C#. - -Publishers are currently in preview and the APIs are experimental (). To suppress the compiler error/warning, use the following code: - -To suppress the `ASPIREPUBLISHERS001` diagnostic, select the **Copy** button from the following diagnostic ID, and see [Suppress diagnostic](#suppress-diagnostic): - -```plaintext -ASPIREPUBLISHERS001 -``` - -## ASPIREAZURE001 - - - -The .NET Aspire Azure hosting integration now ships with a publisher. If you're using any of the APIs, you might see a compiler error/warning indicating that the API is experimental. This is expected behavior, as the API is still in preview and the shape of this API is expected to change in the future. - -To suppress the `ASPIREAZURE001` diagnostic, select the **Copy** button from the following diagnostic ID, and see [Suppress diagnostic](#suppress-diagnostic): - -```plaintext -ASPIREAZURE001 -``` +| Diagnostic ID | Type | Description | +|-------------------------------------------------------|----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------| +| [`ASPIRE006`](ASPIRE006.md) | (Experimental) Error | Application model items must have valid names | +| [`ASPIREACADOMAINS001`](ASPIREACADOMAINS001.md) | (Experimental) Error | `ConfigureCustomDomain` is for evaluation purposes only and is subject to change or removal in future updates. | +| [`ASPIREAZURE001`](ASPIREAZURE001.md) | (Experimental) Error | Publishers are for evaluation purposes only and are subject to change or removal in future updates. | +| [`ASPIRECOSMOSDB001`](ASPIRECOSMOSDB001.md) | (Experimental) Error | `RunAsPreviewEmulator` is for evaluation purposes only and is subject to change or removal in future updates. | +| [`ASPIREHOSTINGPYTHON001`](ASPIREHOSTINGPYTHON001.md) | (Experimental) Error | `AddPythonApp` is for evaluation purposes only and is subject to change or removal in future updates. | +| [`ASPIREPUBLISHERS001`](ASPIREPUBLISHERS001.md) | Error | Publishers are for evaluation purposes only and are subject to change or removal in future updates. | ## Suppress diagnostic -You can suppress any diagnostic in this document using one of the following methods: +Warning and experimental error diagnostics can be suppressed in one of the following ways: - Add the at the assembly, class, method, line, etc. - Include the diagnostic ID in the `NoWarn` property of your project file. @@ -93,7 +33,7 @@ There are some common patterns for suppressing diagnostics in .NET projects. The The is ideal when you need targeted, documented suppression tied directly to a specific code element like a class or method. It shines when you’re making a deliberate exception to a rule that is valid in most other places. This attribute keeps the suppression close to the code it affects, which helps reviewers and future maintainers understand the rationale. While it's a clean solution for isolated cases, it can clutter the code if overused, and it’s not the best choice for widespread or bulk suppressions. -To suppress the `ASPIREEX007` diagnostic with the , consider the following examples: +To suppress the `ASPIREAZURE001` diagnostic with the , consider the following examples: **Assembly-level suppression:** @@ -101,7 +41,7 @@ To suppress the `ASPIREEX007` diagnostic with the - $(NoWarn);ASPIREEX007 + $(NoWarn);ASPIREAZURE001 ``` @@ -156,12 +96,12 @@ To suppress the `ASPIREEX007` diagnostic in the project file, add the following Preprocessor directives like `#pragma warning disable` offer fine-grained suppression within a specific scope, such as a method body or block of code. They're especially handy when you need a temporary suppression during refactoring, or when a rule incorrectly flags a particular line that you can't or don't want to change. The ability to tightly wrap just the affected code makes this approach powerful, but it can also make the code harder to read and maintain, especially if the directives are scattered or forgotten over time. -To suppress the `ASPIREEX007` diagnostic with preprocessor directives, consider the following examples: +To suppress the `ASPIREAZURE001` diagnostic with preprocessor directives, consider the following examples: **File-level suppression:** ```csharp -#pragma warning disable ASPIREEX007 +#pragma warning disable ASPIREAZURE001 public class ExampleClassThatConsumesTheOffendingAPI { @@ -176,9 +116,9 @@ public class ExampleClass { public void ExampleMethodThatConsumesTheOffendingAPI() { - #pragma warning disable ASPIREEX007 + #pragma warning disable ASPIREAZURE001 // Code that triggers the diagnostic - #pragma warning restore ASPIREEX007 + #pragma warning restore ASPIREAZURE001 } } ``` @@ -191,11 +131,11 @@ For more information, see [C# preprocessor directives](/dotnet/csharp/language-r Suppressing diagnostics using an _.editorconfig_ file is ideal for enforcing or adjusting analyzer behavior at scale. It allows teams to standardize severity levels (or disable rules) across an entire solution or per directory/file pattern. This method keeps suppression cleanly out of the codebase, and it works well for communicating team-wide conventions. However, it can be a bit opaque—developers need to know to look in the config file—and it doesn't offer the precision of an attribute or pragma when dealing with one-off cases. -To suppress the `ASPIREEX007` diagnostic in an _.editorconfig_ file, add the following code: +To suppress the `ASPIREAZURE001` diagnostic in an _.editorconfig_ file, add the following code: ```ini [*.cs] -dotnet_diagnostic.ASPIREEX007.severity = none +dotnet_diagnostic.ASPIREAZURE001.severity = none ``` This configuration applies to all C# files in the project. You can also scope it to specific files or directories by adjusting the section header. diff --git a/docs/toc.yml b/docs/toc.yml index 4a736a99de..7472e1e87e 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -415,8 +415,32 @@ items: items: - name: Breaking changes href: compatibility/breaking-changes.md - - name: Diagnostics overview - href: diagnostics/overview.md + - name: Diagnostics + items: + - name: Overview + href: diagnostics/overview.md + - name: Errors + items: + - name: ASPIRE006 + href: diagnostics/ASPIRE006.md + - name: By category + items: + - name: Resources + items: + - name: Items must have valid names + href: diagnostics/ASPIRE006.md + - name: Experimental + items: + - name: Azure custom domains + href: diagnostics/aspireacadomains001.md + - name: Cosmos DB preview emulator and data explorer + href: diagnostics/aspirecosmosdb001.md + - name: Hosting Python apps + href: diagnostics/aspirehostingpython001.md + - name: Publishing APIs are experimental + href: diagnostics/aspirepublishers001.md + - name: Publishing to Azure APIs are experimental + href: diagnostics/aspireazure001.md - name: .NET Aspire API reference href: /dotnet/api?view=dotnet-aspire-9.2&preserve-view=true - name: .NET Aspire FAQ From 53a4de32bc1c607e89b81487ed702ac6df4508f4 Mon Sep 17 00:00:00 2001 From: "Andy De George (adegeo)" Date: Mon, 21 Apr 2025 18:15:25 -0700 Subject: [PATCH 2/8] Minor fix; More TOC --- docs/diagnostics/ASPIRE006.md | 4 ++-- docs/diagnostics/overview.md | 2 +- docs/toc.yml | 14 ++++++++++++-- 3 files changed, 15 insertions(+), 5 deletions(-) diff --git a/docs/diagnostics/ASPIRE006.md b/docs/diagnostics/ASPIRE006.md index e166bd8bfa..c5fca6054c 100644 --- a/docs/diagnostics/ASPIRE006.md +++ b/docs/diagnostics/ASPIRE006.md @@ -1,6 +1,6 @@ --- title: Compiler Error ASPIRE006 -description: Learn more about compiler Error ASPIRE006. Application model items must have valid names +description: Learn more about compiler Error ASPIRE006. Application model items must have valid names. ms.date: 04/21/2025 f1_keywords: - "ASPIRE006" @@ -12,7 +12,7 @@ helpviewer_keywords: **Version introduced:** 8.2.2 -> Application model items must have valid names +> Application model items must have valid names. This diagnostic error is reported when two or more resources share the same name. diff --git a/docs/diagnostics/overview.md b/docs/diagnostics/overview.md index 4c4ac74a41..25a9c1ae24 100644 --- a/docs/diagnostics/overview.md +++ b/docs/diagnostics/overview.md @@ -11,7 +11,7 @@ The following table lists the possible MSBuild and .NET Analyzer warnings and er | Diagnostic ID | Type | Description | |-------------------------------------------------------|----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------| -| [`ASPIRE006`](ASPIRE006.md) | (Experimental) Error | Application model items must have valid names | +| [`ASPIRE006`](ASPIRE006.md) | (Experimental) Error | Application model items must have valid names. | | [`ASPIREACADOMAINS001`](ASPIREACADOMAINS001.md) | (Experimental) Error | `ConfigureCustomDomain` is for evaluation purposes only and is subject to change or removal in future updates. | | [`ASPIREAZURE001`](ASPIREAZURE001.md) | (Experimental) Error | Publishers are for evaluation purposes only and are subject to change or removal in future updates. | | [`ASPIRECOSMOSDB001`](ASPIRECOSMOSDB001.md) | (Experimental) Error | `RunAsPreviewEmulator` is for evaluation purposes only and is subject to change or removal in future updates. | diff --git a/docs/toc.yml b/docs/toc.yml index 7472e1e87e..7e937b2485 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -422,13 +422,23 @@ items: - name: Errors items: - name: ASPIRE006 - href: diagnostics/ASPIRE006.md + href: diagnostics/aspire006.md + - name: ASPIREACADOMAINS001 + href: diagnostics/aspireacadomains001.md + - name: ASPIRECOSMOSDB001 + href: diagnostics/aspirecosmosdb001.md + - name: ASPIREHOSTINGPYTHON001 + href: diagnostics/aspirehostingpython001.md + - name: ASPIREPUBLISHERS001 + href: diagnostics/aspirepublishers001.md + - name: ASPIREAZURE001 + href: diagnostics/aspireazure001.md - name: By category items: - name: Resources items: - name: Items must have valid names - href: diagnostics/ASPIRE006.md + href: diagnostics/aspire006.md - name: Experimental items: - name: Azure custom domains From 3b93a6ac59b2d06f758322b4ce34a8a61549a3fd Mon Sep 17 00:00:00 2001 From: "Andy De George (adegeo)" Date: Mon, 21 Apr 2025 18:16:12 -0700 Subject: [PATCH 3/8] Delete uppercase files --- docs/diagnostics/ASPIRE006.md | 27 --------- docs/diagnostics/ASPIREACADOMAINS001.md | 64 ---------------------- docs/diagnostics/ASPIREAZURE001.md | 40 -------------- docs/diagnostics/ASPIRECOSMOSDB001.md | 57 ------------------- docs/diagnostics/ASPIREHOSTINGPYTHON001.md | 51 ----------------- docs/diagnostics/ASPIREPUBLISHERS001.md | 42 -------------- 6 files changed, 281 deletions(-) delete mode 100644 docs/diagnostics/ASPIRE006.md delete mode 100644 docs/diagnostics/ASPIREACADOMAINS001.md delete mode 100644 docs/diagnostics/ASPIREAZURE001.md delete mode 100644 docs/diagnostics/ASPIRECOSMOSDB001.md delete mode 100644 docs/diagnostics/ASPIREHOSTINGPYTHON001.md delete mode 100644 docs/diagnostics/ASPIREPUBLISHERS001.md diff --git a/docs/diagnostics/ASPIRE006.md b/docs/diagnostics/ASPIRE006.md deleted file mode 100644 index c5fca6054c..0000000000 --- a/docs/diagnostics/ASPIRE006.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Compiler Error ASPIRE006 -description: Learn more about compiler Error ASPIRE006. Application model items must have valid names. -ms.date: 04/21/2025 -f1_keywords: - - "ASPIRE006" -helpviewer_keywords: - - "ASPIRE006" ---- - -# Compiler Error ASPIRE006 - -**Version introduced:** 8.2.2 - -> Application model items must have valid names. - -This diagnostic error is reported when two or more resources share the same name. - -## Example - -The following code generates `ASPIRE006`: - - - -## To correct this Error - -Give each resource a unique name. diff --git a/docs/diagnostics/ASPIREACADOMAINS001.md b/docs/diagnostics/ASPIREACADOMAINS001.md deleted file mode 100644 index 49054d005f..0000000000 --- a/docs/diagnostics/ASPIREACADOMAINS001.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Compiler Error ASPIREACADOMAINS001 -description: Learn more about compiler Error ASPIREACADOMAINS001. `ConfigureCustomDomain` is for evaluation purposes only and is subject to change or removal in future updates. -ms.date: 04/21/2025 -f1_keywords: - - "ASPIREACADOMAINS001" -helpviewer_keywords: - - "ASPIREACADOMAINS001" ---- - -# Compiler Error ASPIREACADOMAINS001 - -**Version introduced:** 9.0 - -> `ConfigureCustomDomain` is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed. - -.NET Aspire 9.0 introduces the ability to customize container app resources using any of the following extension methods: - -- `Aspire.Hosting.AzureContainerAppProjectExtensions.PublishAsAzureContainerApp` -- `Aspire.Hosting.AzureContainerAppContainerExtensions.PublishAsAzureContainerApp` -- `Aspire.Hosting.AzureContainerAppExecutableExtensions.PublishAsAzureContainerApp` - -When you use one of these methods, the Azure Developer CLI (`azd`) can no longer preserve custom domains. Instead use the `Aspire.Hosting.ContainerAppExtensions.ConfigureCustomDomain` method to configure a custom domain within the .NET Aspire app host. - -However, `app.ConfigureCustomDomain` is an experimental API and you must suppress it to use it. - -## Example - -The following code generates `ASPIREACADOMAINS001`: - -```csharp -var customDomain = builder.AddParameter("customDomain"); -var certificateName = builder.AddParameter("certificateName"); - -builder.AddProject("api") - .WithExternalHttpEndpoints() - .PublishAsAzureContainerApp((infra, app) => - { - app.ConfigureCustomDomain(customDomain, certificateName); - }); -``` - -## To correct this error - -Suppress the error with either of the following methods: - -- Set the severity of the rule in the _.editorConfig_ file. - - ```ini - [*.{cs,vb}] - dotnet_diagnostic.ASPIREACADOMAINS001.severity = none - ``` - - For more information about editor config files, see [Configuration files for code analysis rules](/dotnet/fundamentals/code-analysis/configuration-files). - -- Add the following `PropertyGroup` to your project file: - - ```xml - - $(NoWarn);ASPIREACADOMAINS001 - - ``` - -- Suppress in code with the `#pragma warning disable ASPIREACADOMAINS001` directive. diff --git a/docs/diagnostics/ASPIREAZURE001.md b/docs/diagnostics/ASPIREAZURE001.md deleted file mode 100644 index 46489cf297..0000000000 --- a/docs/diagnostics/ASPIREAZURE001.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Compiler Error ASPIREAZURE001 -description: Learn more about compiler Error ASPIREAZURE001. Publishers are for evaluation purposes only and are subject to change or removal in future updates. -ms.date: 04/21/2025 -f1_keywords: - - "ASPIREAZURE001" -helpviewer_keywords: - - "ASPIREAZURE001" ---- - -# Compiler Error ASPIREAZURE001 - -**Version introduced:** 9.2 - -> Publishers are for evaluation purposes only and are subject to change or removal in future updates. Suppress this diagnostic to proceed. - -The .NET Aspire Azure hosting integration now ships with a publisher. If you're using any of the APIs, you might see a compiler error/warning indicating that the API is experimental. This is expected behavior, as the API is still in preview and the shape of this API is expected to change in the future. - -## To correct this Error - -Suppress the Error with either of the following methods: - -- Set the severity of the rule in the _.editorConfig_ file. - - ```ini - [*.{cs,vb}] - dotnet_diagnostic.ASPIREAZURE001.severity = none - ``` - - For more information about editor config files, see [Configuration files for code analysis rules](/dotnet/fundamentals/code-analysis/configuration-files). - -- Add the following `PropertyGroup` to your project file: - - ```xml - - $(NoWarn);ASPIREAZURE001 - - ``` - -- Suppress in code with the `#pragma warning disable ASPIREAZURE001` directive. diff --git a/docs/diagnostics/ASPIRECOSMOSDB001.md b/docs/diagnostics/ASPIRECOSMOSDB001.md deleted file mode 100644 index fcd956960f..0000000000 --- a/docs/diagnostics/ASPIRECOSMOSDB001.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: Compiler Error ASPIRECOSMOSDB001 -description: Learn more about compiler Error ASPIRECOSMOSDB001. `RunAsPreviewEmulator` is for evaluation purposes only and is subject to change or removal in future updates. -ms.date: 04/21/2025 -f1_keywords: - - "ASPIRECOSMOSDB001" -helpviewer_keywords: - - "ASPIRECOSMOSDB001" ---- - -# Compiler Error ASPIRECOSMOSDB001 - -**Version introduced:** 9.0 - -> `RunAsPreviewEmulator` is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed. - --or- - -> `WithDataExplorer` is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed. - -Both `RunAsPreviewEmulator` and `WithDataExplorer` are considered experimental APIs. - -.NET Aspire provides a way to use the Cosmos DB Linux-based (preview) emulator and data explorer. These APIs are considered experimental and are expected to change in the future. - -## Example - -The following sample generates `ASPIRECOSMOSDB001`: - -```csharp -var builder = DistributedApplication.CreateBuilder(args); - -var cosmos = builder.AddAzureCosmosDB("cosmos") - .RunAsPreviewEmulator(e => e.WithDataExplorer()); -``` - -## To correct this error - -Suppress the Error with either of the following methods: - -- Set the severity of the rule in the _.editorConfig_ file. - - ```ini - [*.{cs,vb}] - dotnet_diagnostic.ASPIRECOSMOSDB001.severity = none - ``` - - For more information about editor config files, see [Configuration files for code analysis rules](/dotnet/fundamentals/code-analysis/configuration-files). - -- Add the following `PropertyGroup` to your project file: - - ```xml - - $(NoWarn);ASPIRECOSMOSDB001 - - ``` - -- Suppress in code with the `#pragma warning disable ASPIRECOSMOSDB001` directive. diff --git a/docs/diagnostics/ASPIREHOSTINGPYTHON001.md b/docs/diagnostics/ASPIREHOSTINGPYTHON001.md deleted file mode 100644 index 38827f6564..0000000000 --- a/docs/diagnostics/ASPIREHOSTINGPYTHON001.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Compiler Error ASPIREHOSTINGPYTHON001 -description: Learn more about compiler Error ASPIREHOSTINGPYTHON001. `AddPythonApp` is for evaluation purposes only and is subject to change or removal in future updates. -ms.date: 04/21/2025 -f1_keywords: - - "ASPIREHOSTINGPYTHON001" -helpviewer_keywords: - - "ASPIREHOSTINGPYTHON001" ---- - -# Compiler Error ASPIREHOSTINGPYTHON001 - -**Version introduced:** 9.0 - -> `AddPythonApp` is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed. - -.NET Aspire provides a way to add Python executables or applications to the .NET Aspire app host with the `AddPythonApp` extension. Since the shape of this API is expected to change in the future, it's experimental. - -## Example - -The following code generates `ASPIREHOSTINGPYTHON001`: - -```csharp -var pythonApp = builder.AddPythonApp("hello-python", "../hello-python", "main.py") - .WithHttpEndpoint(env: "PORT") - .WithExternalHttpEndpoints() - .WithOtlpExporter(); -``` - -## To correct this Error - -Suppress the Error with either of the following methods: - -- Set the severity of the rule in the _.editorConfig_ file. - - ```ini - [*.{cs,vb}] - dotnet_diagnostic.ASPIREHOSTINGPYTHON001.severity = none - ``` - - For more information about editor config files, see [Configuration files for code analysis rules](/dotnet/fundamentals/code-analysis/configuration-files). - -- Add the following `PropertyGroup` to your project file: - - ```xml - - $(NoWarn);ASPIREHOSTINGPYTHON001 - - ``` - -- Suppress in code with the `#pragma warning disable ASPIREHOSTINGPYTHON001` directive. diff --git a/docs/diagnostics/ASPIREPUBLISHERS001.md b/docs/diagnostics/ASPIREPUBLISHERS001.md deleted file mode 100644 index af873aba4d..0000000000 --- a/docs/diagnostics/ASPIREPUBLISHERS001.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Compiler Error ASPIREPUBLISHERS001 -description: Learn more about compiler Error ASPIREPUBLISHERS001. Publishers are for evaluation purposes only and are subject to change or removal in future updates. -ms.date: 04/21/2025 -f1_keywords: - - "ASPIREPUBLISHERS001" -helpviewer_keywords: - - "ASPIREPUBLISHERS001" ---- - -# Compiler Error ASPIREPUBLISHERS001 - -**Version introduced:** 9.2 - -> Publishers are for evaluation purposes only and are subject to change or removal in future updates. Suppress this diagnostic to proceed. - -.NET Aspire introduced the concept of _Publishers_ starting in version 9.2. Publishers play a pivotal role in the deployment process, enabling the transformation of your distributed app into deployable assets. This alleviates the intermediate step of producing the publishing [manifest](../deployment/manifest-format.md) for tools to act on, instead empowering the developer to express their intent directly in C#. - -Publishers are considered experimental and are expected to change in the future. - -## To correct this Error - -Suppress the Error with either of the following methods: - -- Set the severity of the rule in the _.editorConfig_ file. - - ```ini - [*.{cs,vb}] - dotnet_diagnostic.ASPIREPUBLISHERS001.severity = none - ``` - - For more information about editor config files, see [Configuration files for code analysis rules](/dotnet/fundamentals/code-analysis/configuration-files). - -- Add the following `PropertyGroup` to your project file: - - ```xml - - $(NoWarn);ASPIREPUBLISHERS001 - - ``` - -- Suppress in code with the `#pragma warning disable ASPIREPUBLISHERS001` directive. From 2397e00b0c2fe5206ade96bea7cbe0e03ba86686 Mon Sep 17 00:00:00 2001 From: "Andy De George (adegeo)" Date: Mon, 21 Apr 2025 18:17:51 -0700 Subject: [PATCH 4/8] Add files as uppercase --- docs/diagnostics/aspire006.md | 27 +++++++++ docs/diagnostics/aspireacadomains001.md | 64 ++++++++++++++++++++++ docs/diagnostics/aspireazure001.md | 40 ++++++++++++++ docs/diagnostics/aspirecosmosdb001.md | 57 +++++++++++++++++++ docs/diagnostics/aspirehostingpython001.md | 51 +++++++++++++++++ docs/diagnostics/aspirepublishers001.md | 42 ++++++++++++++ 6 files changed, 281 insertions(+) create mode 100644 docs/diagnostics/aspire006.md create mode 100644 docs/diagnostics/aspireacadomains001.md create mode 100644 docs/diagnostics/aspireazure001.md create mode 100644 docs/diagnostics/aspirecosmosdb001.md create mode 100644 docs/diagnostics/aspirehostingpython001.md create mode 100644 docs/diagnostics/aspirepublishers001.md diff --git a/docs/diagnostics/aspire006.md b/docs/diagnostics/aspire006.md new file mode 100644 index 0000000000..c5fca6054c --- /dev/null +++ b/docs/diagnostics/aspire006.md @@ -0,0 +1,27 @@ +--- +title: Compiler Error ASPIRE006 +description: Learn more about compiler Error ASPIRE006. Application model items must have valid names. +ms.date: 04/21/2025 +f1_keywords: + - "ASPIRE006" +helpviewer_keywords: + - "ASPIRE006" +--- + +# Compiler Error ASPIRE006 + +**Version introduced:** 8.2.2 + +> Application model items must have valid names. + +This diagnostic error is reported when two or more resources share the same name. + +## Example + +The following code generates `ASPIRE006`: + + + +## To correct this Error + +Give each resource a unique name. diff --git a/docs/diagnostics/aspireacadomains001.md b/docs/diagnostics/aspireacadomains001.md new file mode 100644 index 0000000000..49054d005f --- /dev/null +++ b/docs/diagnostics/aspireacadomains001.md @@ -0,0 +1,64 @@ +--- +title: Compiler Error ASPIREACADOMAINS001 +description: Learn more about compiler Error ASPIREACADOMAINS001. `ConfigureCustomDomain` is for evaluation purposes only and is subject to change or removal in future updates. +ms.date: 04/21/2025 +f1_keywords: + - "ASPIREACADOMAINS001" +helpviewer_keywords: + - "ASPIREACADOMAINS001" +--- + +# Compiler Error ASPIREACADOMAINS001 + +**Version introduced:** 9.0 + +> `ConfigureCustomDomain` is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed. + +.NET Aspire 9.0 introduces the ability to customize container app resources using any of the following extension methods: + +- `Aspire.Hosting.AzureContainerAppProjectExtensions.PublishAsAzureContainerApp` +- `Aspire.Hosting.AzureContainerAppContainerExtensions.PublishAsAzureContainerApp` +- `Aspire.Hosting.AzureContainerAppExecutableExtensions.PublishAsAzureContainerApp` + +When you use one of these methods, the Azure Developer CLI (`azd`) can no longer preserve custom domains. Instead use the `Aspire.Hosting.ContainerAppExtensions.ConfigureCustomDomain` method to configure a custom domain within the .NET Aspire app host. + +However, `app.ConfigureCustomDomain` is an experimental API and you must suppress it to use it. + +## Example + +The following code generates `ASPIREACADOMAINS001`: + +```csharp +var customDomain = builder.AddParameter("customDomain"); +var certificateName = builder.AddParameter("certificateName"); + +builder.AddProject("api") + .WithExternalHttpEndpoints() + .PublishAsAzureContainerApp((infra, app) => + { + app.ConfigureCustomDomain(customDomain, certificateName); + }); +``` + +## To correct this error + +Suppress the error with either of the following methods: + +- Set the severity of the rule in the _.editorConfig_ file. + + ```ini + [*.{cs,vb}] + dotnet_diagnostic.ASPIREACADOMAINS001.severity = none + ``` + + For more information about editor config files, see [Configuration files for code analysis rules](/dotnet/fundamentals/code-analysis/configuration-files). + +- Add the following `PropertyGroup` to your project file: + + ```xml + + $(NoWarn);ASPIREACADOMAINS001 + + ``` + +- Suppress in code with the `#pragma warning disable ASPIREACADOMAINS001` directive. diff --git a/docs/diagnostics/aspireazure001.md b/docs/diagnostics/aspireazure001.md new file mode 100644 index 0000000000..46489cf297 --- /dev/null +++ b/docs/diagnostics/aspireazure001.md @@ -0,0 +1,40 @@ +--- +title: Compiler Error ASPIREAZURE001 +description: Learn more about compiler Error ASPIREAZURE001. Publishers are for evaluation purposes only and are subject to change or removal in future updates. +ms.date: 04/21/2025 +f1_keywords: + - "ASPIREAZURE001" +helpviewer_keywords: + - "ASPIREAZURE001" +--- + +# Compiler Error ASPIREAZURE001 + +**Version introduced:** 9.2 + +> Publishers are for evaluation purposes only and are subject to change or removal in future updates. Suppress this diagnostic to proceed. + +The .NET Aspire Azure hosting integration now ships with a publisher. If you're using any of the APIs, you might see a compiler error/warning indicating that the API is experimental. This is expected behavior, as the API is still in preview and the shape of this API is expected to change in the future. + +## To correct this Error + +Suppress the Error with either of the following methods: + +- Set the severity of the rule in the _.editorConfig_ file. + + ```ini + [*.{cs,vb}] + dotnet_diagnostic.ASPIREAZURE001.severity = none + ``` + + For more information about editor config files, see [Configuration files for code analysis rules](/dotnet/fundamentals/code-analysis/configuration-files). + +- Add the following `PropertyGroup` to your project file: + + ```xml + + $(NoWarn);ASPIREAZURE001 + + ``` + +- Suppress in code with the `#pragma warning disable ASPIREAZURE001` directive. diff --git a/docs/diagnostics/aspirecosmosdb001.md b/docs/diagnostics/aspirecosmosdb001.md new file mode 100644 index 0000000000..fcd956960f --- /dev/null +++ b/docs/diagnostics/aspirecosmosdb001.md @@ -0,0 +1,57 @@ +--- +title: Compiler Error ASPIRECOSMOSDB001 +description: Learn more about compiler Error ASPIRECOSMOSDB001. `RunAsPreviewEmulator` is for evaluation purposes only and is subject to change or removal in future updates. +ms.date: 04/21/2025 +f1_keywords: + - "ASPIRECOSMOSDB001" +helpviewer_keywords: + - "ASPIRECOSMOSDB001" +--- + +# Compiler Error ASPIRECOSMOSDB001 + +**Version introduced:** 9.0 + +> `RunAsPreviewEmulator` is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed. + +-or- + +> `WithDataExplorer` is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed. + +Both `RunAsPreviewEmulator` and `WithDataExplorer` are considered experimental APIs. + +.NET Aspire provides a way to use the Cosmos DB Linux-based (preview) emulator and data explorer. These APIs are considered experimental and are expected to change in the future. + +## Example + +The following sample generates `ASPIRECOSMOSDB001`: + +```csharp +var builder = DistributedApplication.CreateBuilder(args); + +var cosmos = builder.AddAzureCosmosDB("cosmos") + .RunAsPreviewEmulator(e => e.WithDataExplorer()); +``` + +## To correct this error + +Suppress the Error with either of the following methods: + +- Set the severity of the rule in the _.editorConfig_ file. + + ```ini + [*.{cs,vb}] + dotnet_diagnostic.ASPIRECOSMOSDB001.severity = none + ``` + + For more information about editor config files, see [Configuration files for code analysis rules](/dotnet/fundamentals/code-analysis/configuration-files). + +- Add the following `PropertyGroup` to your project file: + + ```xml + + $(NoWarn);ASPIRECOSMOSDB001 + + ``` + +- Suppress in code with the `#pragma warning disable ASPIRECOSMOSDB001` directive. diff --git a/docs/diagnostics/aspirehostingpython001.md b/docs/diagnostics/aspirehostingpython001.md new file mode 100644 index 0000000000..38827f6564 --- /dev/null +++ b/docs/diagnostics/aspirehostingpython001.md @@ -0,0 +1,51 @@ +--- +title: Compiler Error ASPIREHOSTINGPYTHON001 +description: Learn more about compiler Error ASPIREHOSTINGPYTHON001. `AddPythonApp` is for evaluation purposes only and is subject to change or removal in future updates. +ms.date: 04/21/2025 +f1_keywords: + - "ASPIREHOSTINGPYTHON001" +helpviewer_keywords: + - "ASPIREHOSTINGPYTHON001" +--- + +# Compiler Error ASPIREHOSTINGPYTHON001 + +**Version introduced:** 9.0 + +> `AddPythonApp` is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed. + +.NET Aspire provides a way to add Python executables or applications to the .NET Aspire app host with the `AddPythonApp` extension. Since the shape of this API is expected to change in the future, it's experimental. + +## Example + +The following code generates `ASPIREHOSTINGPYTHON001`: + +```csharp +var pythonApp = builder.AddPythonApp("hello-python", "../hello-python", "main.py") + .WithHttpEndpoint(env: "PORT") + .WithExternalHttpEndpoints() + .WithOtlpExporter(); +``` + +## To correct this Error + +Suppress the Error with either of the following methods: + +- Set the severity of the rule in the _.editorConfig_ file. + + ```ini + [*.{cs,vb}] + dotnet_diagnostic.ASPIREHOSTINGPYTHON001.severity = none + ``` + + For more information about editor config files, see [Configuration files for code analysis rules](/dotnet/fundamentals/code-analysis/configuration-files). + +- Add the following `PropertyGroup` to your project file: + + ```xml + + $(NoWarn);ASPIREHOSTINGPYTHON001 + + ``` + +- Suppress in code with the `#pragma warning disable ASPIREHOSTINGPYTHON001` directive. diff --git a/docs/diagnostics/aspirepublishers001.md b/docs/diagnostics/aspirepublishers001.md new file mode 100644 index 0000000000..af873aba4d --- /dev/null +++ b/docs/diagnostics/aspirepublishers001.md @@ -0,0 +1,42 @@ +--- +title: Compiler Error ASPIREPUBLISHERS001 +description: Learn more about compiler Error ASPIREPUBLISHERS001. Publishers are for evaluation purposes only and are subject to change or removal in future updates. +ms.date: 04/21/2025 +f1_keywords: + - "ASPIREPUBLISHERS001" +helpviewer_keywords: + - "ASPIREPUBLISHERS001" +--- + +# Compiler Error ASPIREPUBLISHERS001 + +**Version introduced:** 9.2 + +> Publishers are for evaluation purposes only and are subject to change or removal in future updates. Suppress this diagnostic to proceed. + +.NET Aspire introduced the concept of _Publishers_ starting in version 9.2. Publishers play a pivotal role in the deployment process, enabling the transformation of your distributed app into deployable assets. This alleviates the intermediate step of producing the publishing [manifest](../deployment/manifest-format.md) for tools to act on, instead empowering the developer to express their intent directly in C#. + +Publishers are considered experimental and are expected to change in the future. + +## To correct this Error + +Suppress the Error with either of the following methods: + +- Set the severity of the rule in the _.editorConfig_ file. + + ```ini + [*.{cs,vb}] + dotnet_diagnostic.ASPIREPUBLISHERS001.severity = none + ``` + + For more information about editor config files, see [Configuration files for code analysis rules](/dotnet/fundamentals/code-analysis/configuration-files). + +- Add the following `PropertyGroup` to your project file: + + ```xml + + $(NoWarn);ASPIREPUBLISHERS001 + + ``` + +- Suppress in code with the `#pragma warning disable ASPIREPUBLISHERS001` directive. From cb75b1a601e4aa6938cc9435166b08a284302a97 Mon Sep 17 00:00:00 2001 From: "Andy De George (adegeo)" Date: Mon, 21 Apr 2025 18:21:38 -0700 Subject: [PATCH 5/8] Add article type --- docfx.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docfx.json b/docfx.json index 715ceddd60..be72d0d72a 100644 --- a/docfx.json +++ b/docfx.json @@ -97,7 +97,8 @@ }, "fileMetadata": { "ms.topic": { - "docs/**/*.md": "conceptual" + "docs/**/*.md": "conceptual", + "docs/diagnostics/*.md": "error-reference" }, "ms.devlang": { "docs/**/*.*": "csharp" From 386a0760711696767625cc8ac10b13364ed90dd3 Mon Sep 17 00:00:00 2001 From: "Andy De George (adegeo)" Date: Wed, 23 Apr 2025 14:10:41 -0700 Subject: [PATCH 6/8] Final core updates --- docs/diagnostics/aspire006.md | 11 +- docs/diagnostics/aspireazure001.md | 8 ++ docs/diagnostics/overview.md | 129 +-------------------- docs/fundamentals/orchestrate-resources.md | 12 ++ 4 files changed, 29 insertions(+), 131 deletions(-) diff --git a/docs/diagnostics/aspire006.md b/docs/diagnostics/aspire006.md index c5fca6054c..d25964c862 100644 --- a/docs/diagnostics/aspire006.md +++ b/docs/diagnostics/aspire006.md @@ -14,14 +14,19 @@ helpviewer_keywords: > Application model items must have valid names. -This diagnostic error is reported when two or more resources share the same name. +This diagnostic error is reported when a resource's name is invalid, such as a name with consecutive hyphen (`-`) characters. + +This error shouldn't be be suppressed, as invalid model names throw an exception at runtime. ## Example The following code generates `ASPIRE006`: - +```csharp +var bbsContainer = builder.AddContainer("bbs--server", "coldwall/mystic") + .WithEndpoint(19991, 23); +``` ## To correct this Error -Give each resource a unique name. +Use a valid name. For more information, see [Resource naming conventions](../fundamentals/orchestrate-resources.md#resource-naming-conventions). diff --git a/docs/diagnostics/aspireazure001.md b/docs/diagnostics/aspireazure001.md index 46489cf297..e7a6e47ea0 100644 --- a/docs/diagnostics/aspireazure001.md +++ b/docs/diagnostics/aspireazure001.md @@ -16,6 +16,14 @@ helpviewer_keywords: The .NET Aspire Azure hosting integration now ships with a publisher. If you're using any of the APIs, you might see a compiler error/warning indicating that the API is experimental. This is expected behavior, as the API is still in preview and the shape of this API is expected to change in the future. +## Example + +The following code generates `ASPIREAZURE001`: + +```csharp +builder.AddAzurePublisher(); +``` + ## To correct this Error Suppress the Error with either of the following methods: diff --git a/docs/diagnostics/overview.md b/docs/diagnostics/overview.md index 25a9c1ae24..b72cef29a3 100644 --- a/docs/diagnostics/overview.md +++ b/docs/diagnostics/overview.md @@ -7,7 +7,7 @@ ms.date: 04/15/2025 # .NET Aspire diagnostics list -The following table lists the possible MSBuild and .NET Analyzer warnings and errors you might encounter while developing a .NET Aspire app: +The following table lists the possible MSBuild and .NET Analyzer warnings and errors you might encounter with .NET Aspire: | Diagnostic ID | Type | Description | |-------------------------------------------------------|----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -17,130 +17,3 @@ The following table lists the possible MSBuild and .NET Analyzer warnings and er | [`ASPIRECOSMOSDB001`](ASPIRECOSMOSDB001.md) | (Experimental) Error | `RunAsPreviewEmulator` is for evaluation purposes only and is subject to change or removal in future updates. | | [`ASPIREHOSTINGPYTHON001`](ASPIREHOSTINGPYTHON001.md) | (Experimental) Error | `AddPythonApp` is for evaluation purposes only and is subject to change or removal in future updates. | | [`ASPIREPUBLISHERS001`](ASPIREPUBLISHERS001.md) | Error | Publishers are for evaluation purposes only and are subject to change or removal in future updates. | - -## Suppress diagnostic - -Warning and experimental error diagnostics can be suppressed in one of the following ways: - -- Add the at the assembly, class, method, line, etc. -- Include the diagnostic ID in the `NoWarn` property of your project file. -- Use preprocessor directives in your code. -- Configure diagnostic severity in an _.editorconfig_ file. - -There are some common patterns for suppressing diagnostics in .NET projects. The best method depends on your context and the specific diagnostic. Here's a quick guide to help you choose: - -### Suppress with the suppress message attribute - -The is ideal when you need targeted, documented suppression tied directly to a specific code element like a class or method. It shines when you’re making a deliberate exception to a rule that is valid in most other places. This attribute keeps the suppression close to the code it affects, which helps reviewers and future maintainers understand the rationale. While it's a clean solution for isolated cases, it can clutter the code if overused, and it’s not the best choice for widespread or bulk suppressions. - -To suppress the `ASPIREAZURE001` diagnostic with the , consider the following examples: - -**Assembly-level suppression:** - -```csharp -// Typically placed in AssemblyInfo.cs, GlobalUsings.cs, or any global file. -[assembly: System.Diagnostics.CodeAnalysis.SuppressMessage( - "Aspire.Example", // Category - "ASPIREAZURE001:AspireExampleDiagnostic", // CheckId and optional rule title - Justification = "This warning is not applicable to our context.")] -``` - -**Class-level suppression:** - -```csharp -[System.Diagnostics.CodeAnalysis.SuppressMessage( - "Aspire.Example", - "ASPIREAZURE001:AspireExampleDiagnostic", - Justification = "This warning is not applicable to our context.")] -public class ExampleClassThatConsumesTheOffendingAPI -{ - // Class implementation -} -``` - -**Method-level suppression:** - -```csharp -public class ExampleClass -{ - [System.Diagnostics.CodeAnalysis.SuppressMessage( - "Aspire.Example", - "ASPIREAZURE001:AspireExampleDiagnostic", - Justification = "This warning is not applicable to our context.")] - public void ExampleMethodThatConsumesTheOffendingAPI() - { - // Method implementation - } -} -``` - -> [!IMPORTANT] -> If the diagnostic is triggered on a property, field, or parameter, you can also apply it directly there with the . - -### Suppress within the project file - -Using the `NoWarn` property in the project file is great when you need to suppress a diagnostic across the entire project. This is helpful in cases where a diagnostic is irrelevant to your scenario or when dealing with known false positives. It’s a simple, central way to silence a diagnostic without touching your code. However, it lacks visibility—developers won’t see that a diagnostic is suppressed unless they inspect the project file—so it can make it harder to track intentional exceptions or identify the reason behind suppressions. - -To suppress the `ASPIREAZURE001` diagnostic in the project file, add the following code to your _.csproj_ file: - -```xml - - $(NoWarn);ASPIREAZURE001 - -``` - -> [!TIP] -> The `$(NoWarn)` property in the preceding XML is used to append the diagnostic ID to the existing list of suppressed warnings. This ensures that you don't accidentally remove other suppressions already in place. - -### Suppress with preprocessor directives - -Preprocessor directives like `#pragma warning disable` offer fine-grained suppression within a specific scope, such as a method body or block of code. They're especially handy when you need a temporary suppression during refactoring, or when a rule incorrectly flags a particular line that you can't or don't want to change. The ability to tightly wrap just the affected code makes this approach powerful, but it can also make the code harder to read and maintain, especially if the directives are scattered or forgotten over time. - -To suppress the `ASPIREAZURE001` diagnostic with preprocessor directives, consider the following examples: - -**File-level suppression:** - -```csharp -#pragma warning disable ASPIREAZURE001 - -public class ExampleClassThatConsumesTheOffendingAPI -{ - // Class implementation -} -``` - -**Granular suppression:** - -```csharp -public class ExampleClass -{ - public void ExampleMethodThatConsumesTheOffendingAPI() - { - #pragma warning disable ASPIREAZURE001 - // Code that triggers the diagnostic - #pragma warning restore ASPIREAZURE001 - } -} -``` - -You can use preprocessor directives to suppress the diagnostic for a specific block of code. This is useful when you want to limit the scope of the suppression to a particular section of your code. - -For more information, see [C# preprocessor directives](/dotnet/csharp/language-reference/preprocessor-directives). - -### Suppress with editor configuration - -Suppressing diagnostics using an _.editorconfig_ file is ideal for enforcing or adjusting analyzer behavior at scale. It allows teams to standardize severity levels (or disable rules) across an entire solution or per directory/file pattern. This method keeps suppression cleanly out of the codebase, and it works well for communicating team-wide conventions. However, it can be a bit opaque—developers need to know to look in the config file—and it doesn't offer the precision of an attribute or pragma when dealing with one-off cases. - -To suppress the `ASPIREAZURE001` diagnostic in an _.editorconfig_ file, add the following code: - -```ini -[*.cs] -dotnet_diagnostic.ASPIREAZURE001.severity = none -``` - -This configuration applies to all C# files in the project. You can also scope it to specific files or directories by adjusting the section header. - -## See also - -- [.NET docs: How to suppress code analysis warnings](/dotnet/fundamentals/code-analysis/suppress-warnings) -- [Visual Studio docs: Suppress code analysis violations](/visualstudio/code-quality/in-source-suppression-overview) diff --git a/docs/fundamentals/orchestrate-resources.md b/docs/fundamentals/orchestrate-resources.md index c7c6e2074d..34bb351cc4 100644 --- a/docs/fundamentals/orchestrate-resources.md +++ b/docs/fundamentals/orchestrate-resources.md @@ -16,6 +16,18 @@ In this article, you learn how to customize the behavior of resources further by For the fundamentals of .NET Aspire orchestration and how it manages resources, see [.NET Aspire orchestration overview](app-host-overview.md). +## Resource naming conventions + +Resources in .NET Aspire must follow naming restrictions set by .NET Aspire and the technology that resource represents. For example, a .NET Aspire resource has a maximum name length of 64 characters, but an Azure Container App has a maximum length of 32. When representing a container that's deployed to Azure at publish time, the resource name must not exceed 32 characters. + +.NET Aspire resource names must follow these basic rules: + +- **Must** be between 1 and 64 characters in length. +- **Must** start with an ASCII letter. +- **Must** contain only ASCII letters, digits, and hyphens. +- **Must not** end with a hyphen. +- **Must not** contain consecutive hyphens. + ## Configure explicit resource start Project, executable, and container resources are automatically started with your distributed application by default. A resource can be configured to wait for an explicit startup instruction with the method. A resource configured with is initialized with . From 57afef72bc333d4b8bf18a5351fb191b305630c2 Mon Sep 17 00:00:00 2001 From: "Andy De George (adegeo)" Date: Wed, 23 Apr 2025 14:15:54 -0700 Subject: [PATCH 7/8] Acro and typos --- docs/diagnostics/aspire006.md | 2 +- docs/diagnostics/aspireazure001.md | 2 +- docs/fundamentals/orchestrate-resources.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/diagnostics/aspire006.md b/docs/diagnostics/aspire006.md index d25964c862..3196f14a2f 100644 --- a/docs/diagnostics/aspire006.md +++ b/docs/diagnostics/aspire006.md @@ -16,7 +16,7 @@ helpviewer_keywords: This diagnostic error is reported when a resource's name is invalid, such as a name with consecutive hyphen (`-`) characters. -This error shouldn't be be suppressed, as invalid model names throw an exception at runtime. +This error shouldn't be suppressed, as invalid model names throw an exception at runtime. ## Example diff --git a/docs/diagnostics/aspireazure001.md b/docs/diagnostics/aspireazure001.md index e7a6e47ea0..e02be7f12c 100644 --- a/docs/diagnostics/aspireazure001.md +++ b/docs/diagnostics/aspireazure001.md @@ -14,7 +14,7 @@ helpviewer_keywords: > Publishers are for evaluation purposes only and are subject to change or removal in future updates. Suppress this diagnostic to proceed. -The .NET Aspire Azure hosting integration now ships with a publisher. If you're using any of the APIs, you might see a compiler error/warning indicating that the API is experimental. This is expected behavior, as the API is still in preview and the shape of this API is expected to change in the future. +The .NET Aspire Azure hosting integration now ships with a publisher. If you're using any of the APIs, you might see a compiler error/warning indicating that the API is experimental. This behavior is expected, as the API is still in preview and the shape of this API is expected to change in the future. ## Example diff --git a/docs/fundamentals/orchestrate-resources.md b/docs/fundamentals/orchestrate-resources.md index 34bb351cc4..7fd83cecee 100644 --- a/docs/fundamentals/orchestrate-resources.md +++ b/docs/fundamentals/orchestrate-resources.md @@ -18,7 +18,7 @@ For the fundamentals of .NET Aspire orchestration and how it manages resources, ## Resource naming conventions -Resources in .NET Aspire must follow naming restrictions set by .NET Aspire and the technology that resource represents. For example, a .NET Aspire resource has a maximum name length of 64 characters, but an Azure Container App has a maximum length of 32. When representing a container that's deployed to Azure at publish time, the resource name must not exceed 32 characters. +Resources in .NET Aspire must follow naming restrictions set by .NET Aspire and the technology that resource represents. For example, a .NET Aspire resource has a maximum name length of 64 characters, but an Azure Container App has a maximum length of 32. When you publish the .NET Aspire container resource for Azure, the name must not exceed 32 characters in length. .NET Aspire resource names must follow these basic rules: From e056c7ab2f229443a658d1e334a38724b41bf6e4 Mon Sep 17 00:00:00 2001 From: "Andy De George (adegeo)" Date: Wed, 23 Apr 2025 14:19:33 -0700 Subject: [PATCH 8/8] link directly to diag article --- docs/get-started/build-aspire-apps-with-python.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/get-started/build-aspire-apps-with-python.md b/docs/get-started/build-aspire-apps-with-python.md index b7eaf2e18b..d2ef89bbad 100644 --- a/docs/get-started/build-aspire-apps-with-python.md +++ b/docs/get-started/build-aspire-apps-with-python.md @@ -140,7 +140,7 @@ Replace the app host _Program.cs_ code with the following snippet. This code add :::code source="snippets/PythonSample/PythonSample.AppHost/Program.cs" highlight="6"::: > [!IMPORTANT] -> The preceding code suppresses the `ASPIREHOSTINGPYTHON001` diagnostic error. This error is generated because the `AddPythonApp` API is experimental and might change in future release. For more information, see [ASPIREHOSTINGPYTHON001](../diagnostics/overview.md#aspirehostingpython001). +> The preceding code suppresses the `ASPIREHOSTINGPYTHON001` diagnostic error. This error is generated because the `AddPythonApp` API is experimental and might change in future release. For more information, see [Compiler Error ASPIREHOSTINGPYTHON001](../diagnostics/aspirehostingpython001.md). ## Run the app