From a218c3bea67ddd01439c112e45bd6394216377f1 Mon Sep 17 00:00:00 2001 From: Pranav K Date: Wed, 30 Sep 2020 13:45:18 -0700 Subject: [PATCH] Add docs to CookiePolicy (#26446) * Add docs to CookiePolicy Contributes to https://github.com/dotnet/aspnetcore/issues/26397 * Apply suggestions from code review --- .../CookiePolicy/src/AppendCookieContext.cs | 41 ++++++++++++++++++- .../src/CookiePolicyMiddleware.cs | 23 ++++++++++- .../CookiePolicy/src/CookiePolicyOptions.cs | 4 ++ .../CookiePolicy/src/DeleteCookieContext.cs | 36 +++++++++++++++- .../CookiePolicy/src/HttpOnlyPolicy.cs | 14 ++++++- .../Microsoft.AspNetCore.CookiePolicy.csproj | 4 +- 6 files changed, 116 insertions(+), 6 deletions(-) diff --git a/src/Security/CookiePolicy/src/AppendCookieContext.cs b/src/Security/CookiePolicy/src/AppendCookieContext.cs index bbb4899c04..35b9c9605c 100644 --- a/src/Security/CookiePolicy/src/AppendCookieContext.cs +++ b/src/Security/CookiePolicy/src/AppendCookieContext.cs @@ -1,12 +1,23 @@ // Copyright (c) .NET Foundation. All rights reserved. // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. +using Microsoft.AspNetCore.Builder; using Microsoft.AspNetCore.Http; namespace Microsoft.AspNetCore.CookiePolicy { + /// + /// Context for that allows changes to the cookie prior to being appended. + /// public class AppendCookieContext { + /// + /// Initializes a new instance of . + /// + /// The request . + /// The passed to the cookie policy. + /// The cookie name. + /// The cookie value. public AppendCookieContext(HttpContext context, CookieOptions options, string name, string value) { Context = context; @@ -15,12 +26,40 @@ namespace Microsoft.AspNetCore.CookiePolicy CookieValue = value; } + /// + /// Gets the . + /// public HttpContext Context { get; } + + /// + /// Gets the . + /// public CookieOptions CookieOptions { get; } + + /// + /// Gets or sets the cookie name. + /// public string CookieName { get; set; } + + /// + /// Gets or sets the cookie value. + /// public string CookieValue { get; set; } + + /// + /// Gets a value that determines if cookie consent is required before setting this cookie. + /// public bool IsConsentNeeded { get; internal set; } + + /// + /// Gets a value that determines if cookie consent was provided. + /// public bool HasConsent { get; internal set; } + + /// + /// Gets or sets a value that determines if the cookie can be appended. If set to , + /// the cookie is not appended. + /// public bool IssueCookie { get; set; } } -} \ No newline at end of file +} diff --git a/src/Security/CookiePolicy/src/CookiePolicyMiddleware.cs b/src/Security/CookiePolicy/src/CookiePolicyMiddleware.cs index 1a810b7d55..0c99fb7450 100644 --- a/src/Security/CookiePolicy/src/CookiePolicyMiddleware.cs +++ b/src/Security/CookiePolicy/src/CookiePolicyMiddleware.cs @@ -12,11 +12,20 @@ using Microsoft.Extensions.Options; namespace Microsoft.AspNetCore.CookiePolicy { + /// + /// Initializes a new instance of . + /// public class CookiePolicyMiddleware { private readonly RequestDelegate _next; private readonly ILogger _logger; + /// + /// Initializes a new instance of . + /// + /// A reference to the next item in the application pipeline. + /// Accessor to . + /// The . public CookiePolicyMiddleware(RequestDelegate next, IOptions options, ILoggerFactory factory) { Options = options.Value; @@ -24,6 +33,11 @@ namespace Microsoft.AspNetCore.CookiePolicy _logger = factory.CreateLogger(); } + /// + /// Initializes a new instance of . + /// + /// A reference to the next item in the application pipeline. + /// Accessor to . public CookiePolicyMiddleware(RequestDelegate next, IOptions options) { Options = options.Value; @@ -31,8 +45,15 @@ namespace Microsoft.AspNetCore.CookiePolicy _logger = NullLogger.Instance; } + /// + /// Gets or sets the . + /// public CookiePolicyOptions Options { get; set; } + /// + /// Invokes the middleware. + /// + /// The . public Task Invoke(HttpContext context) { var feature = context.Features.Get() ?? new ResponseCookiesFeature(context.Features); @@ -53,4 +74,4 @@ namespace Microsoft.AspNetCore.CookiePolicy public IResponseCookies Cookies { get; } } } -} \ No newline at end of file +} diff --git a/src/Security/CookiePolicy/src/CookiePolicyOptions.cs b/src/Security/CookiePolicy/src/CookiePolicyOptions.cs index 56e5998808..dde29da80f 100644 --- a/src/Security/CookiePolicy/src/CookiePolicyOptions.cs +++ b/src/Security/CookiePolicy/src/CookiePolicyOptions.cs @@ -27,6 +27,10 @@ namespace Microsoft.AspNetCore.Builder /// public CookieSecurePolicy Secure { get; set; } = CookieSecurePolicy.None; + /// + /// Gets or sets the that is used to track if the user consented to the + /// cookie use policy. + /// public CookieBuilder ConsentCookie { get; set; } = new CookieBuilder() { Name = ".AspNet.Consent", diff --git a/src/Security/CookiePolicy/src/DeleteCookieContext.cs b/src/Security/CookiePolicy/src/DeleteCookieContext.cs index fd79ea8d4b..3149d7fbdf 100644 --- a/src/Security/CookiePolicy/src/DeleteCookieContext.cs +++ b/src/Security/CookiePolicy/src/DeleteCookieContext.cs @@ -1,12 +1,22 @@ // Copyright (c) .NET Foundation. All rights reserved. // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. +using Microsoft.AspNetCore.Builder; using Microsoft.AspNetCore.Http; namespace Microsoft.AspNetCore.CookiePolicy { + /// + /// Context for that allows changes to the cookie prior to being deleted. + /// public class DeleteCookieContext { + /// + /// Initializes a new instance of . + /// + /// The request . + /// The passed to the cookie policy. + /// The cookie name to be deleted. public DeleteCookieContext(HttpContext context, CookieOptions options, string name) { Context = context; @@ -14,11 +24,35 @@ namespace Microsoft.AspNetCore.CookiePolicy CookieName = name; } + /// + /// Gets the . + /// public HttpContext Context { get; } + + /// + /// Gets the . + /// public CookieOptions CookieOptions { get; } + + /// + /// Gets or sets the cookie name. + /// public string CookieName { get; set; } + + /// + /// Gets a value that determines if cookie consent is required before setting this cookie. + /// public bool IsConsentNeeded { get; internal set; } + + /// + /// Gets a value that determines if cookie consent was provided. + /// public bool HasConsent { get; internal set; } + + /// + /// Gets or sets a value that determines if the cookie can be deleted. If set to , + /// cookie deletion is suppressed. + /// public bool IssueCookie { get; set; } } -} \ No newline at end of file +} diff --git a/src/Security/CookiePolicy/src/HttpOnlyPolicy.cs b/src/Security/CookiePolicy/src/HttpOnlyPolicy.cs index 82305f4754..bdabb4129b 100644 --- a/src/Security/CookiePolicy/src/HttpOnlyPolicy.cs +++ b/src/Security/CookiePolicy/src/HttpOnlyPolicy.cs @@ -3,9 +3,21 @@ namespace Microsoft.AspNetCore.CookiePolicy { + /// + /// Describes the HttpOnly behavior for cookies. + /// public enum HttpOnlyPolicy { + /// + /// The cookie does not have a configured HttpOnly behavior. This cookie can be accessed by + /// JavaScript document.cookie API. + /// None, + + /// + /// The cookie is configured with a HttpOnly attribute. This cookie inaccessible to the + /// JavaScript document.cookie API. + /// Always } -} \ No newline at end of file +} diff --git a/src/Security/CookiePolicy/src/Microsoft.AspNetCore.CookiePolicy.csproj b/src/Security/CookiePolicy/src/Microsoft.AspNetCore.CookiePolicy.csproj index d401e8d69f..a47a6f4d36 100644 --- a/src/Security/CookiePolicy/src/Microsoft.AspNetCore.CookiePolicy.csproj +++ b/src/Security/CookiePolicy/src/Microsoft.AspNetCore.CookiePolicy.csproj @@ -1,10 +1,10 @@ - + ASP.NET Core cookie policy classes to control the behavior of cookies. $(DefaultNetCoreTargetFramework) true - $(NoWarn);CS1591 + $(NoWarn.Replace('1591', '')) true aspnetcore false