NullableResponse<T> and consumption by tables (#31790)

* NullableResponse<T>

Author: christothes

sdk/appconfiguration/Azure.Data.AppConfiguration/src/Azure.Data.AppConfiguration.csproj

@@ -9,11 +9,12 @@
     <PackageTags>Microsoft Azure Application Configuration;Data;AppConfig;$(PackageCommonTags)</PackageTags>
     <TargetFrameworks>$(RequiredTargetFrameworks)</TargetFrameworks>
     <NoWarn>$(NoWarn);3021;AZC0007;AZC0006</NoWarn>
-    <IncludeOperationsSharedSource>true</IncludeOperationsSharedSource> 
+    <IncludeOperationsSharedSource>true</IncludeOperationsSharedSource>
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Azure.Core" />
+    <!-- <PackageReference Include="Azure.Core" /> -->
+    <ProjectReference Include="..\..\..\core\Azure.Core\src\Azure.Core.csproj" />
     <PackageReference Include="Microsoft.Bcl.AsyncInterfaces" />
     <PackageReference Include="System.Text.Json" />
   </ItemGroup>

sdk/core/Azure.Core/CHANGELOG.md

@@ -3,6 +3,7 @@
 ## 1.26.0-beta.1 (Unreleased)
 
 ### Features Added
+- Introduced a new `NullableResponse<T>` type for scenarios where a service method may or may not return a value. One common example is `Get*IfExists` methods. `Response<T>` also now inherits from `NullableResponse<T>`.
 
 ### Breaking Changes
 
@@ -15,7 +16,7 @@
 ### Features Added
 - Added `RequestFailedDetailsParser` abstract class, which client libraries can implement to control customization of exception messages for failed responses.
 - Added `HttpPipelineOptions` type which is accepted in a new overload to `HttpPipelineBuilder.Build`.  This type contains all the properties from other overloads and adds a property to specify a `RequestFailedDetailsParser`.
-- Added a property to `HttpPipelineTransportOptions` called `ClientCertificates` which is a collection of `X509Certificate2`. If populated, the certificates in the collection will be used by the client for TLS client certificate authentication. 
+- Added a property to `HttpPipelineTransportOptions` called `ClientCertificates` which is a collection of `X509Certificate2`. If populated, the certificates in the collection will be used by the client for TLS client certificate authentication.
 - Added the `MultipartResponse` type, which can be used by clients to parse the sub-responses for multi-part responses.
 
 ## 1.24.0 (2022-04-04)
@@ -56,7 +57,7 @@
 - Added `ResourceIdentifier`. This class allows users to load an Azure resource identifier string and parse out the pieces of that string such as which `SubscriptionId` does the resource belong to.
 - Added `ResourceType`. This class represents the ARM provider information for a given resource and is used by the `ResourceIdentifier` class.
 - Added `HttpPipelineTransportOptions` type.  This type contains a `ServerCertificateCustomValidationCallback` property that allows callers to set a `Func<ServerCertificateCustomValidationArgs, bool>` delegate.  If set, the delegate will be called to validate the server side TLS certificate.
-- Added a new static overload for `HttpPipelineBuilder.Build` that takes an `HttpPipelineTransportOptions` instance.  This overload creates an `HttpPipeline` with the default transport configuration and the `HttpPipelineTransportOptions` applied. It returns a `DisposableHttpPipeline` that implements `IDisposable`. Note: The `HttpPipelineTransportOptions` will not be applied if a custom `Transport` has been set in the `ClientOptions`. In the case that transport options were provided but not applied, an event is logged `(PipelineTransportOptionsNotApplied`). 
+- Added a new static overload for `HttpPipelineBuilder.Build` that takes an `HttpPipelineTransportOptions` instance.  This overload creates an `HttpPipeline` with the default transport configuration and the `HttpPipelineTransportOptions` applied. It returns a `DisposableHttpPipeline` that implements `IDisposable`. Note: The `HttpPipelineTransportOptions` will not be applied if a custom `Transport` has been set in the `ClientOptions`. In the case that transport options were provided but not applied, an event is logged `(PipelineTransportOptionsNotApplied`).
 
 ### Breaking Changes
 
@@ -191,7 +192,7 @@ options.Diagnostics.LoggedQueryParameters.Remove("api-version");
 - `AzureSasCredential` and its respective policy.
 
 ### Key Bug Fixes
-- Avoid a causing and ignoring an exception when setting network stream timeout on .NET Core 
+- Avoid a causing and ignoring an exception when setting network stream timeout on .NET Core.
 
 ## 1.7.0 (2020-12-14)
 
@@ -215,7 +216,7 @@ options.Diagnostics.LoggedQueryParameters.Remove("api-version");
 ## 1.5.1 (2020-10-01)
 
 ### Changed
