Initial draft of diagnostic redesign

docfx.json

@@ -97,7 +97,8 @@
     },
     "fileMetadata": {
       "ms.topic": {
-        "docs/**/*.md": "conceptual"
+        "docs/**/*.md": "conceptual",
+        "docs/diagnostics/*.md": "error-reference"
       },
       "ms.devlang": {
         "docs/**/*.*": "csharp"

docs/diagnostics/aspire006.md

@@ -0,0 +1,32 @@
+---
+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 a resource's name is invalid, such as a name with consecutive hyphen (`-`) characters.
+
+This error shouldn't 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
+
+Use a valid name. For more information, see [Resource naming conventions](../fundamentals/orchestrate-resources.md#resource-naming-conventions).

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<Projects.AzureContainerApps_ApiService>("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
+  <PropertyGroup>
+      <NoWarn>$(NoWarn);ASPIREACADOMAINS001</NoWarn>
+  </PropertyGroup>
+  ```
+
+- Suppress in code with the `#pragma warning disable ASPIREACADOMAINS001` directive.

docs/diagnostics/aspireazure001.md

@@ -0,0 +1,48 @@
+---
+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 <xref:Aspire.Hosting.AzurePublisherExtensions.AddAzurePublisher*> 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
+
+The following code generates `ASPIREAZURE001`:
+
+```csharp
+builder.AddAzurePublisher();
+```
+
+## 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
+  <PropertyGroup>
+      <NoWarn>$(NoWarn);ASPIREAZURE001</NoWarn>
+  </PropertyGroup>
+  ```
+
+- Suppress in code with the `#pragma warning disable ASPIREAZURE001` directive.

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
+  <PropertyGroup>
+      <NoWarn>$(NoWarn);ASPIRECOSMOSDB001</NoWarn>
+  </PropertyGroup>
+  ```
+
+- Suppress in code with the `#pragma warning disable ASPIRECOSMOSDB001` directive.

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
+  <PropertyGroup>
+      <NoWarn>$(NoWarn);ASPIREHOSTINGPYTHON001</NoWarn>
+  </PropertyGroup>
+  ```
+
+- Suppress in code with the `#pragma warning disable ASPIREHOSTINGPYTHON001` directive.

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
+  <PropertyGroup>
+      <NoWarn>$(NoWarn);ASPIREPUBLISHERS001</NoWarn>
+  </PropertyGroup>
+  ```
+
+- Suppress in code with the `#pragma warning disable ASPIREPUBLISHERS001` directive.