Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 5e0591b

Browse files
r4m-semeyonr4m-semeyon
authored
Merge pull request #20 from yurii-bart/notes-api-v5-mvp
Notes api v5 mvp
2 parents f2da7c9 + b8866f3 commit 5e0591b

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

45 files changed

+4347
-8
lines changed

‎.github/copilot-review-instructions.md‎

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
# GitHub Copilot Review Instructions for Route4Me .NET Core SDK
2+
3+
## Project Overview
4+
This is the Route4Me Route Optimization SaaS C# SDK (.NET Core framework) that provides a comprehensive API wrapper for route optimization, fleet management, and logistics operations. The SDK supports both V4 and V5 API versions with a focus on performance, reliability, and maintainability.
5+
6+
## Architecture & Design Patterns
7+
8+
### Manager Pattern
9+
- **Base Class**: All managers inherit from `Route4MeManagerBase`
10+
- **Naming Convention**: `{Domain}ManagerV5` (e.g., `OptimizationManagerV5`, `VehicleManagerV5`)
11+
- **Constructor**: Always takes `string apiKey` parameter
12+
- **API Methods**: Provide both synchronous and asynchronous versions
13+
- **Return Pattern**: Use `out ResultResponse resultResponse` for error handling
14+
15+
```csharp
16+
public class ExampleManagerV5 : Route4MeManagerBase
17+
{
18+
public ExampleManagerV5(string apiKey) : base(apiKey) { }
19+
20+
public DataType GetData(Parameters parameters, out ResultResponse resultResponse)
21+
{
22+
return GetJsonObjectFromAPI<DataType>(parameters, url, HttpMethodType.Get, out resultResponse);
23+
}
24+
25+
public async Task<Tuple<DataType, ResultResponse>> GetDataAsync(Parameters parameters)
26+
{
27+
var result = await GetJsonObjectFromAPIAsync<DataType>(parameters, url, HttpMethodType.Get);
28+
return new Tuple<DataType, ResultResponse>(result.Item1, result.Item2);
29+
}
30+
}
31+
```
32+
33+
### Data Types & Serialization
34+
- **DataContract**: All data types use `[DataContract]` and `[DataMember]` attributes
35+
- **JSON Mapping**: Use `[DataMember(Name = "json_property_name")]` for API field mapping
36+
- **Documentation**: Include comprehensive XML documentation for all public properties
37+
- **Versioning**: V5 types are in `Route4MeSDK.DataTypes.V5` namespace
38+
39+
```csharp
40+
[DataContract]
41+
public class ExampleResponse
42+
{
43+
/// <summary>
44+
/// Detailed description of the property and its purpose
45+
/// </summary>
46+
[DataMember(Name = "property_name")]
47+
public string PropertyName { get; set; }
48+
}
49+
```
50+
51+
### Error Handling
52+
- **ResultResponse**: Use `ResultResponse` class for consistent error handling
53+
- **Exception Types**: Catch specific exceptions (`HttpListenerException`, `Exception`)
54+
- **Error Messages**: Structure errors in `Dictionary<string, string[]>` format
55+
- **Status Codes**: Always check `response.IsSuccessStatusCode`
56+
57+
```csharp
58+
catch (HttpListenerException e)
59+
{
60+
resultResponse = new ResultResponse
61+
{
62+
Status = false,
63+
Messages = new Dictionary<string, string[]>
64+
{
65+
{"Error", new[] {e.Message}}
66+
}
67+
};
68+
}
69+
```
70+
71+
## Code Quality Standards
72+
73+
### Documentation Requirements
74+
- **XML Documentation**: All public methods, properties, and classes must have comprehensive XML documentation
75+
- **Parameter Documentation**: Document all parameters with purpose and constraints
76+
- **Return Documentation**: Document return values and possible error conditions
77+
- **Example Usage**: Include usage examples in complex method documentation
78+
79+
### Naming Conventions
80+
- **Classes**: PascalCase (e.g., `OptimizationManagerV5`)
81+
- **Methods**: PascalCase (e.g., `GetVehicles`, `CreateOrder`)
82+
- **Properties**: PascalCase (e.g., `RouteId`, `MemberEmail`)
83+
- **Parameters**: camelCase (e.g., `vehicleParams`, `optimizationParameters`)
84+
- **Private Fields**: camelCase with underscore prefix (e.g., `_apiKey`)
85+
86+
### Async/Await Patterns
87+
- **Async Methods**: Always provide async versions of public API methods
88+
- **ConfigureAwait**: Use `.ConfigureAwait(false)` in library code
89+
- **Return Types**: Use `Task<Tuple<T, ResultResponse>>` for async methods
90+
- **Cancellation**: Support `CancellationToken` where appropriate
91+
92+
### HTTP Client Management
93+
- **HttpClientHolder**: Use `HttpClientHolderManager.AcquireHttpClientHolder()` for HTTP client management
94+
- **Disposal**: Always use `using` statements for HTTP client holders
95+
- **V5 Detection**: Use `R4MeUtils.IsV5(url)` to determine API version
96+
- **Authentication**: Pass API key to V5 endpoints via HTTP client holder
97+
98+
## API Integration Patterns
99+
100+
### URL Construction
101+
- **Base URLs**: Use constants from `R4MEInfrastructureSettings` and `R4MEInfrastructureSettingsV5`
102+
- **Parameter Serialization**: Use `optimizationParameters.Serialize(v5 ? null : ApiKey)`
103+
- **Query Parameters**: Append serialized parameters to base URL
104+
105+
### HTTP Methods
106+
- **GET**: For data retrieval operations
107+
- **POST**: For creation operations
108+
- **PUT**: For full updates
109+
- **PATCH**: For partial updates
110+
- **DELETE**: For deletion operations
111+
112+
### Content Handling
113+
- **JSON Content**: Use `StringContent` with `application/json` content type
114+
- **PATCH Content**: Use `application/json-patch+json` for PATCH operations
115+
- **Stream Processing**: Handle both `StreamContent` and other content types
116+
117+
## Testing & Examples
118+
119+
### Test Structure
120+
- **Example Classes**: Use `Route4MeExamples` partial class for examples
121+
- **Test Data**: Use `ActualApiKey` and `DemoApiKey` from configuration
122+
- **Cleanup**: Always clean up test data using removal lists
123+
- **CRUD Operations**: Follow Create-Read-Update-Delete pattern in examples
124+
125+
### Configuration
126+
- **API Keys**: Store in `appsettings.json` with `actualApiKey` and `demoApiKey`
127+
- **Environment**: Support both production and demo environments
128+
- **Settings**: Use `R4MeUtils.ReadSetting()` for configuration access
129+
130+
## Performance Considerations
131+
132+
### HTTP Client Reuse
133+
- **Connection Pooling**: Leverage `HttpClientHolderManager` for connection reuse
134+
- **Timeout Handling**: Implement appropriate timeout values
135+
- **Retry Logic**: Consider implementing retry mechanisms for transient failures
136+
137+
### Memory Management
138+
- **Disposal**: Properly dispose of HTTP clients and streams
139+
- **Large Responses**: Handle large response streams efficiently
140+
- **Object Pooling**: Consider object pooling for frequently created objects
141+
142+
## Security Guidelines
143+
144+
### API Key Management
145+
- **Secure Storage**: Never hardcode API keys in source code
146+
- **Environment Variables**: Use configuration files or environment variables
147+
- **Key Rotation**: Support API key rotation without code changes
148+
149+
### Data Validation
150+
- **Input Validation**: Validate all input parameters
151+
- **Sanitization**: Sanitize user inputs before API calls
152+
- **Error Information**: Avoid exposing sensitive information in error messages
153+
154+
## Version Compatibility
155+
156+
### V4 vs V5 APIs
157+
- **Version Detection**: Use `R4MeUtils.IsV5(url)` for version-specific logic
158+
- **Backward Compatibility**: Maintain V4 support while adding V5 features
159+
- **Namespace Separation**: Keep V5 types in separate namespaces
160+
- **Manager Separation**: Use separate manager classes for V4 and V5
161+
162+
### .NET Standard
163+
- **Target Framework**: Maintain `netstandard2.0` compatibility
164+
- **Dependencies**: Use compatible package versions
165+
- **Cross-Platform**: Ensure cross-platform compatibility
166+
167+
## Code Review Checklist
168+
169+
### Before Submitting
170+
- [ ] All public methods have XML documentation
171+
- [ ] Both sync and async versions provided for API methods
172+
- [ ] Proper error handling with `ResultResponse`
173+
- [ ] HTTP client properly disposed
174+
- [ ] API version detection implemented correctly
175+
- [ ] Test examples provided for new functionality
176+
- [ ] Configuration properly externalized
177+
- [ ] No hardcoded values or API keys
178+
179+
### Code Quality
180+
- [ ] Follows established naming conventions
181+
- [ ] Uses appropriate design patterns
182+
- [ ] Handles exceptions properly
183+
- [ ] Implements proper disposal patterns
184+
- [ ] Uses async/await correctly
185+
- [ ] Includes comprehensive error messages
186+
- [ ] Maintains backward compatibility
187+
188+
### Testing
189+
- [ ] Example code provided
190+
- [ ] Test data cleanup implemented
191+
- [ ] Both success and error scenarios covered
192+
- [ ] Configuration properly set up
193+
- [ ] Documentation matches implementation
194+
195+
## Common Pitfalls to Avoid
196+
197+
1. **Hardcoded API Keys**: Never commit API keys to source control
198+
2. **Missing Async Methods**: Always provide async versions of public API methods
199+
3. **Improper Disposal**: Always dispose of HTTP clients and streams
200+
4. **Generic Exception Handling**: Catch specific exception types, not just `Exception`
201+
5. **Missing Documentation**: All public APIs must be documented
202+
6. **Version Mixing**: Don't mix V4 and V5 logic in the same method
203+
7. **Memory Leaks**: Ensure proper disposal of disposable resources
204+
8. **Inconsistent Error Handling**: Use `ResultResponse` consistently
205+
206+
## Dependencies & Packages
207+
208+
### Core Dependencies
209+
- `Newtonsoft.Json` (13.0.2) - JSON serialization
210+
- `Microsoft.Extensions.Configuration.*` - Configuration management
211+
- `System.Collections.Immutable` - Immutable collections
212+
- `System.ComponentModel.Annotations` - Data annotations
213+
214+
### Development Dependencies
215+
- `CsvHelper` - CSV file processing
216+
- `fastJSON` - Alternative JSON processing
217+
- `SocketIoClientDotNet.Standard` - WebSocket support
218+
219+
## Release & Versioning
220+
221+
### Version Management
222+
- **Semantic Versioning**: Follow semantic versioning principles
223+
- **Changelog**: Maintain detailed changelog in `CHANGELOG.md`
224+
- **Assembly Signing**: Use strong name signing with `r4m_csharp_sdk.snk`
225+
- **Package Metadata**: Keep package metadata up to date
226+
227+
### Distribution
228+
- **NuGet Package**: Publish to NuGet with proper metadata
229+
- **GitHub Releases**: Tag releases in GitHub
230+
- **Documentation**: Update README and examples for new features
231+
232+
---
233+
234+
*This document should be reviewed and updated as the project evolves. All team members should familiarize themselves with these guidelines before contributing to the codebase.*