-- `ServicePointManager` Connection limit is automatically increased to `50` for Azure endpoints. 
+- `ServicePointManager` Connection limit is automatically increased to `50` for Azure endpoints.
 
 
 ## 1.5.0 (2020-09-03)
@@ -229,7 +230,7 @@ options.Diagnostics.LoggedQueryParameters.Remove("api-version");
 ```xml
  <ItemGroup>
     <RuntimeHostConfigurationOption Include="Azure.Core.Pipeline.DisableHttpWebRequestTransport" Value="true" />
-  </ItemGroup> 
+  </ItemGroup>
 ```
 
 When the environment variable or the switch are set the `HttpClientTransport` would be used by default instead.
@@ -290,28 +291,28 @@ When the environment variable or the switch are set the `HttpClientTransport` wo
 - Add support for retrying on 408, 500, 502, 504 status codes.
 - Remove commit hash from User-Agent telemetry.
 
-## 1.0.1 
+## 1.0.1
 
 - Fix issues with log redaction where first query character was replaced with '?' character.
 - Exclude EventCounter events from AzureEventSourceListener.
 - Add `AZURE_TRACING_DISABLED` environment variable support.
 
-## 1.0.0 
+## 1.0.0
 
 - Updating versioning and packaging for general availability.
 - Make types and namespace names consistent.
 
-## 1.0.0-preview.9 
+## 1.0.0-preview.9
 
 - Added console and trace logger listener.
 - Added additional content and header logging options.
 - Moved commonly used types to Azure namespace.
 
-## 1.0.0-preview.8 
+## 1.0.0-preview.8
 
 - Minor improvements and bug fixes.
 
-## 1.0.0-preview.7 
+## 1.0.0-preview.7
 
 - Support for distributed tracing added.
 - Support for TokenCredential in ASP.NET Core integration added.

sdk/core/Azure.Core/api/Azure.Core.net461.cs

@@ -113,6 +113,18 @@ public MatchConditions() { }
         public Azure.ETag? IfMatch { get { throw null; } set { } }
         public Azure.ETag? IfNoneMatch { get { throw null; } set { } }
     }
+    public abstract partial class NullableResponse<T>
+    {
+        protected NullableResponse() { }
+        public abstract bool HasValue { get; }
+        public abstract T Value { get; }
+        [System.ComponentModel.EditorBrowsableAttribute(System.ComponentModel.EditorBrowsableState.Never)]
+        public override bool Equals(object? obj) { throw null; }
+        [System.ComponentModel.EditorBrowsableAttribute(System.ComponentModel.EditorBrowsableState.Never)]
+        public override int GetHashCode() { throw null; }
+        public abstract Azure.Response GetRawResponse();
+        public override string ToString() { throw null; }
+    }
     public abstract partial class Operation
     {
         protected Operation() { }
@@ -239,17 +251,16 @@ public ResponseError(string? code, string? message) { }
         public string? Message { get { throw null; } }
         public override string ToString() { throw null; }
     }
-    public abstract partial class Response<T>
+    public abstract partial class Response<T> : Azure.NullableResponse<T>
     {
         protected Response() { }
-        public abstract T Value { get; }
+        [System.ComponentModel.EditorBrowsableAttribute(System.ComponentModel.EditorBrowsableState.Never)]
+        public override bool HasValue { get { throw null; } }
         [System.ComponentModel.EditorBrowsableAttribute(System.ComponentModel.EditorBrowsableState.Never)]
         public override bool Equals(object? obj) { throw null; }
         [System.ComponentModel.EditorBrowsableAttribute(System.ComponentModel.EditorBrowsableState.Never)]
         public override int GetHashCode() { throw null; }
-        public abstract Azure.Response GetRawResponse();
         public static implicit operator T (Azure.Response<T> response) { throw null; }
-        public override string ToString() { throw null; }
     }
     public partial class SyncAsyncEventArgs : System.EventArgs
     {

sdk/core/Azure.Core/api/Azure.Core.net5.0.cs

@@ -113,6 +113,18 @@ public MatchConditions() { }
         public Azure.ETag? IfMatch { get { throw null; } set { } }
         public Azure.ETag? IfNoneMatch { get { throw null; } set { } }
     }
