https://github.com/lusipad/azure2md
一个将 Azure DevOps 工作项导出为 Markdown 报告的工具。
https://github.com/lusipad/azure2md
azure markdown tfs
Last synced: 2 months ago
JSON representation
一个将 Azure DevOps 工作项导出为 Markdown 报告的工具。
- Host: GitHub
- URL: https://github.com/lusipad/azure2md
- Owner: lusipad
- License: mit
- Created: 2024-09-05T23:34:59.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-02-16T12:49:05.000Z (8 months ago)
- Last Synced: 2025-02-16T13:52:21.747Z (8 months ago)
- Topics: azure, markdown, tfs
- Language: C#
- Homepage:
- Size: 816 KB
- Stars: 0
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.en.md
- License: LICENSE
Awesome Lists containing this project
README
# Azure2Md
[English](README.en.md) | [简体中文](README.md)
A tool to export Azure DevOps/TFS work items to Markdown reports.
## Features
- Support for Azure DevOps and TFS 2022
- Support for both HTTPS and HTTP connections
- Support for multiple project work item export
- Support for merged or individual project reports
- Support for complete work item hierarchy (Feature -> User Story -> Task)
- Generate multi-level Gantt chart views
- Feature + User Story view
- User Story + Task view
- Group tasks by team members
- Support for custom queries or existing queries
- Display complete work item time information
- Support for task status visualization (active/done)
- Support for multiple languages (Chinese/English/auto-detect)
- Support for custom Gantt chart display options
- Support for custom time field mappings
## Configuration
Configure in `appsettings.json`:
```json
{
"TfsUrl": "https://dev.azure.com/your-organization", // Azure DevOps URL
// Or use TFS URL, for example:
// "TfsUrl": "http://tfs.your-company.com:8080/tfs/DefaultCollection",
"PersonalAccessToken": "your-pat-token",
"ReportSettings": {
"MergeProjects": true,
"MergedTitle": "Multi-Project Report",
"Language": "auto", // Options: auto, zh-CN, en-US
"DisplayOptions": {
"ShowFeatureInGantt": true, // Whether to show Feature in Gantt chart
"ShowUserStoryInGantt": true, // Whether to show User Story in Gantt chart
"PrefixParentName": true // Whether to show parent name before child item
}
},
"Projects": [
{
"ProjectName": "project-name",
"Query": {
"UseExistingQuery": false,
"QueryPath": "Shared Queries/query-path",
"CustomWiql": null
},
"FieldMappings": {
"Feature": {
"StartDateField": "Custom.FeatureStartDate",
"EndDateField": "Custom.FeatureEndDate"
},
"UserStory": {
"StartDateField": "Custom.StoryStartDate",
"EndDateField": "Custom.StoryEndDate"
},
"Task": {
"StartDateField": "Custom.TaskStartDate",
"EndDateField": "Custom.TaskEndDate"
}
}
}
]
}
```
### Configuration Items
- `TfsUrl`:
- Azure DevOps URL format: `https://dev.azure.com/your-organization`
- TFS URL format: `http://tfs-server:port/tfs/collection-name`
- Supports both HTTP and HTTPS protocols
- `PersonalAccessToken`: Personal Access Token (PAT)
- `ReportSettings`: Report generation settings
- `MergeProjects`: Whether to merge multiple project reports
- `MergedTitle`: Title for merged report
- `Language`: Language settings
- `auto`: Auto-detect system language
- `zh-CN`: Force Chinese
- `en-US`: Force English
- `DisplayOptions`: Display options
- `ShowFeatureInGantt`: Whether to show Feature nodes in Gantt chart
- `ShowUserStoryInGantt`: Whether to show User Story nodes in Gantt chart
- `PrefixParentName`: Whether to add parent name before child items
- `Projects`: Project configuration list
- `ProjectName`: Project name
- `Query`: Query configuration
- `UseExistingQuery`: Whether to use existing query
- `QueryPath`: Path to existing query
- `CustomWiql`: Custom WIQL query (optional)
- `FieldMappings`: Time field mapping configuration
- `Feature`: Feature work item type field mapping
- `StartDateField`: Start date field name
- `EndDateField`: End date field name
- `UserStory`: User Story work item type field mapping
- `StartDateField`: Start date field name
- `EndDateField`: End date field name
- `Task`: Task work item type field mapping
- `StartDateField`: Start date field name
- `EndDateField`: End date field name
### Time Field Mapping
- If FieldMappings is not configured or fields are empty, default fields will be used:
- Start date: `Microsoft.VSTS.Scheduling.StartDate`
- End date: `Microsoft.VSTS.Scheduling.FinishDate`
- Different work item types can use different time fields
- Custom fields must use complete field reference names (e.g., `Custom.FieldName`)
- If a field doesn't exist or is empty, default durations will be used:
- Feature type default duration: 30 days
- User Story type default duration: 14 days
- Task type default duration: 7 days
## Connection Guide
### Azure DevOps Connection
- Uses HTTPS protocol
- URL format: `https://dev.azure.com/organization-name`
- Requires valid PAT token
### TFS 2022 Connection
- Supports both HTTP and HTTPS protocols
- URL format: `http(s)://server:port/tfs/collection-name`
- For HTTP connections:
- Tool automatically handles certificate validation
- Auto-configures security protocols
- Supports self-signed certificates
- Connection troubleshooting:
- Verify URL format is correct
- Ensure server is accessible
- Verify PAT token is valid
- Check network proxy settings
## Gantt Chart Display
1. Parent-Child Display
- When `ShowFeatureInGantt` is true, shows Feature nodes
- When `ShowUserStoryInGantt` is true, shows User Story nodes
- Child items are always shown
2. Name Display
- When `PrefixParentName` is true:
- User Story shows as: `Feature Name - User Story Name`
- Task shows as: `User Story Name - Task Name`
- When `PrefixParentName` is false, shows only item's own name
3. Node Type Identification
- Feature nodes show as: `Name (Feature)`
- User Story nodes show as: `Name (Story)`
- Task nodes show without type identifier
## Generated Report Content
### Merged Report Mode
1. Overall Overview
- Work item statistics for all projects
- Count of completed and active items
2. Project Statistics
- Work item statistics by project
- Completion status by project
3. Overall Gantt Charts
- Feature level view
- User Story level view
4. Work Item Categories
- Features list (with start and end dates)
- User Stories list (with start/end dates and parent Feature)
- Tasks list (with start/end dates and parent Story)
5. Team Member Task Assignment
- Gantt chart for each member
- Personal work item list (with start and end dates)
### Individual Report Mode
Each project generates a separate report containing:
1. Project Overview
- Total work items
- Completed items count
- Active items count
2. Project Gantt Charts
- Feature level view
- User Story level view
3. Work Item Categories
- User Stories (with start and end dates)
- Tasks (with start/end dates and parent Story)
4. Team Member Task Assignment
- Personal Gantt chart
- Personal work item list (with start and end dates)
## Status Mapping
Work item status mapping rules:
- Done status (done): done, closed, completed, resolved, removed
- Active status (active): active, in progress, doing
- Other status: shown as normal tasks
## Dependencies
- .NET 8.0
- Microsoft.TeamFoundationServer.Client
- Microsoft.VisualStudio.Services.Client
- Newtonsoft.Json
## Notes
- Requires valid Azure DevOps/TFS PAT token
- PAT needs work item read permissions
- Supported work item types: Feature, User Story, and Task
- Time display uses local timezone
- Merged report mode combines all project work items into one report
- Auto language setting detects system language
## Sample Report
