Skip to content

Commit 13f803f

Browse files
JDetmarJDetmar
authored
Add devcontainer configuration and enhance Azure targets with documen… (#167)
* Add devcontainer configuration and enhance Azure targets with documentation and properties * Enhance documentation for Azure Event Grid target properties to clarify authentication usage
1 parent 199cef8 commit 13f803f

File tree

19 files changed

+222
-180
lines changed

19 files changed

+222
-180
lines changed

‎.devcontainer/devcontainer.json‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
{
2+
"name": "NLog.Extensions.AzureStorage",
3+
"image": "mcr.microsoft.com/devcontainers/dotnet:1-8.0-jammy",
4+
"features": {
5+
"ghcr.io/devcontainers/features/github-cli:1": {}
6+
},
7+
"customizations": {
8+
"vscode": {
9+
"extensions": [
10+
"ms-dotnettools.csharp",
11+
"ms-dotnettools.vscode-dotnet-runtime"
12+
],
13+
"settings": {
14+
"dotnet.defaultSolution": "src/NLog.Extensions.AzureStorage.sln"
15+
}
16+
}
17+
},
18+
"postCreateCommand": "dotnet restore src/NLog.Extensions.AzureStorage.sln"
19+
}

‎src/NLog.Extensions.AzureAccessToken/NLog.Extensions.AzureAccessToken.csproj‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@
44
<TargetFrameworks>netstandard2.0;netstandard1.4;net461;net452</TargetFrameworks>
55
<DisableImplicitFrameworkReferences Condition=" '$(TargetFramework)' == 'net452' Or '$(TargetFramework)' == 'net461' ">true</DisableImplicitFrameworkReferences>
66
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
7+
<GenerateDocumentationFile>true</GenerateDocumentationFile>
8+
<RepositoryBranch>master</RepositoryBranch>
9+
<IncludeSymbols>true</IncludeSymbols>
10+
<SymbolPackageFormat>snupkg</SymbolPackageFormat>
711

812
<Version>2.3.0</Version>
913

‎src/NLog.Extensions.AzureBlobStorage/BlobStorageTarget.cs‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,9 @@ public sealed class BlobStorageTarget : AsyncTaskTarget
2727
//Delegates for bucket sorting
2828
private SortHelpers.KeySelector<LogEventInfo, ContainerBlobKey> _getContainerBlobNameDelegate;
2929

30+
/// <summary>
31+
/// Gets or sets the Azure Storage connection string. Alternative to <see cref="ServiceUri"/>.
32+
/// </summary>
3033
public Layout ConnectionString { get; set; }
3134

3235
/// <summary>
@@ -108,6 +111,9 @@ public sealed class BlobStorageTarget : AsyncTaskTarget
108111
[RequiredParameter]
109112
public Layout Container { get; set; }
110113

114+
/// <summary>
115+
/// Gets or sets the Azure Blob Storage container name.
116+
/// </summary>
111117
[System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Never)]
112118
[Obsolete("Instead use Container")]
113119
public Layout ContainerName { get => Container; set => Container = value; }
@@ -118,14 +124,27 @@ public sealed class BlobStorageTarget : AsyncTaskTarget
118124
[RequiredParameter]
119125
public Layout BlobName { get; set; }
120126

127+
/// <summary>
128+
/// Gets or sets the MIME content type for blob storage.
129+
/// </summary>
130+
/// <remarks>Default: "text/plain"</remarks>
121131
public string ContentType { get; set; } = "text/plain";
122132

133+
/// <summary>
134+
/// Gets the collection of custom metadata key-value pairs to attach to the blob.
135+
/// </summary>
123136
[ArrayParameter(typeof(TargetPropertyWithContext), "metadata")]
124137
public IList<TargetPropertyWithContext> BlobMetadata { get; private set; }
125138

139+
/// <summary>
140+
/// Gets the collection of blob tags for categorization and filtering.
141+
/// </summary>
126142
[ArrayParameter(typeof(TargetPropertyWithContext), "tag")]
127143
public IList<TargetPropertyWithContext> BlobTags { get; private set; }
128144

145+
/// <summary>
146+
/// Initializes a new instance of the <see cref="BlobStorageTarget"/> class.
147+
/// </summary>
129148
public BlobStorageTarget()
130149
:this(new CloudBlobService())
131150
{
@@ -226,6 +245,11 @@ protected override void InitializeTarget()
226245
}
227246
}
228247