+    public abstract partial class NullableResponse<T>
+    {
+        protected NullableResponse() { }
+        public abstract bool HasValue { get; }
+        public abstract T Value { get; }
+        [System.ComponentModel.EditorBrowsableAttribute(System.ComponentModel.EditorBrowsableState.Never)]
+        public override bool Equals(object? obj) { throw null; }
+        [System.ComponentModel.EditorBrowsableAttribute(System.ComponentModel.EditorBrowsableState.Never)]
+        public override int GetHashCode() { throw null; }
+        public abstract Azure.Response GetRawResponse();
+        public override string ToString() { throw null; }
+    }
     public abstract partial class Operation
     {
         protected Operation() { }
@@ -239,17 +251,16 @@ public ResponseError(string? code, string? message) { }
         public string? Message { get { throw null; } }
         public override string ToString() { throw null; }
     }
-    public abstract partial class Response<T>
+    public abstract partial class Response<T> : Azure.NullableResponse<T>
     {
         protected Response() { }
-        public abstract T Value { get; }
+        [System.ComponentModel.EditorBrowsableAttribute(System.ComponentModel.EditorBrowsableState.Never)]
+        public override bool HasValue { get { throw null; } }
         [System.ComponentModel.EditorBrowsableAttribute(System.ComponentModel.EditorBrowsableState.Never)]
         public override bool Equals(object? obj) { throw null; }
         [System.ComponentModel.EditorBrowsableAttribute(System.ComponentModel.EditorBrowsableState.Never)]
         public override int GetHashCode() { throw null; }
-        public abstract Azure.Response GetRawResponse();
         public static implicit operator T (Azure.Response<T> response) { throw null; }
-        public override string ToString() { throw null; }
     }
     public partial class SyncAsyncEventArgs : System.EventArgs
     {

sdk/core/Azure.Core/api/Azure.Core.netcoreapp2.1.cs

@@ -113,6 +113,18 @@ public MatchConditions() { }
         public Azure.ETag? IfMatch { get { throw null; } set { } }
         public Azure.ETag? IfNoneMatch { get { throw null; } set { } }
     }
+    public abstract partial class NullableResponse<T>
+    {
+        protected NullableResponse() { }
+        public abstract bool HasValue { get; }
+        public abstract T Value { get; }
+        [System.ComponentModel.EditorBrowsableAttribute(System.ComponentModel.EditorBrowsableState.Never)]
+        public override bool Equals(object? obj) { throw null; }
+        [System.ComponentModel.EditorBrowsableAttribute(System.ComponentModel.EditorBrowsableState.Never)]
+        public override int GetHashCode() { throw null; }
+        public abstract Azure.Response GetRawResponse();
+        public override string ToString() { throw null; }
+    }
     public abstract partial class Operation
     {
         protected Operation() { }
@@ -239,17 +251,16 @@ public ResponseError(string? code, string? message) { }
         public string? Message { get { throw null; } }
         public override string ToString() { throw null; }
     }
-    public abstract partial class Response<T>
+    public abstract partial class Response<T> : Azure.NullableResponse<T>
     {
         protected Response() { }
-        public abstract T Value { get; }
+        [System.ComponentModel.EditorBrowsableAttribute(System.ComponentModel.EditorBrowsableState.Never)]
+        public override bool HasValue { get { throw null; } }
         [System.ComponentModel.EditorBrowsableAttribute(System.ComponentModel.EditorBrowsableState.Never)]
         public override bool Equals(object? obj) { throw null; }
         [System.ComponentModel.EditorBrowsableAttribute(System.ComponentModel.EditorBrowsableState.Never)]
         public override int GetHashCode() { throw null; }
-        public abstract Azure.Response GetRawResponse();
         public static implicit operator T (Azure.Response<T> response) { throw null; }
-        public override string ToString() { throw null; }
     }
     public partial class SyncAsyncEventArgs : System.EventArgs
     {

sdk/core/Azure.Core/api/Azure.Core.netstandard2.0.cs

@@ -113,6 +113,18 @@ public MatchConditions() { }
         public Azure.ETag? IfMatch { get { throw null; } set { } }
         public Azure.ETag? IfNoneMatch { get { throw null; } set { } }
     }
+    public abstract partial class NullableResponse<T>
+    {
+        protected NullableResponse() { }
+        public abstract bool HasValue { get; }
+        public abstract T Value { get; }
+        [System.ComponentModel.EditorBrowsableAttribute(System.ComponentModel.EditorBrowsableState.Never)]
+        public override bool Equals(object? obj) { throw null; }
+        [System.ComponentModel.EditorBrowsableAttribute(System.ComponentModel.EditorBrowsableState.Never)]
+        public override int GetHashCode() { throw null; }
+        public abstract Azure.Response GetRawResponse();
+        public override string ToString() { throw null; }
+    }
     public abstract partial class Operation
     {
         protected Operation() { }
@@ -239,17 +251,16 @@ public ResponseError(string? code, string? message) { }
         public string? Message { get { throw null; } }
         public override string ToString() { throw null; }
     }
