Skip to content

Commit b7f9cd2

Browse files
StephenMolloyStephenMolloy
committed
Documentation updates.
1 parent 9c32243 commit b7f9cd2

4 files changed

+266
-86
lines changed

‎Readme.md

+6
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,12 @@
11
## Introduction
22
OutputCacheModule is ASP.NET’s default handler for storing the generated output of pages, controls, and HTTP responses. This content can then be reused when appropriate to improve performance. Prior to the .NET Framework 4.6.2, the OutputCache Module did not support async read/write to the storage. You can find more details on [this blog post](https://blogs.msdn.microsoft.com/webdev/2016/12/05/introducing-the-asp-net-async-outputcache-module/).
33

4+
## Key Benefits
5+
- Asynchronous operations for improved scalability
6+
- Better performance in high-traffic applications
7+
- Multiple storage provider options (SQL Server, Azure Cosmos DB)
8+
- Compatible with existing ASP.NET output cache APIs
9+
410
## How to build
511
1. Open a [VS developer command prompt](https://docs.microsoft.com/en-us/dotnet/framework/tools/developer-command-prompt-for-vs)
612
2. Run build.cmd. This will build Nuget packages and run all the unit tests.

‎docs/CosmosDBTableAsyncOutputCacheProvider.md

+88-31
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,88 @@
1-
# How to use the CosmosDB OutputCache Provider
2-
1. Target your application to 4.6.2+.
3-
4-
The OutputCacheProviderAsync interface was introduced in .NET Framework 4.6.2, therefore you need to target your application to .NET Framework 4.6.2 or above in order to use the Async OutputCache Module. Download the [.NET Framework 4.6.2 Developer Pack](https://www.microsoft.com/en-us/download/details.aspx?id=53321) if you do not have it installed yet and update your application’s web.config targetFrameworks attributes as demonstrated below:
5-
```xml
6-
<system.web>
7-
<compilation debug="true" targetFramework="4.6.2"/>
8-
<httpRuntime targetFramework="4.6.2"/>
9-
</system.web>
10-
```
11-
12-
2. Add the [Microsoft.AspNet.OutputCache.OutputCacheModuleAsync](https://www.nuget.org/packages/Microsoft.AspNet.OutputCache.OutputCacheModuleAsync/) NuGet package.
13-
3. Add the [Microsoft.AspNet.OutputCache.CosmosDBTableAsyncOutputCacheProvider](https://www.nuget.org/packages/Microsoft.AspNet.OutputCache.CosmosDBTableAsyncOutputCacheProvider/) NuGet package.
14-
15-
Use the NuGet package manager to install the Microsoft.AspNet.OutputCache.CosmosDBTableAsyncOutputCacheProvider packages. This will add a reference to Microsoft.AspNet.OutputCache.CosmosDBTableAsyncOutputCacheProvider.dll and add the following configuration into the web.config file.
16-
```xml
17-
<system.web>
18-
<caching>
19-
<outputCache defaultProvider="CosmosDBTableAsyncOutputCacheProvider">
20-
<providers>
21-
<add name="CosmosDBTableAsyncOutputCacheProvider" connectionStringName="StorageConnectionStringForOutputCacheProvider" tableName="[TableName]"
22-
type="Microsoft.AspNet.OutputCache.CosmosDBTableAsyncOutputCacheProvider.CosmosDBTableAsyncOutputCacheProvider, Microsoft.AspNet.OutputCache.CosmosDBTableAsyncOutputCacheProvider, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
23-
</providers>
24-
</outputCache>
25-
</caching>
26-
</system.web>
27-
```
28-
29-
1. *TableName* - The name of the table to use for the provider.
30-
31-
Now your applications will start using Async OutputCache Module with the CosmosDB OutputCache Provider.
1+
# Microsoft.AspNet.OutputCache.CosmosDBTableAsyncOutputCacheProvider
2+
3+
## Overview
4+
5+
`CosmosDBTableAsyncOutputCacheProvider` is an asynchronous output cache provider for ASP.NET that uses Azure Cosmos DB Table API as the backend storage. This allows for distributed caching across web applications hosted in different regions, providing high availability and low latency.
6+
7+
## Features
8+
9+
- Asynchronous operations for improved scalability via integration with [OutputCacheModuleAsync](https://www.nuget.org/packages/Microsoft.AspNet.OutputCache.OutputCacheModuleAsync/)
10+
- Distributed caching support using Azure Cosmos DB Table API
11+
12+
## Requirements
13+
14+
- .NET Framework 4.6.2 or later (Full framework - not .NET Core)
15+
- Azure Cosmos DB account with Table API
16+
17+
## Usage
18+
19+
1. **Target your application to .NET Framework 4.6.2 or later**
20+
21+
The `OutputCacheProviderAsync` interface was introduced in .NET Framework 4.6.2, therefore you need to target your application to .NET Framework 4.6.2 or above in order to use the Async OutputCache Module. Download the [.NET Framework 4.6.2 Developer Pack](https://www.microsoft.com/en-us/download/details.aspx?id=53321) if you do not have it installed yet and update your application's `web.config` targetFramework attributes as demonstrated below:
22+
23+
```xml
24+
<system.web>
25+
<compilation debug="true" targetFramework="4.6.2"/>
26+
<httpRuntime targetFramework="4.6.2"/>
27+
</system.web>
28+
```
29+
30+
1. **Add NuGet packages**
31+
32+
Use the NuGet package manager to install:
33+
34+
- [Microsoft.AspNet.OutputCache.OutputCacheModuleAsync](https://www.nuget.org/packages/Microsoft.AspNet.OutputCache.OutputCacheModuleAsync/)
35+
- [Microsoft.AspNet.OutputCache.CosmosDBTableAsyncOutputCacheProvider](https://www.nuget.org/packages/Microsoft.AspNet.OutputCache.CosmosDBTableAsyncOutputCacheProvider/)
36+
37+
This will add a reference to the necessary assemblies and add the following configuration into the `web.config` file.
38+
39+
```xml
40+
<system.web>
41+
<caching>
42+
<outputCache defaultProvider="CosmosDBTableAsyncOutputCacheProvider">
43+
<providers>
44+
<add name="CosmosDBTableAsyncOutputCacheProvider" connectionStringName="StorageConnectionStringForOutputCacheProvider" tableName="[TableName]"
45+
type="Microsoft.AspNet.OutputCache.CosmosDBTableAsyncOutputCacheProvider.CosmosDBTableAsyncOutputCacheProvider, Microsoft.AspNet.OutputCache.CosmosDBTableAsyncOutputCacheProvider, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
46+
</providers>
47+
</outputCache>
48+
</caching>
49+
</system.web>
50+
```
51+
52+
1. **Further Configuration**
53+
54+
Be sure that `web.config` includes both the connection string and the `OutputCacheModuleAsync` configuration:
55+
56+
```xml
57+
<configuration>
58+
<appSettings>
59+
<add key="CosmosDBEndpoint" value="https://<your-account>.documents.azure.com:443/" />
60+
<add key="CosmosDBKey" value="<your-account-key>" />
61+
<add key="CosmosDBDatabase" value="OutputCache" />
62+
<add key="CosmosDBTable" value="CacheEntries" />
63+
</appSettings>
64+
65+
<system.webServer>
66+
<modules>
67+
<remove name="OutputCache" />
68+
<add name="OutputCache"
69+
type="Microsoft.AspNet.OutputCache.OutputCacheModuleAsync, Microsoft.AspNet.OutputCache.OutputCacheModuleAsync"
70+
preCondition="integratedMode" />
71+
</modules>
72+
</system.webServer>
73+
</configuration>
74+
```
75+
76+
## Updates
77+
78+
### v1.1.1
79+
80+
- Dependency version updates.
81+
82+
### v1.1.0
83+
84+
- Migrated to using `Azure.Data.Tables` SDK for Cosmos access.
85+
86+
### v1.0.0
87+
88+
- Initial release.

‎docs/OutputCacheModuleAsync.md

+93-24
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,93 @@
1-
# How to use the Async OutputCache Module
2-
1. Target your application to 4.6.2+.
3-
4-
The OutputCacheProviderAsync interface was introduced in .NET Framework 4.6.2, therefore you need to target your application to .NET Framework 4.6.2 or above in order to use the Async OutputCache Module. Download the [.NET Framework 4.6.2 Developer Pack](https://www.microsoft.com/en-us/download/details.aspx?id=53321) if you do not have it installed yet and update your application’s web.config targetFrameworks attributes as demonstrated below:
5-
```xml
6-
<system.web>
7-
<compilation debug="true" targetFramework="4.6.2"/>
8-
<httpRuntime targetFramework="4.6.2"/>
9-
</system.web>
10-
```
11-
12-
2. Add the [Microsoft.AspNet.OutputCache.OutputCacheModuleAsync](https://www.nuget.org/packages/Microsoft.AspNet.OutputCache.OutputCacheModuleAsync/) NuGet package.
13-
14-
Use the NuGet package manager to install the Microsoft.AspNet.OutputCache.OutputCacheModuleAsync package. This will add a reference to the Microsoft.AspNet.OutputCache.OutputCacheModuleAsync.dll and add the following configuration into the web.config file.
15-
```xml
16-
<system.webServer>
17-
<modules>
18-
<remove name="OutputCache"/>
19-
<add name="OutputCache" type="Microsoft.AspNet.OutputCache.OutputCacheModuleAsync, Microsoft.AspNet.OutputCache.OutputCacheModuleAsync" preCondition="integratedMode"/>
20-
</modules>
21-
</system.webServer>
22-
```
23-
24-
Now your applications will start using Async OutputCache Module. If no outputcacheprovider is specified in web.config, the module will use a default synchronous in-memory provider, with that you won’t get the async benefits. Please consider using one of the OutputCache providers that builds on this package, or [implement an async OutputCache Provider of your own](https://devblogs.microsoft.com/dotnet/introducing-the-asp-net-async-outputcache-module/#how-to-implement-an-async-outputcache-provider).
1+
# Microsoft.AspNet.OutputCache.OutputCacheModuleAsync
2+
3+
## Overview
4+
5+
`OutputCacheModuleAsync` is an asynchronous implementation of ASP.NET's (4.X) output caching module. It provides performance improvements for web applications by caching the output of HTTP responses to reduce the need to execute the same request processing multiple times.
6+
7+
## Features
8+
9+
- Asynchronous caching operations for better scalability
10+
- Conditional request processing (If-Modified-Since, If-None-Match)
11+
- Customizable cache expiration policies
12+
- VaryBy parameter support (VaryByHeader, VaryByParam, VaryByCustom)
13+
14+
## Integrations
15+
16+
The `OutputCacheModuleAsync` is designed to work with any cache provider that implements the `OutputCacheProviderAsync` base class, allowing you to store cached content in various backends like SQL Server, Redis, or custom storage solutions. Two such providers are provided from the this same [repository](https://github.com/aspnet/AspNetOutputCache/):
17+
- [SQLAsyncOutputCacheProvider](https://www.nuget.org/packages/Microsoft.AspNet.OutputCache.SQLAsyncOutputCacheProvider/)
18+
- [CosmosDBTableAsyncOutputCacheProvider](https://www.nuget.org/packages/Microsoft.AspNet.OutputCache.CosmosDBTableAsyncOutputCacheProvider/)
19+
20+
## Requirements
21+
22+
- .NET Framework 4.6.2 or later (Full framework - not .NET Core)
23+
24+
## Usage
25+
26+
1. **Target your application to .NET Framework 4.6.2 or later**
27+
28+
The `OutputCacheProviderAsync` interface was introduced in .NET Framework 4.6.2, therefore you need to target your application to .NET Framework 4.6.2 or above in order to use the Async OutputCache Module. Download the [.NET Framework 4.6.2 Developer Pack](https://www.microsoft.com/en-us/download/details.aspx?id=53321) if you do not have it installed yet and update your application’s `web.config` targetFramework attributes as demonstrated below:
29+
30+
```xml
31+
<system.web>
32+
<compilation debug="true" targetFramework="4.6.2"/>
33+
<httpRuntime targetFramework="4.6.2"/>
34+
</system.web>
35+
```
36+
37+
1. **Add the Microsoft.AspNet.OutputCache.OutputCacheModuleAsync NuGet package**
38+
39+
Use the NuGet package manager to install the [Microsoft.AspNet.OutputCache.OutputCacheModuleAsync](https://www.nuget.org/packages/Microsoft.AspNet.OutputCache.OutputCacheModuleAsync/) package. This will add a reference to the `Microsoft.AspNet.OutputCache.OutputCacheModuleAsync.dll` and add the following configuration into the `web.config` file.
40+
41+
```xml
42+
<system.webServer>
43+
<modules>
44+
<remove name="OutputCache"/>
45+
<add name="OutputCache" type="Microsoft.AspNet.OutputCache.OutputCacheModuleAsync, Microsoft.AspNet.OutputCache.OutputCacheModuleAsync" preCondition="integratedMode"/>
46+
</modules>
47+
</system.webServer>
48+
```
49+
50+
1. **Enable Output Caching in your application**
51+
52+
Configure web forms applications for output caching by adding the following to the applications `web.config` file:
53+
54+
```xml
55+
<system.web>
56+
<caching>
57+
<outputCache enableOutputCache="true" />
58+
<outputCacheSettings>
59+
<outputCacheProfiles>
60+
<add name="CacheFor60Seconds" duration="60" varyByParam="none" />
61+
</outputCacheProfiles>
62+
</outputCacheSettings>
63+
</caching>
64+
</system.web>
65+
```
66+
67+
You can also enable output caching in your MVC applications by adding the `OutputCache` attribute to your controllers or actions. For example:
68+
```csharp
69+
[OutputCache(Duration = 60, VaryByParam = "none")]
70+
public ActionResult Index()
71+
{
72+
// This content will be cached for 60 seconds
73+
return View();
74+
}
75+
```
76+
Now the applications will start using the Async OutputCache Module.
77+
78+
If there are special requirements of a cache store that are not met by these released providers, consider [implementing an async OutputCache Provider of your own](https://devblogs.microsoft.com/dotnet/introducing-the-asp-net-async-outputcache-module/#how-to-implement-an-async-outputcache-provider).
79+
80+
## Updates
81+
82+
### v1.0.4
83+
84+
- Bug Fix: Fixed an issue with cache expiration policies not being applied correctly.
85+
86+
### v1.0.1
87+
88+
- Added checks and support for kernel cache APIs in several places to ensure proper handling of kernel cache entries. Also updated the `DependencyRemovedCallback` method to invalidate kernel cache entries when dependencies change.
89+
- Added `[Serializable]` attributes to several classes to ensure they can be serialized correctly, which helps in caching scenarios.
90+
91+
### v1.0.0
92+
93+
- Initial release.

‎docs/SQLAsyncOutputCacheProvider.md

+79-31
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,79 @@
1-
# How to use the SQLAsync OutputCache Provider
2-
1. Target your application to 4.6.2+.
3-
4-
The OutputCacheProviderAsync interface was introduced in .NET Framework 4.6.2, therefore you need to target your application to .NET Framework 4.6.2 or above in order to use the Async OutputCache Module. Download the [.NET Framework 4.6.2 Developer Pack](https://www.microsoft.com/en-us/download/details.aspx?id=53321) if you do not have it installed yet and update your application’s web.config targetFrameworks attributes as demonstrated below:
5-
```xml
6-
<system.web>
7-
<compilation debug="true" targetFramework="4.6.2"/>
8-
<httpRuntime targetFramework="4.6.2"/>
9-
</system.web>
10-
```
11-
12-
2. Add the [Microsoft.AspNet.OutputCache.OutputCacheModuleAsync](https://www.nuget.org/packages/Microsoft.AspNet.OutputCache.OutputCacheModuleAsync/) NuGet package.
13-
3. Add the [Microsoft.AspNet.OutputCache.SQLAsyncOutputCacheProvider](https://www.nuget.org/packages/Microsoft.AspNet.OutputCache.SQLAsyncOutputCacheProvider/) NuGet package.
14-
15-
Use the NuGet package manager to install the Microsoft.AspNet.OutputCache.SQLAsyncOutputCacheProvider packages. This will add a reference to Microsoft.AspNet.OutputCache.SQLAsyncOutputCacheProvider.dll and add the following configuration into the web.config file.
16-
```xml
17-
<system.web>
18-
<caching>
19-
<outputCache defaultProvider="SQLAsyncOutputCacheProvider">
20-
<providers>
21-
<add name="SQLAsyncOutputCacheProvider" connectionStringName="DefaultConnection" UseInMemoryTable="[true|false]"
22-
type="Microsoft.AspNet.OutputCache.SQLAsyncOutputCacheProvider.SQLAsyncOutputCacheProvider, Microsoft.AspNet.OutputCache.SQLAsyncOutputCacheProvider, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
23-
</providers>
24-
</outputCache>
25-
</caching>
26-
</system.web>
27-
```
28-
29-
1. *UseInMemoryTable* - Indicates whether to use Sql server 2016 In-Memory OLTP for the provider.
30-
31-
Now your applications will start using Async OutputCache Module with the SQLAsync OutputCache Provider.
1+
# Microsoft.AspNet.OutputCache.SQLAsyncOutputCacheProvider
2+
3+
## Overview
4+
5+
`SQLAsyncOutputCacheProvider` is an asynchronous SQL Server-based output cache provider for ASP.NET. It enables storing ASP.NET output cache data in a SQL Server database, allowing for distributed caching across web farm scenarios.
6+
7+
## Features
8+
9+
- Asynchronous database operations for improved scalability via integration with [OutputCacheModuleAsync](https://www.nuget.org/packages/Microsoft.AspNet.OutputCache.OutputCacheModuleAsync/)
10+
- Traditional or In-Memory OLTP tables for cache storage
11+
12+
## Requirements
13+
14+
- .NET Framework 4.6.2 or later (Full framework - not .NET Core)
15+
- SQL Server 2014 (12.0) or later for In-Memory OLTP support
16+
17+
## Usage
18+
19+
1. **Target your application to .NET Framework 4.6.2 or later**
20+
21+
The `OutputCacheProviderAsync` interface was introduced in .NET Framework 4.6.2, therefore you need to target your application to .NET Framework 4.6.2 or above in order to use the Async OutputCache Module. Download the [.NET Framework 4.6.2 Developer Pack](https://www.microsoft.com/en-us/download/details.aspx?id=53321) if you do not have it installed yet and update your application's `web.config` targetFramework attributes as demonstrated below:
22+
23+
```xml
24+
<system.web>
25+
<compilation debug="true" targetFramework="4.6.2"/>
26+
<httpRuntime targetFramework="4.6.2"/>
27+
</system.web>
28+
```
29+
30+
1. **Add NuGet packages**
31+
32+
Use the NuGet package manager to install:
33+
34+
- [Microsoft.AspNet.OutputCache.OutputCacheModuleAsync](https://www.nuget.org/packages/Microsoft.AspNet.OutputCache.OutputCacheModuleAsync/)
35+
- [Microsoft.AspNet.OutputCache.SQLAsyncOutputCacheProvider](https://www.nuget.org/packages/Microsoft.AspNet.OutputCache.SQLAsyncOutputCacheProvider/)
36+
37+
This will add a reference to the necessary assemblies and configuration similar to the following into the `web.config` file.
38+
39+
```xml
40+
<system.web>
41+
<caching>
42+
<outputCache defaultProvider="SQLAsyncOutputCacheProvider">
43+
<providers>
44+
<add name="SQLAsyncOutputCacheProvider" connectionStringName="DefaultConnection" UseInMemoryTable="[true|false]"
45+
type="Microsoft.AspNet.OutputCache.SQLAsyncOutputCacheProvider.SQLAsyncOutputCacheProvider, Microsoft.AspNet.OutputCache.SQLAsyncOutputCacheProvider, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
46+
</providers>
47+
</outputCache>
48+
</caching>
49+
</system.web>
50+
```
51+
52+
1. **Further Configuration**
53+
54+
Be sure that `web.config` includes both the connection string and the `OutputCacheModuleAsync` configuration:
55+
56+
```xml
57+
<configuration>
58+
<connectionStrings>
59+
<add name="SQLOutputCache"
60+
connectionString="Data Source=<myserver>;Initial Catalog=OutputCache;Integrated Security=True"
61+
providerName="System.Data.SqlClient" />
62+
</connectionStrings>
63+
64+
<system.webServer>
65+
<modules>
66+
<remove name="OutputCache" />
67+
<add name="OutputCache"
68+
type="Microsoft.AspNet.OutputCache.OutputCacheModuleAsync, Microsoft.AspNet.OutputCache.OutputCacheModuleAsync"
69+
preCondition="integratedMode" />
70+
</modules>
71+
</system.webServer>
72+
</configuration>
73+
```
74+
75+
## Updates
76+
77+
### v1.0.1
78+
79+
- Initial release.

0 commit comments

Comments
 (0)