‎Dockerfile‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# =============================================================================
2+
# Dockerfile for Route4Me C# SDK Testing Environment
3+
#
4+
# This Dockerfile creates a containerized environment for building and testing
5+
# the Route4Me C# SDK, based on the Travis CI configuration.
6+
#
7+
# Usage:
8+
# Build: docker build -t route4me-sdk-test .
9+
# Run tests: docker run --rm route4me-sdk-test
10+
# Interactive shell: docker run -it --rm route4me-sdk-test /bin/bash
11+
#
12+
# =============================================================================
13+
14+
# Use the official .NET 6.0 SDK image as base
15+
# This provides both build and runtime capabilities for .NET 6.0 projects
16+
# Specify platform to avoid QEMU emulation issues on Apple Silicon
17+
FROM --platform=linux/amd64 mcr.microsoft.com/dotnet/sdk:6.0 AS base
18+
19+
# Set environment variables for non-interactive installation
20+
ENV DEBIAN_FRONTEND=noninteractive
21+
ENV DOTNET_CLI_TELEMETRY_OPTOUT=1
22+
ENV DOTNET_SKIP_FIRST_TIME_EXPERIENCE=1
23+
24+
# Install additional dependencies that might be needed for testing
25+
# and development tools
26+
RUN apt-get update && apt-get install -y \
27+
git \
28+
curl \
29+
wget \
30+
unzip \
31+
ca-certificates \
32+
&& rm -rf /var/lib/apt/lists/*
33+
34+
# Set the working directory
35+
WORKDIR /app
36+
37+
# Copy the entire project structure
38+
# This includes all source code, test projects, and data files
39+
COPY . .
40+
41+
# =============================================================================
42+
# Build Stage
43+
# =============================================================================
44+
FROM base AS build
45+
46+
# Restore dependencies for the entire solution
47+
# This matches the Travis CI command: dotnet restore ./route4me-csharp-sdk/Route4MeSDK.sln
48+
RUN dotnet restore ./route4me-csharp-sdk/Route4MeSDK.sln
49+
50+
# Build the SDK library
51+
# Note: SDK library targets netstandard2.0, so no framework override needed
52+
RUN dotnet build -v q -c Release ./route4me-csharp-sdk/Route4MeSDKLibrary/Route4MeSDKLibrary.csproj
53+
54+
# Build the unit test projects
55+
# Note: Test projects target net6.0, so no framework override needed
56+
RUN dotnet build -v q -c Release ./route4me-csharp-sdk/Route4MeSDKUnitTest/Route4MeSDKUnitTest.csproj
57+
RUN dotnet build -v q -c Release ./route4me-csharp-sdk/Route4MeSdkV5UnitTest/Route4MeSdkV5UnitTest.csproj
58+
59+
# =============================================================================
60+
# Test Stage
61+
# =============================================================================
62+
FROM build AS test
63+
64+
# Set the working directory to the SDK folder
65+
WORKDIR /app/route4me-csharp-sdk
66+
67+
# Run the unit tests
68+
# Note: Test projects target net6.0, so no framework override needed
69+
RUN dotnet test -v n -p:ParallelizeTestCollections=false -c Release --filter Category!=Beacon ./Route4MeSDKUnitTest/Route4MeSDKUnitTest.csproj
70+
71+
# Run the V5 unit tests as well
72+
RUN dotnet test -v n -p:ParallelizeTestCollections=false -c Release ./Route4MeSdkV5UnitTest/Route4MeSdkV5UnitTest.csproj
73+
74+
# =============================================================================
75+
# Development Stage
76+
# =============================================================================
77+
FROM build AS development
78+
79+
# Set the working directory to the SDK folder
80+
WORKDIR /app/route4me-csharp-sdk
81+
82+
# Create a script to run all tests
83+
RUN echo '#!/bin/bash\n\
84+
echo "Running Route4Me SDK Tests..."\n\
85+
echo "================================"\n\
86+
\n\
87+
echo "Running Unit Tests (excluding Beacon category)..."\n\
88+
dotnet test -v n -p:ParallelizeTestCollections=false -c Release --filter Category!=Beacon ./Route4MeSDKUnitTest/Route4MeSDKUnitTest.csproj\n\
89+
\n\
90+
echo "Running V5 Unit Tests..."\n\
91+
dotnet test -v n -p:ParallelizeTestCollections=false -c Release ./Route4MeSdkV5UnitTest/Route4MeSdkV5UnitTest.csproj\n\
92+
\n\
93+
echo "All tests completed!"\n\
94+
' > /usr/local/bin/run-tests.sh && chmod +x /usr/local/bin/run-tests.sh
95+
96+
# Create a script to build the solution
97+
RUN echo '#!/bin/bash\n\
98+
echo "Building Route4Me SDK..."\n\
99+
echo "========================"\n\
100+
\n\
101+
echo "Restoring dependencies..."\n\
102+
dotnet restore ./Route4MeSDK.sln\n\
103+
\n\
104+
echo "Building SDK Library..."\n\
105+
dotnet build -v q -c Release ./Route4MeSDKLibrary/Route4MeSDKLibrary.csproj\n\
106+
\n\
107+
echo "Building Unit Test projects..."\n\
108+
dotnet build -v q -c Release ./Route4MeSDKUnitTest/Route4MeSDKUnitTest.csproj\n\
109+
dotnet build -v q -c Release ./Route4MeSdkV5UnitTest/Route4MeSdkV5UnitTest.csproj\n\
110+
\n\
111+
echo "Build completed!"\n\
112+
' > /usr/local/bin/build-sdk.sh && chmod +x /usr/local/bin/build-sdk.sh
113+
114+
# Set the default command to run tests
115+
# CMD ["/usr/local/bin/run-tests.sh"]
116+

0 commit comments

Comments
 (0)