diff --git a/docs/diagnostics/aspire001.md b/docs/diagnostics/aspire001.md new file mode 100644 index 0000000000..00b225cdf9 --- /dev/null +++ b/docs/diagnostics/aspire001.md @@ -0,0 +1,42 @@ +--- +title: Compiler Warning ASPIRE001 +description: Learn more about compiler Warning ASPIRE001. The code language isn't fully supported by Aspire - some code generation targets will not run, so will require manual authoring. +ms.date: 05/08/2025 +f1_keywords: + - "ASPIRE001" +helpviewer_keywords: + - "ASPIRE001" +--- + +# Compiler Warning ASPIRE001 + +**Version introduced:** 8.0.0 + +> The 'CODELANGUAGE' language isn't fully supported by Aspire - some code generation targets will not run, so will require manual authoring. + +This diagnostic warning is reported when using a code language other than C#. + +## To correct this warning + +In your .NET Aspire project, use C#. + +## Suppress the warning + +Suppress the warning with either of the following methods: + +- Set the severity of the rule in the _.editorconfig_ file. + + ```ini + [*.{cs,vb}] + dotnet_diagnostic.ASPIRE001.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);ASPIRE001 + + ``` diff --git a/docs/diagnostics/aspire002.md b/docs/diagnostics/aspire002.md new file mode 100644 index 0000000000..0da393032b --- /dev/null +++ b/docs/diagnostics/aspire002.md @@ -0,0 +1,21 @@ +--- +title: Compiler Warning ASPIRE002 +description: Learn more about compiler Warning ASPIRE002. Project is an Aspire AppHost project but necessary dependencies aren't present. Are you missing an Aspire.Hosting.AppHost PackageReference? +ms.date: 05/08/2025 +f1_keywords: + - "ASPIRE002" +helpviewer_keywords: + - "ASPIRE002" +--- + +# Compiler Warning ASPIRE002 + +**Version introduced:** 8.0.0 + +> 'Project' is an Aspire AppHost project but necessary dependencies aren't present. Are you missing an Aspire.Hosting.AppHost PackageReference? + +This diagnostic warning is reported when your project is missing reference to the .NET Aspire App Host. + +## To correct this warning + +Add reference to the [📦 Aspire.Hosting.AppHost](https://www.nuget.org/packages/Aspire.Hosting.AppHost) NuGet package. For more information about the app host, see [.NET Aspire orchestration overview](../fundamentals/app-host-overview.md). diff --git a/docs/diagnostics/aspire003.md b/docs/diagnostics/aspire003.md new file mode 100644 index 0000000000..c23c5a6cbe --- /dev/null +++ b/docs/diagnostics/aspire003.md @@ -0,0 +1,21 @@ +--- +title: Compiler Warning ASPIRE003 +description: Learn more about compiler Warning ASPIRE003. Project is a .NET Aspire AppHost project that requires Visual Studio version 17.10 or above to work correctly. +ms.date: 05/08/2025 +f1_keywords: + - "ASPIRE003" +helpviewer_keywords: + - "ASPIRE003" +--- + +# Compiler Warning ASPIRE003 + +**Version introduced:** 8.0.0 + +> 'Project' is a .NET Aspire AppHost project that requires Visual Studio version 17.10 or above to work correctly. + +When using Visual Studio to code your .NET Aspire project, you must have Visual Studio 2022 version 17.10 or later. + +## To correct this warning + +Upgrade Visual Studio 2022 to latest version, or at a minimum, version 17.20. diff --git a/docs/diagnostics/aspire004.md b/docs/diagnostics/aspire004.md new file mode 100644 index 0000000000..93550a436d --- /dev/null +++ b/docs/diagnostics/aspire004.md @@ -0,0 +1,48 @@ +--- +title: Compiler Warning ASPIRE004 +description: Learn more about compiler Warning ASPIRE004. Project is referenced by an Aspire Host project, but it is not an executable. +ms.date: 05/08/2025 +f1_keywords: + - "ASPIRE004" +helpviewer_keywords: + - "ASPIRE004" +--- + +# Compiler Warning ASPIRE004 + +**Version introduced:** 8.0.0 + +> 'Project' is referenced by an Aspire Host project, but it is not an executable. Did you mean to set IsAspireProjectResource="false"? + +The project being referenced byt the .NET Aspire App Host isn't an executable, but is being treated like one for the purposes of orchestration. + +## To correct this warning + +Either change the build type of the project to an executable, or add the `IsAspireProjectResource="false"` setting to the project reference in your .NET Aspire App Host project file, as demonstrated in the following snippet: + +```xml + + + +``` + +## Suppress the warning + +Suppress the warning with either of the following methods: + +- Set the severity of the rule in the _.editorconfig_ file. + + ```ini + [*.{cs,vb}] + dotnet_diagnostic.ASPIRE004.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);ASPIRE004 + + ``` diff --git a/docs/diagnostics/aspire007.md b/docs/diagnostics/aspire007.md new file mode 100644 index 0000000000..0ebca4266e --- /dev/null +++ b/docs/diagnostics/aspire007.md @@ -0,0 +1,43 @@ +--- +title: Compiler Error ASPIRE007 +description: Learn more about compiler Error ASPIRE007. 'Project' requires a reference to "Aspire.AppHost.Sdk" with version "9.0.0" or greater to work correctly. +ms.date: 05/08/2025 +f1_keywords: + - "ASPIRE007" +helpviewer_keywords: + - "ASPIRE007" +--- + +# Compiler Error ASPIRE007 + +**Version introduced:** 9.0.0 + +> 'Project' requires a reference to "Aspire.AppHost.Sdk" with version "9.0.0" or greater to work correctly. Please add the following line after the Project declaration ``. + +The .NET Aspire App Host package references require .NET Aspire SDK version 9.0.0 or greater. The SDK reference is either being omitted or is using a version older than 9.0.0. + +## To correct this error + +Update the referenced SDK version to 9.0.0 or the latest. + +If the SDK reference is missing from your project file, add it, as demonstrated in the following snippet: + +```xml + + + + + + Exe + net9.0 + enable + enable + true + + + + + + + +``` diff --git a/docs/diagnostics/aspireacadomains001.md b/docs/diagnostics/aspireacadomains001.md index 49054d005f..82f4e953c5 100644 --- a/docs/diagnostics/aspireacadomains001.md +++ b/docs/diagnostics/aspireacadomains001.md @@ -44,7 +44,7 @@ builder.AddProject("api") Suppress the error with either of the following methods: -- Set the severity of the rule in the _.editorConfig_ file. +- Set the severity of the rule in the _.editorconfig_ file. ```ini [*.{cs,vb}] diff --git a/docs/diagnostics/aspireazure001.md b/docs/diagnostics/aspireazure001.md index e02be7f12c..58ebecff2a 100644 --- a/docs/diagnostics/aspireazure001.md +++ b/docs/diagnostics/aspireazure001.md @@ -28,7 +28,7 @@ builder.AddAzurePublisher(); Suppress the Error with either of the following methods: -- Set the severity of the rule in the _.editorConfig_ file. +- Set the severity of the rule in the _.editorconfig_ file. ```ini [*.{cs,vb}] diff --git a/docs/diagnostics/aspirecompute001.md b/docs/diagnostics/aspirecompute001.md new file mode 100644 index 0000000000..d03c9b855d --- /dev/null +++ b/docs/diagnostics/aspirecompute001.md @@ -0,0 +1,52 @@ +--- +title: Compiler Error ASPIRECOMPUTE001 +description: Learn more about compiler Error ASPIRECOMPUTE001. Compute related types and members are for evaluation purposes only and are subject to change or removal in future updates. Suppress this diagnostic to proceed. +ms.date: 05/08/2025 +f1_keywords: + - "ASPIRECOMPUTE001" +helpviewer_keywords: + - "ASPIRECOMPUTE001" +--- + +# Compiler Error ASPIRECOMPUTE001 + +**Version introduced:** 9.3 + +> Compute related types and members are for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed. + +## Example + +The following code generates `ASPIRECOMPUTE001`: + +```csharp +var builder = DistributedApplication.CreateBuilder(args); + +builder.AddDockerComposeEnvironment("env"); +// or +builder.AddAzureContainerAppEnvironment("env") +// or +builder.AddKubernetesEnvironment("env") +``` + +## 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.ASPIRECOMPUTE001.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);ASPIRECOMPUTE001 + + ``` + +- Suppress in code with the `#pragma warning disable ASPIRECOMPUTE001` directive. diff --git a/docs/diagnostics/aspirecosmosdb001.md b/docs/diagnostics/aspirecosmosdb001.md index fcd956960f..3c4480c0a5 100644 --- a/docs/diagnostics/aspirecosmosdb001.md +++ b/docs/diagnostics/aspirecosmosdb001.md @@ -37,7 +37,7 @@ var cosmos = builder.AddAzureCosmosDB("cosmos") Suppress the Error with either of the following methods: -- Set the severity of the rule in the _.editorConfig_ file. +- Set the severity of the rule in the _.editorconfig_ file. ```ini [*.{cs,vb}] diff --git a/docs/diagnostics/aspirehostingpython001.md b/docs/diagnostics/aspirehostingpython001.md index 38827f6564..c372d07402 100644 --- a/docs/diagnostics/aspirehostingpython001.md +++ b/docs/diagnostics/aspirehostingpython001.md @@ -31,7 +31,7 @@ var pythonApp = builder.AddPythonApp("hello-python", "../hello-python", "main.py Suppress the Error with either of the following methods: -- Set the severity of the rule in the _.editorConfig_ file. +- Set the severity of the rule in the _.editorconfig_ file. ```ini [*.{cs,vb}] diff --git a/docs/diagnostics/aspireproxyendpoints001.md b/docs/diagnostics/aspireproxyendpoints001.md new file mode 100644 index 0000000000..9fa99cefc6 --- /dev/null +++ b/docs/diagnostics/aspireproxyendpoints001.md @@ -0,0 +1,57 @@ +--- +title: Compiler Error ASPIREPROXYENDPOINTS001 +description: Learn more about compiler Error ASPIREPROXYENDPOINTS001. Members are for evaluation purposes only and are subject to change or removal in future updates. +ms.date: 05/08/2025 +f1_keywords: + - "ASPIREPROXYENDPOINTS001" +helpviewer_keywords: + - "ASPIREPROXYENDPOINTS001" +--- + +# Compiler Error ASPIREPROXYENDPOINTS001 + +**Version introduced:** 9.1 + +> `WithEndpointProxySupport` is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed. + +-or- + +> `ProxySupportAnnotation` is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed. + +Both `WithEndpointProxySupport` and `ProxySupportAnnotation` are considered experimental APIs. + +Container resources use proxied endpoints by default. Adjusting this setting is experimental. For more information, see . + +## Example + +The following code generates `ASPIREPROXYENDPOINTS001`: + +```csharp +var builder = DistributedApplication.CreateBuilder(args); + +var redis = builder.AddRedis($"example-redis", 1234) + .WithEndpointProxySupport(false); +``` + +## 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.ASPIREPROXYENDPOINTS001.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);ASPIREPROXYENDPOINTS001 + + ``` + +- Suppress in code with the `#pragma warning disable ASPIREPROXYENDPOINTS001` directive. diff --git a/docs/diagnostics/aspirepublishers001.md b/docs/diagnostics/aspirepublishers001.md index af873aba4d..16f1fb526e 100644 --- a/docs/diagnostics/aspirepublishers001.md +++ b/docs/diagnostics/aspirepublishers001.md @@ -22,7 +22,7 @@ Publishers are considered experimental and are expected to change in the future. Suppress the Error with either of the following methods: -- Set the severity of the rule in the _.editorConfig_ file. +- Set the severity of the rule in the _.editorconfig_ file. ```ini [*.{cs,vb}] diff --git a/docs/diagnostics/overview.md b/docs/diagnostics/overview.md index b72cef29a3..ca367180bd 100644 --- a/docs/diagnostics/overview.md +++ b/docs/diagnostics/overview.md @@ -9,11 +9,18 @@ ms.date: 04/15/2025 The following table lists the possible MSBuild and .NET Analyzer warnings and errors you might encounter with .NET Aspire: -| 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. | +| Diagnostic ID | Type | Description | +|---------------------------------------------------------|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [`ASPIRE001`](aspire001.md) | Warning | The code language isn't fully supported by Aspire, some code generation targets will not run. | +| [`ASPIRE002`](aspire002.md) | Warning | Project is an Aspire AppHost project but necessary dependencies aren't present. Are you missing an Aspire.Hosting.AppHost PackageReference? | +| [`ASPIRE003`](aspire003.md) | Warning | 'Project' is a .NET Aspire AppHost project that requires Visual Studio version 17.10 or above to work correctly. | +| [`ASPIRE004`](aspire004.md) | Warning | 'Project' is referenced by an Aspire Host project, but it is not an executable. | +| [`ASPIRE006`](aspire006.md) | (Experimental) Error | Application model items must have valid names. | +| [`ASPIRE007`](aspire007.md) | Error | 'Project' requires a reference to "Aspire.AppHost.Sdk" with version "9.0.0" or greater to work correctly. | +| [`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. | +| [`ASPIRECOMPUTE001`](aspirecompute001.md) | (Experimental) Error | Compute related types and members are for evaluation purposes only and is 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. | +| [`ASPIREPROXYENDPOINTS001`](aspireproxyendpoints001.md) | (Experimental) Error | ProxyEndpoint members are for evaluation purposes only and are 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. | diff --git a/docs/toc.yml b/docs/toc.yml index 23e20c2298..90a697df0b 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -425,22 +425,50 @@ items: items: - name: Overview href: diagnostics/overview.md + - name: Warnings + items: + - name: ASPIRE001 + href: diagnostics/aspire001.md + - name: ASPIRE002 + href: diagnostics/aspire002.md + - name: ASPIRE003 + href: diagnostics/aspire003.md + - name: ASPIRE004 + href: diagnostics/aspire004.md - name: Errors items: - name: ASPIRE006 href: diagnostics/aspire006.md + - name: ASPIRE007 + href: diagnostics/aspire007.md - name: ASPIREACADOMAINS001 href: diagnostics/aspireacadomains001.md + - name: ASPIRECOMPUTE001 + href: diagnostics/aspirecompute001.md - name: ASPIRECOSMOSDB001 href: diagnostics/aspirecosmosdb001.md - name: ASPIREHOSTINGPYTHON001 href: diagnostics/aspirehostingpython001.md + - name: ASPIREPROXYENDPOINTS001 + href: diagnostics/aspireproxyendpoints001.md - name: ASPIREPUBLISHERS001 href: diagnostics/aspirepublishers001.md - name: ASPIREAZURE001 href: diagnostics/aspireazure001.md - name: By category items: + - name: Project + items: + - name: Code language not fully supported + href: diagnostics/aspire001.md + - name: Aspire.Hosting.AppHost is missing + href: diagnostics/aspire002.md + - name: Version of Visual Studio not supported + href: diagnostics/aspire003.md + - name: Referenced project isn't an executable + href: diagnostics/aspire004.md + - name: Aspire SDK reference is out of date or missing + href: diagnostics/aspire007.md - name: Resources items: - name: Items must have valid names @@ -451,6 +479,10 @@ items: href: diagnostics/aspireacadomains001.md - name: Cosmos DB preview emulator and data explorer href: diagnostics/aspirecosmosdb001.md + - name: Various compute APIs are experimental + href: diagnostics/aspirecompute001.md + - name: Container proxy endpoint APIs are experimental + href: diagnostics/aspireproxyendpoints001.md - name: Hosting Python apps href: diagnostics/aspirehostingpython001.md - name: Publishing APIs are experimental