-    public abstract partial class Response<T>
+    public abstract partial class Response<T> : Azure.NullableResponse<T>
     {
         protected Response() { }
-        public abstract T Value { get; }
+        [System.ComponentModel.EditorBrowsableAttribute(System.ComponentModel.EditorBrowsableState.Never)]
+        public override bool HasValue { get { throw null; } }
         [System.ComponentModel.EditorBrowsableAttribute(System.ComponentModel.EditorBrowsableState.Never)]
         public override bool Equals(object? obj) { throw null; }
         [System.ComponentModel.EditorBrowsableAttribute(System.ComponentModel.EditorBrowsableState.Never)]
         public override int GetHashCode() { throw null; }
-        public abstract Azure.Response GetRawResponse();
         public static implicit operator T (Azure.Response<T> response) { throw null; }
-        public override string ToString() { throw null; }
     }
     public partial class SyncAsyncEventArgs : System.EventArgs
     {

sdk/core/Azure.Core/src/NullableResponseOfT.cs

@@ -0,0 +1,45 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using System.ComponentModel;
+
+namespace Azure
+{
+    /// <summary>
+    /// Represents a result of Azure operation.
+    /// </summary>
+    /// <typeparam name="T">The type of returned value.</typeparam>
+#pragma warning disable SA1649 // File name should match first type name
+    public abstract class NullableResponse<T>
+#pragma warning restore SA1649 // File name should match first type name
+    {
+        private const string NoValue = "<null>";
+
+        /// <summary>
+        /// Gets a value indicating whether the current instance has a valid value of its underlying type.
+        /// </summary>
+        public abstract bool HasValue { get; }
+
+        /// <summary>
+        /// Gets the value returned by the service. Accessing this property will throw if <see cref="HasValue"/> is false.
+        /// </summary>
+        public abstract T Value { get; }
+
+        /// <summary>
+        /// Returns the HTTP response returned by the service.
+        /// </summary>
+        /// <returns>The HTTP response returned by the service.</returns>
+        public abstract Response GetRawResponse();
+
+        /// <inheritdoc />
+        [EditorBrowsable(EditorBrowsableState.Never)]
+        public override bool Equals(object? obj) => base.Equals(obj);
+
+        /// <inheritdoc />
+        [EditorBrowsable(EditorBrowsableState.Never)]
+        public override int GetHashCode() => base.GetHashCode();
+
+        /// <inheritdoc />
+        public override string ToString() => $"Status: {GetRawResponse()?.Status}, Value: {(HasValue ? Value : NoValue)}";
+    }
+}

sdk/core/Azure.Core/src/ResponseOfT.cs

@@ -14,20 +14,13 @@ namespace Azure
     [DebuggerTypeProxy(typeof(ResponseDebugView<>))]
 #pragma warning disable SA1649 // File name should match first type name
 #pragma warning disable AZC0012 // Avoid single word type names
-    public abstract class Response<T>
+    public abstract class Response<T> : NullableResponse<T>
 #pragma warning restore AZC0012 // Avoid single word type names
 #pragma warning restore SA1649 // File name should match first type name
     {
-        /// <summary>
-        /// Returns the HTTP response returned by the service.
-        /// </summary>
-        /// <returns>The HTTP response returned by the service.</returns>
-        public abstract Response GetRawResponse();
-
-        /// <summary>
-        /// Gets the value returned by the service.
-        /// </summary>
-        public abstract T Value { get; }
+        /// <inheritdoc />
+        [EditorBrowsable(EditorBrowsableState.Never)]
+        public override bool HasValue => true;
 
         /// <summary>
         /// Returns the value of this <see cref="Response{T}"/> object.
@@ -52,11 +45,5 @@ public static implicit operator T(Response<T> response)
         /// <inheritdoc />
         [EditorBrowsable(EditorBrowsableState.Never)]
         public override int GetHashCode() => base.GetHashCode();
-
-        /// <inheritdoc />
-        public override string ToString()
-        {
-            return $"Status: {GetRawResponse().Status}, Value: {Value}";
-        }
     }
 }

sdk/core/Azure.Core/src/Shared/NoBodyResponseOfT.cs

@@ -5,6 +5,9 @@
 
 namespace Azure
 {
+    /// <summary>
+    /// NOTE: This type should not be used going forward. Use NoValueResponse{T} instead.
+    /// </summary>
 #pragma warning disable SA1649 // File name should match first type name
     internal class NoBodyResponse<T> : Response<T>
 #pragma warning restore SA1649 // File name should match first type name
@@ -16,6 +19,9 @@ public NoBodyResponse(Response response)
             _response = response;
         }
 
+        /// <inheritdoc />
+        public override bool HasValue => false;
+
         public override T Value
         {
             get