Documentation update

Author: github-actions

docs/migrations/migration8/index.html

@@ -1187,6 +1187,58 @@ <h3 id="33-added-capability-to-reference-object-graph-types-from-their-implement
 <span class="token punctuation">{</span>
     <span class="token keyword">public</span> <span class="token return-type class-name"><span class="token keyword">string</span></span> Name <span class="token punctuation">{</span> <span class="token keyword">get</span><span class="token punctuation">;</span> <span class="token keyword">set</span><span class="token punctuation">;</span> <span class="token punctuation">}</span>
 <span class="token punctuation">}</span></code></pre></div>
+<h3 id="34-deprecated-element-detection-and-validation-support-v86" style="position:relative;"><a href="#34-deprecated-element-detection-and-validation-support-v86" aria-label="34 deprecated element detection and validation support v86 permalink" class="anchor before"><svg aria-hidden="true" focusable="false" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>34. Deprecated element detection and validation support (v8.6+)</h3>
+<p>Two new classes have been added to help manage deprecated schema elements more effectively:
+<a href="src/GraphQL/Utilities/Visitors/Custom/DeprecatedTypeReferenceVisitor.cs"><code class="language-text">DeprecatedTypeReferenceVisitor</code></a> and
+<a href="src/GraphQL/Validation/Rules.Custom/DeprecatedElementsValidationRule.cs"><code class="language-text">DeprecatedElementsValidationRule</code></a>.
+These classes work together to provide comprehensive deprecation management at both the schema and query validation levels.</p>
+<p>The <a href="src/GraphQL/Utilities/Visitors/Custom/DeprecatedTypeReferenceVisitor.cs"><code class="language-text">DeprecatedTypeReferenceVisitor</code></a> is a schema visitor that identifies non-deprecated fields that directly reference deprecated types during schema initialization. This helps maintain schema consistency by flagging potential issues where deprecated types are still being referenced by active fields.</p>
+<p>The <a href="src/GraphQL/Validation/Rules.Custom/DeprecatedElementsValidationRule.cs"><code class="language-text">DeprecatedElementsValidationRule</code></a> is an abstract validation rule that identifies deprecated fields, arguments, and types referenced in GraphQL documents during query validation. It provides abstract methods that can be overridden to implement custom handling of deprecated element usage, such as logging warnings or collecting metrics.</p>
+<div class="gatsby-highlight" data-language="csharp"><pre class="language-csharp"><code class="language-csharp"><span class="token comment">// Create a custom validation rule to handle deprecated element usage during query validation</span>
+<span class="token keyword">public</span> <span class="token keyword">class</span> <span class="token class-name">LoggingDeprecatedElementsRule</span> <span class="token punctuation">:</span> <span class="token type-list"><span class="token class-name">DeprecatedElementsValidationRule</span></span>
+<span class="token punctuation">{</span>
+    <span class="token keyword">private</span> <span class="token keyword">readonly</span> <span class="token class-name">ILogger<span class="token punctuation">&lt;</span>LoggingDeprecatedElementsRule<span class="token punctuation">></span></span> _logger<span class="token punctuation">;</span>
+
+    <span class="token keyword">public</span> <span class="token function">LoggingDeprecatedElementsRule</span><span class="token punctuation">(</span><span class="token class-name">ILogger<span class="token punctuation">&lt;</span>LoggingDeprecatedElementsRule<span class="token punctuation">></span></span> logger<span class="token punctuation">)</span>
+    <span class="token punctuation">{</span>
+        _logger <span class="token operator">=</span> logger<span class="token punctuation">;</span>
+    <span class="token punctuation">}</span>
+
+    <span class="token keyword">protected</span> <span class="token keyword">override</span> <span class="token return-type class-name">ValueTask</span> <span class="token function">OnDeprecatedFieldReferencedAsync</span><span class="token punctuation">(</span><span class="token class-name">ValidationContext</span> context<span class="token punctuation">,</span> <span class="token class-name">GraphQLField</span> fieldNode<span class="token punctuation">,</span> <span class="token class-name">FieldType</span> fieldDefinition<span class="token punctuation">,</span> <span class="token class-name">IGraphType</span> parentType<span class="token punctuation">)</span>
+    <span class="token punctuation">{</span>
+        _logger<span class="token punctuation">.</span><span class="token function">LogWarning</span><span class="token punctuation">(</span><span class="token string">"Deprecated field '{ParentType}.{FieldName}' was used: {DeprecationReason}"</span><span class="token punctuation">,</span>
+            parentType<span class="token punctuation">.</span>Name<span class="token punctuation">,</span> fieldDefinition<span class="token punctuation">.</span>Name<span class="token punctuation">,</span> fieldDefinition<span class="token punctuation">.</span>DeprecationReason<span class="token punctuation">)</span><span class="token punctuation">;</span>
+        <span class="token keyword">return</span> <span class="token keyword">default</span><span class="token punctuation">;</span>
+    <span class="token punctuation">}</span>
+
+    <span class="token keyword">protected</span> <span class="token keyword">override</span> <span class="token return-type class-name">ValueTask</span> <span class="token function">OnDeprecatedFieldArgumentReferencedAsync</span><span class="token punctuation">(</span><span class="token class-name">ValidationContext</span> context<span class="token punctuation">,</span> <span class="token class-name">GraphQLArgument</span> argumentNode<span class="token punctuation">,</span> <span class="token class-name">QueryArgument</span> argumentDefinition<span class="token punctuation">,</span> <span class="token class-name">FieldType</span> fieldDefinition<span class="token punctuation">,</span> <span class="token class-name">IGraphType</span> parentType<span class="token punctuation">)</span>
+    <span class="token punctuation">{</span>
+        _logger<span class="token punctuation">.</span><span class="token function">LogWarning</span><span class="token punctuation">(</span><span class="token string">"Deprecated argument '{ParentType}.{FieldName}.{ArgumentName}' was used: {DeprecationReason}"</span><span class="token punctuation">,</span>
+            parentType<span class="token punctuation">.</span>Name<span class="token punctuation">,</span> fieldDefinition<span class="token punctuation">.</span>Name<span class="token punctuation">,</span> argumentDefinition<span class="token punctuation">.</span>Name<span class="token punctuation">,</span> argumentDefinition<span class="token punctuation">.</span>DeprecationReason<span class="token punctuation">)</span><span class="token punctuation">;</span>
+        <span class="token keyword">return</span> <span class="token keyword">default</span><span class="token punctuation">;</span>
+    <span class="token punctuation">}</span>
+
+    <span class="token keyword">protected</span> <span class="token keyword">override</span> <span class="token return-type class-name">ValueTask</span> <span class="token function">OnDeprecatedDirectiveArgumentReferencedAsync</span><span class="token punctuation">(</span><span class="token class-name">ValidationContext</span> context<span class="token punctuation">,</span> <span class="token class-name">GraphQLArgument</span> argumentNode<span class="token punctuation">,</span> <span class="token class-name">QueryArgument</span> argumentDefinition<span class="token punctuation">,</span> <span class="token class-name">Directive</span> directiveDefinition<span class="token punctuation">)</span>
+    <span class="token punctuation">{</span>
+        _logger<span class="token punctuation">.</span><span class="token function">LogWarning</span><span class="token punctuation">(</span><span class="token string">"Deprecated directive argument '@{DirectiveName}.{ArgumentName}' was used: {DeprecationReason}"</span><span class="token punctuation">,</span>
+            directiveDefinition<span class="token punctuation">.</span>Name<span class="token punctuation">,</span> argumentDefinition<span class="token punctuation">.</span>Name<span class="token punctuation">,</span> argumentDefinition<span class="token punctuation">.</span>DeprecationReason<span class="token punctuation">)</span><span class="token punctuation">;</span>
+        <span class="token keyword">return</span> <span class="token keyword">default</span><span class="token punctuation">;</span>
+    <span class="token punctuation">}</span>
+
+    <span class="token keyword">protected</span> <span class="token keyword">override</span> <span class="token return-type class-name">ValueTask</span> <span class="token function">OnDeprecatedTypeReferencedAsync</span><span class="token punctuation">(</span><span class="token class-name">ValidationContext</span> context<span class="token punctuation">,</span> <span class="token class-name">GraphQLNamedType</span> typeConditionNode<span class="token punctuation">,</span> <span class="token class-name">IGraphType</span> typeDefinition<span class="token punctuation">)</span>
+    <span class="token punctuation">{</span>
+        _logger<span class="token punctuation">.</span><span class="token function">LogWarning</span><span class="token punctuation">(</span><span class="token string">"Deprecated type '{TypeName}' was used: {DeprecationReason}"</span><span class="token punctuation">,</span>
+            typeDefinition<span class="token punctuation">.</span>Name<span class="token punctuation">,</span> typeDefinition<span class="token punctuation">.</span>DeprecationReason<span class="token punctuation">)</span><span class="token punctuation">;</span>
+        <span class="token keyword">return</span> <span class="token keyword">default</span><span class="token punctuation">;</span>
+    <span class="token punctuation">}</span>
+<span class="token punctuation">}</span>
+
+<span class="token comment">// Register the schema visitor and validation rule</span>
+services<span class="token punctuation">.</span><span class="token function">AddGraphQL</span><span class="token punctuation">(</span>b <span class="token operator">=></span> b
+    <span class="token punctuation">.</span><span class="token generic-method"><span class="token function">AddSchema</span><span class="token generic class-name"><span class="token punctuation">&lt;</span>MySchema<span class="token punctuation">></span></span></span><span class="token punctuation">(</span><span class="token punctuation">)</span>
+    <span class="token punctuation">.</span><span class="token generic-method"><span class="token function">AddSchemaVisitor</span><span class="token generic class-name"><span class="token punctuation">&lt;</span>DeprecatedTypeReferenceVisitor<span class="token punctuation">></span></span></span><span class="token punctuation">(</span><span class="token punctuation">)</span>
+    <span class="token punctuation">.</span><span class="token generic-method"><span class="token function">AddValidationRule</span><span class="token generic class-name"><span class="token punctuation">&lt;</span>LoggingDeprecatedElementsRule<span class="token punctuation">></span></span></span><span class="token punctuation">(</span><span class="token punctuation">)</span>
+<span class="token punctuation">)</span><span class="token punctuation">;</span></code></pre></div>
 <h2 id="breaking-changes" style="position:relative;"><a href="#breaking-changes" aria-label="breaking changes permalink" class="anchor before"><svg aria-hidden="true" focusable="false" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Breaking Changes</h2>
 <h3 id="1-query-type-is-required" style="position:relative;"><a href="#1-query-type-is-required" aria-label="1 query type is required permalink" class="anchor before"><svg aria-hidden="true" focusable="false" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>1. Query type is required</h3>
 <p>Pursuant to the GraphQL specification, a query type is required for any schema.