248+
/// <summary>
249+
/// Override this to provide async task for writing a single logevent.
250+
/// </summary>
251+
/// <param name="logEvent">The log event.</param>
252+
/// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
229253
protected override Task WriteAsyncTask(LogEventInfo logEvent, CancellationToken cancellationToken)
230254
{
231255
throw new NotImplementedException();
@@ -237,6 +261,7 @@ protected override Task WriteAsyncTask(LogEventInfo logEvent, CancellationToken
237261
/// optimize batch writes.
238262
/// </summary>
239263
/// <param name="logEvents">Logging events to be written out.</param>
264+
/// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
240265
protected override Task WriteAsyncTask(IList<LogEventInfo> logEvents, CancellationToken cancellationToken)
241266
{
242267
//must sort into containers and then into the blobs for the container
@@ -502,6 +527,9 @@ async Task<AppendBlobClient> InitializeAndCacheBlobAsync(string containerName, s
502527
/// Initializes the BLOB.
503528
/// </summary>
504529
/// <param name="blobName">Name of the BLOB.</param>
530+
/// <param name="blobContainer">The blob container client.</param>
531+
/// <param name="contentType">MIME content type for the blob.</param>
532+
/// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
505533
private async Task<AppendBlobClient> InitializeBlob(string blobName, BlobContainerClient blobContainer, string contentType, CancellationToken cancellationToken)
506534
{
507535
InternalLogger.Debug("AzureBlobStorageTarget: Initializing blob: {0}", blobName);
@@ -530,6 +558,7 @@ private async Task<AppendBlobClient> InitializeBlob(string blobName, BlobContain
530558
/// Initializes the Azure storage container and creates it if it doesn't exist.
531559
/// </summary>
532560
/// <param name="containerName">Name of the container.</param>
561+
/// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
533562
private async Task<BlobContainerClient> InitializeContainer(string containerName, CancellationToken cancellationToken)
534563
{
535564
if (_client == null)

‎src/NLog.Extensions.AzureBlobStorage/NLog.Extensions.AzureBlobStorage.csproj‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@
44
<TargetFrameworks>netstandard2.0;net8.0</TargetFrameworks>
55
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
66
<IsTrimmable Condition="$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net6.0'))">true</IsTrimmable>
7+
<GenerateDocumentationFile>true</GenerateDocumentationFile>
8+
<RepositoryBranch>master</RepositoryBranch>
9+
<IncludeSymbols>true</IncludeSymbols>
10+
<SymbolPackageFormat>snupkg</SymbolPackageFormat>
711

812
<Version>4.6.0</Version>
913

‎src/NLog.Extensions.AzureDataTables/DataTablesTarget.cs‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,13 @@ public override int GetHashCode()
5555
}
5656
}
5757

58+
/// <summary>
59+
/// Gets or sets the connection string for Azure Table Storage or Cosmos DB Table API.
60+
/// </summary>
5861
public Layout ConnectionString { get; set; }
62+
/// <summary>
63+
/// Gets or sets the name of the connection string stored in ConnectionStrings section of the config.
64+
/// </summary>
5965
public string ConnectionStringKey { get; set; }
6066

6167
/// <summary>
@@ -128,17 +134,32 @@ public override int GetHashCode()
128134
/// </summary>
129135
public Layout AccessKey { get; set; }
130136

137+
/// <summary>
138+
/// Gets or sets the name of the Azure table where log entries will be stored.
139+
/// </summary>
131140
[RequiredParameter]
132141
public Layout TableName { get; set; }
133142

143+
/// <summary>
144+
/// Gets or sets the partition key for table entries. Defaults to "${logger}".
145+
/// </summary>
134146
[RequiredParameter]
135147
public Layout PartitionKey { get; set; } = "${logger}";
136148

149+
/// <summary>
150+
/// Gets or sets the row key for table entries.
151+
/// </summary>
137152
[RequiredParameter]
138153
public Layout RowKey { get; set; }
139154

155+
/// <summary>
156+
/// Gets or sets the format string for log timestamps. Defaults to "O" (ISO 8601).
157+
/// </summary>
140158
public string LogTimeStampFormat { get; set; } = "O";
141159

160+
/// <summary>
161+
/// Initializes a new instance of the <see cref="DataTablesTarget"/> class.
162+
/// </summary>
142163
public DataTablesTarget()
143164
:this(new CloudTableService())
144165
{
@@ -205,11 +226,21 @@ protected override void InitializeTarget()
205226
}
206227
}
207228

229+
/// <summary>
230+
/// Override this to provide async task for writing a single logevent.
231+
/// </summary>
232+
/// <param name="logEvent">The log event.</param>
233+
/// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
208234
protected override Task WriteAsyncTask(LogEventInfo logEvent, CancellationToken cancellationToken)
209235
{
210236
throw new NotImplementedException();
211237
}
212238

239+
/// <summary>
240+
/// Override this to provide async task for writing multiple logevents in optimized batch operation.
241+
/// </summary>
242+
/// <param name="logEvents">The log events.</param>
243+
/// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
213244
protected override Task WriteAsyncTask(IList<LogEventInfo> logEvents, CancellationToken cancellationToken)
214245
{
215246
//must sort into containers and then into the blobs for the container

‎src/NLog.Extensions.AzureDataTables/NLog.Extensions.AzureDataTables.csproj‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@
44
<TargetFrameworks>netstandard2.0;net8.0</TargetFrameworks>
55
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
66
<IsTrimmable Condition="$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net6.0'))">true</IsTrimmable>
7+
<GenerateDocumentationFile>true</GenerateDocumentationFile>
8+
<RepositoryBranch>master</RepositoryBranch>
9+
<IncludeSymbols>true</IncludeSymbols>
10+
<SymbolPackageFormat>snupkg</SymbolPackageFormat>
711

812
<Version>4.6.0</Version>
913

‎src/NLog.Extensions.AzureDataTables/NLogEntity.cs‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,22 +4,73 @@
44

55
namespace NLog.Extensions.AzureStorage
66
{
7+
/// <summary>
8+
/// Represents a log entry entity for Azure Table Storage.
9+
/// </summary>
710
public class NLogEntity: ITableEntity
811
{
12+
/// <summary>
13+
/// Gets or sets the partition key of the table entity.
14+
/// </summary>
915
public string PartitionKey { get; set; }
16+
/// <summary>
17+
/// Gets or sets the row key of the table entity.
18+
/// </summary>
1019
public string RowKey { get; set; }
20+
/// <summary>
21+
/// Gets or sets the timestamp of the table entity.
22+
/// </summary>
1123
public DateTimeOffset? Timestamp { get; set; }
24+
/// <summary>
25+
/// Gets or sets the ETag of the table entity.
26+
/// </summary>
1227
public ETag ETag { get; set; }
28+
/// <summary>
29+
/// Gets or sets the formatted timestamp of the log event.
30+
/// </summary>
1331
public string LogTimeStamp { get; set; }
32+
/// <summary>
33+
/// Gets or sets the log level of the log event.
34+
/// </summary>
1435
public string Level { get; set; }
36+
/// <summary>
37+
/// Gets or sets the name of the logger that created the log event.
38+
/// </summary>
1539
public string LoggerName { get; set; }
40+
/// <summary>
41+
/// Gets or sets the log message.
42+
/// </summary>
1643
public string Message { get; set; }
44+
/// <summary>
45+
/// Gets or sets the exception information.
46+
/// </summary>
1747
public string Exception { get; set; }
48+
/// <summary>
49+
/// Gets or sets the inner exception information.
50+
/// </summary>
1851
public string InnerException { get; set; }
52+
/// <summary>
53+
/// Gets or sets the stack trace information.
54+
/// </summary>
1955
public string StackTrace { get; set; }
56+
/// <summary>
57+
/// Gets or sets the full formatted log message.
58+
/// </summary>
2059
public string FullMessage { get; set; }
60+
/// <summary>
61+
/// Gets or sets the name of the machine where the log event occurred.
62+
/// </summary>
2163
public string MachineName { get; set; }
2264

65+
/// <summary>
66+
/// Initializes a new instance of the <see cref="NLogEntity"/> class with log event data.
67+
/// </summary>
68+
/// <param name="logEvent">The log event information.</param>
69+
/// <param name="layoutMessage">The formatted layout message.</param>
70+
/// <param name="machineName">The machine name.</param>
71+
/// <param name="partitionKey">The partition key.</param>
72+
/// <param name="rowKey">The row key.</param>
73+
/// <param name="logTimeStampFormat">The timestamp format string.</param>
2374
public NLogEntity(LogEventInfo logEvent, string layoutMessage, string machineName, string partitionKey, string rowKey, string logTimeStampFormat)
2475
{
2576
FullMessage = TruncateWhenTooBig(layoutMessage);
@@ -72,6 +123,9 @@ private static string TruncateWhenTooBig(string stringValue)
72123
stringValue.Substring(0, Targets.DataTablesTarget.ColumnStringValueMaxSize - 1) : stringValue;
73124
}
74125

126+
/// <summary>
127+
/// Initializes a new instance of the <see cref="NLogEntity"/> class.
128+
/// </summary>
75129
public NLogEntity() { }
76130
}
77131
}

‎src/NLog.Extensions.AzureEventGrid/EventGridTarget.cs‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ public string DataFormat
7575
public Layout DataSchema { get; set; }
7676

7777
/// <summary>
78-
/// TenantId for <see cref="Azure.Identity.DefaultAzureCredentialOptions"/>. Requires <see cref="ServiceUri"/>.
78+
/// TenantId for <see cref="Azure.Identity.DefaultAzureCredentialOptions"/>. Used with DefaultAzureCredential authentication when connecting to the Event Grid topic endpoint.
7979
/// </summary>
8080
public Layout TenantIdentity { get; set; }
8181

@@ -87,7 +87,7 @@ public string DataFormat
8787
public Layout ResourceIdentity { get => ManagedIdentityResourceId; set => ManagedIdentityResourceId = value; }
8888

8989
/// <summary>
90-
/// ResourceId for <see cref="Azure.Identity.DefaultAzureCredentialOptions.ManagedIdentityResourceId"/> on <see cref="Azure.Identity.DefaultAzureCredentialOptions"/>. Requires <see cref="ServiceUri"/> .
90+
/// ResourceId for <see cref="Azure.Identity.DefaultAzureCredentialOptions.ManagedIdentityResourceId"/> on <see cref="Azure.Identity.DefaultAzureCredentialOptions"/>. Used with managed identity authentication when connecting to the Event Grid topic endpoint.
9191
/// </summary>
9292
/// <remarks>
9393
/// Do not configure this value together with <see cref="ManagedIdentityClientId"/>
@@ -102,20 +102,20 @@ public string DataFormat
102102
public Layout ClientIdentity { get => ManagedIdentityClientId; set => ManagedIdentityClientId = value; }
103103

104104
/// <summary>
105-
/// ManagedIdentityClientId for <see cref="Azure.Identity.DefaultAzureCredentialOptions"/>. Requires <see cref="ServiceUri"/>.
105+
/// ManagedIdentityClientId for <see cref="Azure.Identity.DefaultAzureCredentialOptions"/>. Used with managed identity authentication when connecting to the Event Grid topic endpoint.
106106
/// </summary>
107107
/// <remarks>
108108
/// If this value is configured, then <see cref="ManagedIdentityResourceId"/> should not be configured.
109109
/// </remarks>
110110
public Layout ManagedIdentityClientId { get; set; }
111111

112112
/// <summary>
113-
/// AccessKey for <see cref="Azure.AzureKeyCredential"/> authentication. Requires <see cref="ServiceUri"/>.
113+
/// AccessKey for <see cref="Azure.AzureKeyCredential"/> authentication. Used with key-based authentication when connecting to the Event Grid topic endpoint.
114114
/// </summary>
115115
public Layout AccessKey { get; set; }
116116

117117
/// <summary>
118-
/// Access signature for <see cref="Azure.AzureSasCredential"/> authentication. Requires <see cref="ServiceUri"/>.
118+
/// Access signature for <see cref="Azure.AzureSasCredential"/> authentication. Used with SAS token authentication when connecting to the Event Grid topic endpoint.
119119
/// </summary>
120120
public Layout SharedAccessSignature { get; set; }
121121

@@ -125,6 +125,9 @@ public string DataFormat
125125
[ArrayParameter(typeof(TargetPropertyWithContext), "messageproperty")]
126126
public IList<TargetPropertyWithContext> MessageProperties { get => ContextProperties; }
127127

128+
/// <summary>
129+
/// Initializes a new instance of the <see cref="EventGridTarget"/> class.
130+
/// </summary>
128131
public EventGridTarget()
129132
: this(new EventGridService())
130133
{
@@ -185,6 +188,11 @@ protected override void InitializeTarget()
185188
}
186189
}
187190

191+
/// <summary>
192+
/// Override this to provide async task for writing a single logevent.
193+
/// </summary>
194+
/// <param name="logEvent">The log event.</param>
195+
/// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
188196
protected override Task WriteAsyncTask(LogEventInfo logEvent, CancellationToken cancellationToken)
189197
{
190198
try

‎src/NLog.Extensions.AzureEventGrid/NLog.Extensions.AzureEventGrid.csproj‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@
44
<TargetFrameworks>netstandard2.0;net8.0</TargetFrameworks>
55
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
66
<IsTrimmable Condition="$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net6.0'))">true</IsTrimmable>
7+
<GenerateDocumentationFile>true</GenerateDocumentationFile>
8+
<RepositoryBranch>master</RepositoryBranch>
9+
<IncludeSymbols>true</IncludeSymbols>
10+
<SymbolPackageFormat>snupkg</SymbolPackageFormat>
711

812
<Version>4.6.0</Version>
913

0 commit comments

Comments
 (0)